Skip to content

Commit 51034fe

Browse files
melvincarvalhomelvincarvalho
authored
docs: add CONTRIBUTING.md with workflow + AI-disclosure + fork policy (JavaScriptSolidServer#422) (JavaScriptSolidServer#425)
JSS had no `CONTRIBUTING.md` at the repo root. New contributors — human and agent — had to reverse-engineer the project's conventions from commit history. This adds a one-screen reference card surfacing what's already de-facto practice, plus formal stances on AI-assisted contributions and forks. Sections: - Quick start: clone / install / test / run - Workflow: issue → branch → PR → merge → pull (no direct commits to the default branch) - Code style: ESM, Node ≥ 22 LTS, no native modules, JSDoc, node --test, no build step - AI-assistance disclosure: three-tier disclosure (hand-authored / AI-assisted with review / substantially AI-generated), prompt sharing for substantial AI-generated portions, authorship responsibility stays with the contributor, per-contributor flexibility for established history. Aligns with NLnet's generative-AI policy for funded projects. - Forks and downstream distribution: AGPL-3.0 § 5(a) modification notice obligation on conveyed modified versions; happy to advise on application. - Licence and CLA: AGPL-3.0 default; CLA in progress, required for substantial contributions ahead of 0.1. - Where to ask: GitHub issue tracker is canonical; security issues via forthcoming SECURITY.md. References: - NLnet generative-AI policy: https://nlnet.nl/foundation/policies/generativeAI/ - AGPL-3.0 § 5(a): https://www.gnu.org/licenses/agpl-3.0.en.html#section5
1 parent 44a5ccb commit 51034fe

1 file changed

Lines changed: 98 additions & 0 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# Contributing to JSS
2+
3+
Thanks for your interest in contributing to JavaScript Solid Server (JSS).
4+
This document covers the conventions the project already follows. Aim is
5+
*reference card*, not tutorial — one screen, scannable.
6+
7+
## Quick start
8+
9+
```bash
10+
git clone https://github.com/JavaScriptSolidServer/JavaScriptSolidServer
11+
cd JavaScriptSolidServer
12+
npm install
13+
npm test # ~40s, 780+ tests
14+
node bin/jss.js # run a local pod
15+
```
16+
17+
## Workflow
18+
19+
The project follows a strict **issue → branch → PR → merge → pull** sequence.
20+
No direct commits to `gh-pages` (the default branch).
21+
22+
1. Open an issue describing the change (or pick an existing one)
23+
2. Branch: `git checkout -b issue-<number>-short-slug`
24+
3. Commit with a descriptive title + multi-paragraph body explaining the *why*
25+
(see existing history for the cadence)
26+
4. Open a PR linked to the issue
27+
5. Address Copilot review iteratively until clean (the project leans heavily
28+
on automated review passes)
29+
6. Squash-merge, delete branch, `git pull`
30+
31+
## Code style
32+
33+
- **ESM only**, Node ≥ 22 LTS
34+
- **No native modules** — runs unmodified on Termux, postmarketOS,
35+
Cloudflare Workers
36+
- **JSDoc** on public exports; inline `//` comments explain *why*, not *what*
37+
- **Tests via `node --test`** — no test framework dependency
38+
- **No build step** — the source you read is the source that runs
39+
40+
## AI-assistance disclosure
41+
42+
JSS welcomes thoughtfully-prepared contributions, including those drafted
43+
with AI assistance. To keep provenance clear:
44+
45+
- **Disclose AI assistance** in the PR description. Indicate one of:
46+
- hand-authored
47+
- AI-assisted with substantive human review
48+
- substantially AI-generated
49+
- **Share prompts** for substantial AI-generated portions (in the PR
50+
description or a linked artifact) so reviewers can assess scope.
51+
- **Authorship responsibility** — code review, follow-up, and licence
52+
obligations stay with the contributor regardless of AI involvement.
53+
- **Per-contributor flexibility** — established contributors with a
54+
consistent disclosure history may agree streamlined arrangements
55+
with the maintainer.
56+
57+
This is consistent with [NLnet's generative-AI policy for funded
58+
projects](https://nlnet.nl/foundation/policies/generativeAI/) and
59+
general open-source provenance best practice; it is not a JSS-specific
60+
imposition.
61+
62+
A PR template (`.github/pull_request_template.md`) carries the same
63+
checklist so every PR captures the disclosure inline.
64+
65+
## Forks and downstream distribution
66+
67+
JSS is AGPL-3.0. Forks are welcome.
68+
69+
The licence terms set the boundary: **§5(a)** requires a prominent
70+
modification notice on conveyed (deployed, published, or distributed)
71+
modified versions, with a relevant date. Forks operating a public
72+
deployment are encouraged to surface this notice on the deployment
73+
itself — about page, footer, response headers, or equivalent — so
74+
downstream users have visible provenance.
75+
76+
If you are forking and want to ensure §5(a) compliance, please open an
77+
issue or ping the maintainer; happy to advise on how to apply the
78+
notice cleanly.
79+
80+
## Licence and CLA
81+
82+
JSS is licensed under AGPL-3.0 (see `LICENSE`). All contributions are
83+
accepted under the same licence by default.
84+
85+
A Contributor Licence Agreement is being drafted and will be required
86+
for substantial contributions ahead of the `0.1` release; details and
87+
process will be published as part of that milestone work. Until then,
88+
the GitHub commit-via-PR flow constitutes acceptance of the project
89+
licence for the contributed change.
90+
91+
## Where to ask
92+
93+
- **Bugs / feature requests:** the GitHub issue tracker
94+
- **Security issues:** see `SECURITY.md` (forthcoming) for the
95+
responsible-disclosure path
96+
- **General questions:** ping the maintainer via the project's issue
97+
tracker; conversational venues are intentionally not listed here so
98+
the canonical record stays on GitHub

0 commit comments

Comments
 (0)