shithub Public

Watch 1 Fork 0 Star 0
markdown · 3689 bytes Raw Blame History

Contributing to shithub

shithub is open to contributions from anyone. The project is post-launch (per S40); the workflow is the standard one.

By contributing, you certify that the work is yours to give and that you're licensing it to the project under the same terms as the rest of the codebase (AGPLv3). The mechanism is the Developer Certificate of Origin (DCO) v1.1 — sign off your commits with -s:

git commit -s -m "your message"

A CI check rejects PRs whose commits aren't signed off.

Code of conduct

Participation is governed by CODE_OF_CONDUCT.md. In short: be civil; harassment isn't tolerated; report issues to the email listed in that file.

Reporting bugs

For non-security bugs: open an issue on github.com/tenseleyFlow/shithub/issues.

For security issues: see SECURITY.md. Do not file public issues for security findings; the security mailbox is the disclosure path.

Development setup

git clone https://github.com/tenseleyFlow/shithub.git
cd shithub
make install-tools
make dev-db dev-storage    # Postgres + MinIO via docker compose
make dev-migrate           # apply migrations
make dev                   # hot-reload server on http://localhost:8080

Requires:

  • Go 1.22+ (developed against 1.26).
  • PostgreSQL 13+.
  • A local MinIO (or any S3-compatible store).
  • golangci-lint, gofumpt, goimports, air, sqlc (installed via make install-tools).

Copy .env.example to .env and fill in DB URL, session keys, and the TOTP/webhook AEAD keys.

Submitting a change

  1. Branch. From main, create a feature branch.
  2. Commit. Terse, imperative, single-line messages unless the change needs elaboration. One concern per commit. Avoid git add -A; stage by file.
  3. Test. Add tests proportional to the scope. Integration tests hit a real Postgres; we do not mock the DB seam. The bench harness (bench/) is the right home for performance regressions.
  4. Lint. make ci runs everything CI runs. PRs must be green.
  5. Push + PR. Open against main. The PR template prompts for a summary + test plan + reviewer notes.

Code style

  • gofumpt + goimports (run via make fmt).
  • golangci-lint per the in-repo config.
  • Package-boundary lints (markdown, policy, secret-logs, CSRF) are enforced via scripts/lint-*.sh. Adding a goldmark import outside internal/markdown will fail CI.
  • Comment style: lead with the why. Don't restate the code.
  • Migrations: forward-only by convention; down exists for emergency rollback only and may drop data.

Browser interactivity

HTMX is for partial-render swaps where a full page reload would feel jarring. SSE is for true streaming. Do not reach for either without a specific UX reason, and keep HTMX swap targets separate from SSE-owned log panes so polling cannot replace an active stream.

Reviewing

Maintainers (and other contributors with write access) review each PR. Aim for one approval before merge; protected branches enforce status checks + required reviews.

If you've left a "Request changes" review, please follow up within a few days — open PRs are a tax on the author.

Cutting a release

Maintainers only. The procedure is in docs/internal/runbooks/upgrade.md. Tag the release, push, run the deploy.

Communication

  • Discussion of features / RFCs: open an issue tagged proposal.
  • Day-to-day chat: the project doesn't run a Slack/Discord yet; PR comments and issues are the channel.
  • Security: security@shithub.sh (see SECURITY.md).
View source
1 # Contributing to shithub
2
3 shithub is open to contributions from anyone. The project is
4 post-launch (per S40); the workflow is the standard one.
5
6 By contributing, you certify that the work is yours to give and
7 that you're licensing it to the project under the same terms as
8 the rest of the codebase (AGPLv3). The mechanism is the
9 [Developer Certificate of Origin (DCO) v1.1](https://developercertificate.org/)
10 — sign off your commits with `-s`:
11
12 ```sh
13 git commit -s -m "your message"
14 ```
15
16 A CI check rejects PRs whose commits aren't signed off.
17
18 ## Code of conduct
19
20 Participation is governed by [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md).
21 In short: be civil; harassment isn't tolerated; report issues to
22 the email listed in that file.
23
24 ## Reporting bugs
25
26 For non-security bugs: open an issue on
27 [github.com/tenseleyFlow/shithub/issues](https://github.com/tenseleyFlow/shithub/issues).
28
29 For security issues: see [SECURITY.md](./SECURITY.md). Do **not**
30 file public issues for security findings; the security mailbox
31 is the disclosure path.
32
33 ## Development setup
34
35 ```sh
36 git clone https://github.com/tenseleyFlow/shithub.git
37 cd shithub
38 make install-tools
39 make dev-db dev-storage # Postgres + MinIO via docker compose
40 make dev-migrate # apply migrations
41 make dev # hot-reload server on http://localhost:8080
42 ```
43
44 Requires:
45 - Go 1.22+ (developed against 1.26).
46 - PostgreSQL 13+.
47 - A local MinIO (or any S3-compatible store).
48 - `golangci-lint`, `gofumpt`, `goimports`, `air`, `sqlc` (installed
49 via `make install-tools`).
50
51 Copy `.env.example` to `.env` and fill in DB URL, session keys,
52 and the TOTP/webhook AEAD keys.
53
54 ## Submitting a change
55
56 1. **Branch.** From `main`, create a feature branch.
57 2. **Commit.** Terse, imperative, single-line messages unless the
58 change needs elaboration. One concern per commit. Avoid
59 `git add -A`; stage by file.
60 3. **Test.** Add tests proportional to the scope. Integration
61 tests hit a real Postgres; we do not mock the DB seam. The
62 bench harness (`bench/`) is the right home for performance
63 regressions.
64 4. **Lint.** `make ci` runs everything CI runs. PRs must be green.
65 5. **Push + PR.** Open against `main`. The PR template prompts
66 for a summary + test plan + reviewer notes.
67
68 ## Code style
69
70 - `gofumpt` + `goimports` (run via `make fmt`).
71 - `golangci-lint` per the in-repo config.
72 - Package-boundary lints (markdown, policy, secret-logs, CSRF)
73 are enforced via `scripts/lint-*.sh`. Adding a goldmark import
74 outside `internal/markdown` will fail CI.
75 - Comment style: lead with the why. Don't restate the code.
76 - Migrations: forward-only by convention; `down` exists for
77 emergency rollback only and may drop data.
78
79 ## Browser interactivity
80
81 HTMX is for partial-render swaps where a full page reload would feel
82 jarring. SSE is for true streaming. Do not reach for either without a
83 specific UX reason, and keep HTMX swap targets separate from SSE-owned
84 log panes so polling cannot replace an active stream.
85
86 ## Reviewing
87
88 Maintainers (and other contributors with write access) review
89 each PR. Aim for one approval before merge; protected branches
90 enforce status checks + required reviews.
91
92 If you've left a "Request changes" review, please follow up
93 within a few days — open PRs are a tax on the author.
94
95 ## Cutting a release
96
97 Maintainers only. The procedure is in
98 `docs/internal/runbooks/upgrade.md`. Tag the release, push,
99 run the deploy.
100
101 ## Communication
102
103 - **Discussion of features / RFCs:** open an issue tagged
104 `proposal`.
105 - **Day-to-day chat:** the project doesn't run a Slack/Discord
106 yet; PR comments and issues are the channel.
107 - **Security:** `security@shithub.sh` (see SECURITY.md).