@@ -1,23 +1,100 @@ |
| 1 | 1 | # Contributing to shithub |
| 2 | 2 | |
| 3 | | -shithub is currently **pre-launch and closed to external contributions**. Once we cross v1.0.0 and the project's own source migrates to a self-hosted shithub instance, this document will be expanded with the full contribution workflow. |
| 3 | +shithub is open to contributions from anyone. The project is |
| 4 | +post-launch (per S40); the workflow is the standard one. |
| 4 | 5 | |
| 5 | | -In the meantime, if you find a security issue, please follow [SECURITY.md](SECURITY.md). |
| 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`: |
| 6 | 11 | |
| 7 | | -## Post-launch (planned) |
| 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. |
| 8 | 23 | |
| 9 | | -- Code style: `gofumpt` + `goimports`. Lint via `golangci-lint`. |
| 10 | | -- Commit messages: terse, imperative, single-line unless the change requires elaboration. |
| 11 | | -- DCO sign-off on each commit (`git commit -s`). |
| 12 | | -- Tests: every change ships with tests proportional to its scope. Integration tests hit a real Postgres; we do not mock the DB seam. |
| 13 | | -- One change per pull request; small PRs are easier to review. |
| 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. |
| 14 | 32 | |
| 15 | 33 | ## Development setup |
| 16 | 34 | |
| 17 | 35 | ```sh |
| 18 | 36 | git clone https://github.com/tenseleyFlow/shithub.git |
| 19 | 37 | cd shithub |
| 20 | | -make dev |
| 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 |
| 21 | 42 | ``` |
| 22 | 43 | |
| 23 | | -The full development guide will land in `docs/internal/contributing.md` post-launch. |
| 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 | +## Reviewing |
| 80 | + |
| 81 | +Maintainers (and other contributors with write access) review |
| 82 | +each PR. Aim for one approval before merge; protected branches |
| 83 | +enforce status checks + required reviews. |
| 84 | + |
| 85 | +If you've left a "Request changes" review, please follow up |
| 86 | +within a few days — open PRs are a tax on the author. |
| 87 | + |
| 88 | +## Cutting a release |
| 89 | + |
| 90 | +Maintainers only. The procedure is in |
| 91 | +`docs/internal/runbooks/upgrade.md`. Tag the release, push, |
| 92 | +run the deploy. |
| 93 | + |
| 94 | +## Communication |
| 95 | + |
| 96 | +- **Discussion of features / RFCs:** open an issue tagged |
| 97 | + `proposal`. |
| 98 | +- **Day-to-day chat:** the project doesn't run a Slack/Discord |
| 99 | + yet; PR comments and issues are the channel. |
| 100 | +- **Security:** `security@shithub.example` (see SECURITY.md). |
