docs: add CONTRIBUTING.md and a PR template - #90
Merged
Conversation
The same handful of mistakes keeps arriving from different people: pushing without running the gates, tests that assert nothing, new test functions without annotations, `__all__` appended instead of sorted, and work duplicated because nobody checked the open PRs. Every one of those is caught by `scripts/run-ci.sh`, which nothing told anyone to run. Neither repo had a CONTRIBUTING.md or a PR template. Two things worth calling out, because a contributor cannot discover either: - Installing `requirements-dev.txt` is load-bearing beyond running the tests. mypy's answer depends on which packages are importable — a `# type: ignore` that is required with sentence-transformers installed is an unused-ignore error without it — so skipping the install grades different code than CI. - Pull requests from forks cannot run CI at all. They receive no repository secrets, so the setup step that needs one fails in seconds with "Input required and not supplied: token". That is not something the contributor can fix, and it looks exactly like a broken patch. The doc says to run the gates locally and note it; a maintainer re-runs from a branch. Deliberately does not restate the engineering rules — those are enforced by the gates, and the fuller ruleset lives in infrastructure an outside contributor cannot see. Anything requiring that repo (the surface oracle) is written as "flag it, a maintainer lands it" rather than as a task. Master copy: the other nine ports carry a language-adapted version.
Two gates caught this, both correctly. ROOT-HYGIENE keeps a public port root clear of anything not on its allowlist, and a new tracked root file is exactly what it exists to stop. `.github/` is where GitHub looks for CONTRIBUTING.md anyway — it surfaces identically from the PR and issue UI — so the file moves rather than the gate being widened. DOC-AUDIT resolves every symbol referenced in docs against the surface oracle, and the assertion example cites `pytest.raises`. Recorded in DOC_AUDIT_IGNORE.md as third-party, next to the other test-helper entries. Both were verified locally BEFORE this push and both passed — because the check ran before the files were staged, and both gates only see tracked files. Which is a fair demonstration of the guide's own first rule: run scripts/run-ci.sh, which stages nothing and reads the tree the way CI does.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds
CONTRIBUTING.mdand a PR template. Neither repo had either.Why
The same few mistakes keep arriving from different people, and all of them are
caught by
scripts/run-ci.sh— which nothing told anyone to run. Recentexamples, four different authors:
the mypy config says in a comment that "a new untyped test fails the gate"
__all__appended to instead of sorted — twiceat the open PRs
Two things a contributor cannot possibly discover
Installing
requirements-dev.txtis load-bearing beyond running the tests.mypy's answer depends on which packages are importable. A
# type: ignorethatis required with
sentence-transformersinstalled is an unused-ignore errorwithout it. Skip the install and your checker grades different code than CI's,
so a gate reds on lines you never touched. (Hit this repeatedly while fixing
the release gates; it is why
ruffis pinned exact, and mypy arguably shouldbe too.)
Fork PRs cannot run CI at all. They receive no repository secrets, so the
porting-sdk checkout dies in ~6s on
Input required and not supplied: token.Nothing in the patch can fix it, and it reads exactly like a broken
contribution. All four of the recent outside PRs failed this way and had to be
re-homed onto an in-repo branch. The doc tells contributors to expect it, run
the gates locally, and say so.
What it deliberately does not do
It does not restate the engineering rules. Those are enforced by the gates, and
the fuller ruleset lives in infrastructure an outside contributor cannot see —
so anything needing that repo (the surface oracle) is phrased as "flag it in
the PR, a maintainer lands it" rather than as a task assigned to someone
without access.
Scope
Master copy. The other nine ports should carry a language-adapted version —
six of the eight points are portable; the commands are per-language.
Verification
ROOT-HYGIENE and DOC-LINKS clean. Full run-ci passes except the four known
environment artifacts: TYPECHECK/TEST at main's baseline, and SURFACE-NATIVE /
SEMVER-DIFF which hardcode a sibling
../porting-sdklookup and cannot resolvefrom the temporary worktree this was built in. Doc-only change; no code paths
touched.
🤖 Generated with Claude Code
https://claude.ai/code/session_015dYktt85Ltj3oK9gG5VBww