Skip to content

Flesh out CONTRIBUTING.md and SECURITY.md#663

Open
JobDoesburg wants to merge 2 commits into
masterfrom
improve-contributing-and-security
Open

Flesh out CONTRIBUTING.md and SECURITY.md#663
JobDoesburg wants to merge 2 commits into
masterfrom
improve-contributing-and-security

Conversation

@JobDoesburg

Copy link
Copy Markdown
Collaborator

What this does

Brings the two root-level community docs up to the same standard as the rest of the repo.

CONTRIBUTING.md

The existing version was actually pretty good (modular-apps rule, services pattern, migrations, fixtures, time zones, CSP, sensitive apps, privacy, testing, code style — all already there and accurate). The weakness was the bottom: a 3-bullet workflow that didn't tell a new contributor what their first PR should actually look like.

Additions:

  • Quick start with a concrete checklist (set up locally, branch, make the change, run the actual lint/test/schema-validate commands, open the PR). Replaces the bare 3-bullet workflow.
  • Opening a pull request section spelling out what makes a good PR: one concern per PR, descriptive body, regression test for fixes, migration in the same commit, don't squash other people's commits, don't force-push to master or --no-verify past hooks.
  • Reviewer checklist — scope check, app isolation, migrations, sensitive-app coverage, PII, vendored frontend, CI green. Makes the implicit explicit and gives reviewer and contributor a shared bar.
  • AGENTS.md pointer at the top — same conventions, condensed for AI coding tools. Was easy to miss before.
  • SECURITY.md pointer from the sensitive-apps section so the reader knows the right disclosure path.
  • pydocstyle added to the listed code-style tools — CI already runs it.

Existing content kept verbatim.

SECURITY.md

Promoted from a 9-line stub to a real disclosure policy.

  • Supported versions — only the current deployment at https://tosti.science.ru.nl and the TOSTI-fridge-client repo.
  • Reporting a vulnerability — don't open a public issue; email www-tosti@science.ru.nl; what to include in the report; expect an acknowledgement within 7 days; escalation path at 14 days.
  • What counts as a security issue with explicit in/out-of-scope lists. In: auth/scope bypasses, age-verification bypass (legally loaded), OAuth/MCP issues, SAML issues, privacy leaks, injection classes, secret leakage, supply chain. Out: cosmetic issues, third-party domains, unverified scanner output.
  • What we ask of reporters — don't pivot once you've demonstrated the issue, don't unnecessarily test in production, coordinate disclosure timelines.

Test plan

  • Render both files on GitHub and confirm the headings, code blocks, and the new > [!IMPORTANT] callout in CONTRIBUTING.md display correctly.
  • Check that all in-repo links resolve (AGENTS.md, SECURITY.md, deploy/README.md, README.md anchors).

JobDoesburg and others added 2 commits June 28, 2026 21:28
CONTRIBUTING.md:
- New "Quick start" with a concrete checklist (set up locally, branch,
  make the change, run the actual lint/test/schema-validate commands,
  open the PR). Replaces the bare 3-bullet workflow at the bottom.
- New "Opening a pull request" section spelling out what makes a good
  PR (one concern, descriptive body, tests for fixes, migration in the
  same commit, don't squash someone else's commits, don't force-push or
  --no-verify past hooks).
- New "Reviewer checklist" — what a reviewer is expected to check
  before approving. Makes the implicit explicit and gives the
  reviewer-and-contributor pair a shared bar to look at.
- Pointer to AGENTS.md at the top — same conventions, condensed for AI
  coding tools. Was easy to miss before.
- Pointer to SECURITY.md from the sensitive-apps section so the
  reader has the right disclosure path in mind.
- Other content (scope check, modular apps, services, migrations,
  fixtures, performance, time zones, CSP, sensitive apps, privacy,
  testing, code style) kept verbatim — it was accurate.
- Added pydocstyle to the listed code-style tools; CI already runs it
  but the doc didn't say so.
- Heading hierarchy and language touch-ups for consistency.

SECURITY.md:
- Promoted from a 9-line stub to a real disclosure policy.
- New "Supported versions" section that names the production
  deployment (tosti.science.ru.nl) and the TOSTI-fridge-client repo as
  the supported surfaces.
- New "Reporting a vulnerability" section: don't open a public issue;
  email www-tosti@science.ru.nl; what to include in the report;
  expect an acknowledgement within 7 days; escalation path at 14 days.
- New "What counts as a security issue" with explicit in/out-of-scope
  lists. Calls out the load-bearing surfaces: auth/scope bypasses,
  age verification (legally loaded), OAuth/MCP, SAML, privacy leaks,
  injection classes, secret leakage, supply chain. Out-of-scope:
  non-security bugs, cosmetic issues, third-party domains, unverified
  scanner output.
- New "What we ask of reporters" — don't pivot, don't test in
  production unnecessarily, coordinate disclosure timelines.

No code, no behaviour change. Pure documentation.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
There's only one inbox in practice. Stop referring to it under two
names (``tartaruswebsite@`` was the older alias) so a reader looking
for the right address doesn't have to wonder which to pick.

- CONTRIBUTING.md: header reachable-at line and "Getting help"
  bottom both point at www-tosti@.
- SECURITY.md: the maintainer-contact section drops the
  general-vs-security split (same inbox); the escalation paragraph
  no longer points at the dead-letter alias.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant