shithub Public

Watch 1 Fork 0 Star 0

markdown · 3398 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

Branch. From main, create a feature branch.
Commit. Terse, imperative, single-line messages unless the change needs elaboration. One concern per commit. Avoid git add -A; stage by file.
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.
Lint. make ci runs everything CI runs. PRs must be green.
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.

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
        ## 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.sh` (see SECURITY.md).

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	## 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.sh` (see SECURITY.md).