CONTRIBUTING.org

 1#+title: contributing to gitbay
 2
 3Development happens on [[https://gitbay.org/krz/gitbay][gitbay.org]] — gitbay is built with gitbay. GitHub
 4is not used.
 5
 6* Getting an account
 7
 8Registration is open. Register with the SSH key you will push with, and
 9the address that will receive the verification code:
10
11#+begin_src sh
12ssh git@gitbay.org register --username you --email you@example.org
13ssh git@gitbay.org email verify <code>       # the code arrives by mail
14#+end_src
15
16The account is active once the address is verified. The same signup is
17at [[https://gitbay.org/register][gitbay.org/register]] for a browser.
18
19* The workflow
20
211. Fork and branch:
22   #+begin_src sh
23   gitbay repo fork krz/gitbay          # or: ssh git@gitbay.org repo fork krz/gitbay
24   gitbay repo clone you/gitbay && cd gitbay
25   git checkout -b my-change
26   #+end_src
272. Make the change. =go build ./...= and =go test ./...= must be green —
28   the e2e suite drives real =git=, =ssh=, =sshd=, and =gpg= binaries and
29   takes about two minutes.
303. **Sign your commits.** =main= requires verified signatures: register
31   your signing key (=gitbay auth pgp add= for OpenPGP, or sign with a
32   registered SSH key) and make sure your author email is verified on
33   your account. Unsigned work cannot merge.
344. Push and open a merge request:
35   #+begin_src sh
36   git push origin my-change
37   gitbay mr create krz/gitbay --source you/gitbay:my-change --target main --title "..."
38   #+end_src
395. Merges are fast-forward only on =main=; if it moves under you, rebase
40   and re-push (your reviews go stale on force-push — that is by design).
41
42* What holds the design together
43
44Read the [[https://gitbay.org/krz/gitbay/wiki/Roadmap][roadmap]] (in the wiki) for direction. The invariants that reviews will
45hold you to:
46
47- every control command must work from bare OpenSSH; the registry test
48  enforces reachability, and the CLI stays a thin passthrough
49- one source of truth: SSH and the JSON API front the same handlers
50- the forge never executes repository content, and there is no server
51  signing key — server-created commits are honestly unsigned
52- private repositories are indistinguishable from nonexistent ones on
53  every surface
54- all git access goes through the =git= binary; no go-git
55- features land with e2e coverage against real binaries, not mocks
56
57* Style
58
59Plain, direct prose in code comments, commit messages, and docs — no
60hype, no filler. Commit messages state facts of the change. Match the
61surrounding code; keep diffs surgical.
62
63* Issues
64
65File at [[https://gitbay.org/krz/gitbay/issues][the tracker]] (=gitbay issue create= from a clone). Check
66the [[https://gitbay.org/krz/gitbay/wiki/Roadmap][roadmap]] (in the wiki) first — it maps the filed issues to phases.
67
68* License
69
700BSD. By contributing you agree your work is released under it. No CLA,
71no copyright assignment; sign-off lines are welcome but not required.