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 =make test= must be green. Use
28   =make test=, not a bare =go test ./...=: the e2e suite drives real
29   =git=, =ssh=, =sshd= and =gpg= binaries and takes six to fifteen
30   minutes depending on the machine, which is past =go test='s ten-minute
31   default. The bare command panics part way through and names whichever
32   test was running, which is not the one at fault.
333. **Sign your commits.** =main= requires verified signatures: register
34   your signing key (=gitbay auth pgp add= for OpenPGP, or sign with a
35   registered SSH key) and make sure your author email is verified on
36   your account. Unsigned work cannot merge.
374. Push and open a merge request:
38   #+begin_src sh
39   git push origin my-change
40   gitbay mr create krz/gitbay --source you/gitbay:my-change --target main --title "..."
41   #+end_src
425. Merges are fast-forward only on =main=; if it moves under you, rebase
43   and re-push (your reviews go stale on force-push — that is by design).
44
45* What holds the design together
46
47Read the [[https://gitbay.org/krz/gitbay/wiki/Roadmap][roadmap]] (in the wiki) for direction. The invariants that reviews will
48hold you to:
49
50- every control command must work from bare OpenSSH; the registry test
51  enforces reachability, and the CLI stays a thin passthrough
52- one source of truth: SSH and the JSON API front the same handlers
53- the forge never executes repository content, and there is no server
54  signing key — server-created commits are honestly unsigned
55- private repositories are indistinguishable from nonexistent ones on
56  every surface
57- all git access goes through the =git= binary; no go-git
58- features land with e2e coverage against real binaries, not mocks
59
60* Style
61
62Plain, direct prose in code comments, commit messages, and docs — no
63hype, no filler. Commit messages state facts of the change. Match the
64surrounding code; keep diffs surgical.
65
66* Issues
67
68File at [[https://gitbay.org/krz/gitbay/issues][the tracker]] (=gitbay issue create= from a clone). Check
69the [[https://gitbay.org/krz/gitbay/wiki/Roadmap][roadmap]] (in the wiki) first — it maps the filed issues to phases.
70
71* License
72
730BSD. By contributing you agree your work is released under it. No CLA,
74no copyright assignment; sign-off lines are welcome but not required.