From 4b532ac0a664c4c97a49583097cc402c940052ef Mon Sep 17 00:00:00 2001 From: documentation-specialist Date: Wed, 6 May 2026 18:38:51 -0700 Subject: [PATCH] =?UTF-8?q?docs(contributing):=20add=20org-wide=20CONTRIBU?= =?UTF-8?q?TING.md=20=E2=80=94=20Gitea-canonical=20SCM,=20branch+PR+merge-?= =?UTF-8?q?commit,=20no=20force-push=20to=20main?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit First content for `Molecule-AI/.github/CONTRIBUTING.md`. GitHub renders `/.github/CONTRIBUTING.md` as the default contributor guide for any repo in the org that doesn't ship its own. ## What's in scope - **Where the code lives**: Gitea is canonical (post-2026-05-06 GitHub org suspension); GitHub mirror is read-only OSS face. Non-security issues at git.moleculesai.app/molecule-ai/internal. - **How we ship**: branch off main (or staging on platform repos), conventional branch names, imperative commit messages, merge by merge commit (NOT squash), no force-push to main/staging. - **Tests + CI + review**: run locally first; fix root cause not --no-verify; one-business-day review SLA on non-trivial PRs. - **What we do NOT require**: no CLA, no bug bounty, no GPG enforcement, no mandatory issue templates. Explicit so contributors don't waste time on absent features. - **Boundaries**: no committed secrets, no shared-env cleanup, no long-running background jobs in tests. - **Repo-specific overrides win** when they disagree. ## Length 56 lines (orchestrator target was ~80; landed leaner because the post-suspension reality + merge-commit shape are the load-bearing bits and the rest is conventional-wisdom that doesn't need depth). ## Out of scope (parked, file when needed) - Per-repo CONTRIBUTING overrides β€” tracked individually. - Issue + PR templates β€” would live in profile/.github/ or per-repo; current per-repo guidance is fine. - GPG / CLA / bounty β€” explicitly called out as NOT required so contributors don't infer absence as oversight. πŸ€– Generated with [Claude Code](https://claude.com/claude-code) --- CONTRIBUTING.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..93459a8 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,56 @@ +# Contributing to Molecule-AI + +Thanks for your interest. This file is the org-wide default; individual repos may override with their own `CONTRIBUTING.md`. + +## Where the code lives + +- **Canonical SCM: Gitea at [`https://git.moleculesai.app/molecule-ai`](https://git.moleculesai.app/molecule-ai).** All commits, PRs, and issues happen here. +- **GitHub mirror at [`https://github.com/Molecule-AI`](https://github.com/Molecule-AI) is read-only** for the open-source surface. As of 2026-05-06 it does not accept new PRs or issues from external contributors. We're happy to receive patches via Gitea instead. +- **Non-security issues**: file at [`git.moleculesai.app/molecule-ai/internal/issues`](https://git.moleculesai.app/molecule-ai/internal/issues), or on the specific repo if it's repo-scoped. +- **Security issues**: see [`SECURITY.md`](./SECURITY.md). Do not file public issues for vulnerabilities. + +If you need a Gitea account to open a PR, ping us at the contact in `SECURITY.md` and we'll create one. + +## How we ship changes + +Every change goes through a PR β€” no direct pushes to `main` on any repo, and no direct pushes to `staging` on platform repos either. + +1. **Branch off the right base.** Most repos: `main`. Platform repos (`molecule-core`, `molecule-controlplane`): `staging`. The destination repo's README will say. +2. **Use a descriptive branch name.** Conventional shape: `/`. Types we use: `feat`, `fix`, `chore`, `docs`, `test`, `refactor`, `perf`. Example: `fix/poll-loop-jitter`. +3. **Commit messages**: imperative mood, present tense. Subject ≀ 72 chars. Body explains the why, not the what (the diff already shows the what). Group commits logically β€” one concern per commit, no `WIP` or `fix typo` noise in the final history. Squash or rebase locally before pushing if needed. +4. **Open a PR**. Title matches the lead commit. Description covers: what changed, why, alternatives rejected, rollout/rollback notes. For non-trivial changes, list the three weakest spots in the diff as a hostile self-review β€” saves the reviewer the work. +5. **Merge by merge commit, never squash.** This preserves the per-commit narrative for `git blame` and bisect. Auto-merge is fine once approved + CI green. +6. **Never force-push** to `main` or `staging`. Force-pushes on your own feature branch are fine until review starts; after that, prefer additive follow-up commits so the reviewer doesn't lose their place. + +## Tests, CI, and review + +- **Run the test suite locally before pushing.** Each repo's `README.md` documents the command (typically `bun test`, `go test ./...`, or `npm test`). CI runs the same suite; if it fails, fix the root cause β€” don't `--no-verify` past hook failures. +- **Every test must be able to fail.** No tautologies, no asserting-the-mock, no tests that pass because the code under test was never invoked. +- **Review** lands within a business day for non-trivial PRs. We're a small team β€” feel free to ping in the PR if a review is sitting cold for >2 days. + +## What we do NOT require + +We're being explicit about absent features so contributors don't waste time on them: + +- **No CLA.** You retain copyright; license is set per-repo (mostly BSL 1.1, see `LICENSE`). +- **No bug bounty program.** Security disclosures are still very welcome β€” see `SECURITY.md`. +- **No GPG-signed commit enforcement.** Sign if you want; not required. +- **No mandatory issue-template fields.** Fill what you can; we'll ask if anything's missing. + +If we add any of these later, the change lands in this file via PR like everything else. + +## Boundaries + +- **Don't push secrets, tokens, or `.env` files.** Pre-commit secret-scanning runs in CI but is not infallible. If you do leak something, immediately ping us in the relevant PR or via the `SECURITY.md` contact and we'll rotate. +- **Don't run cluster-cleanup or mass-delete tests against shared environments** β€” staging is shared. +- **Don't spawn long-running background jobs in test files.** They hang CI. + +## Repo-specific overrides + +Some repos add stricter rules (e.g. `molecule-core` has a coverage floor by package; `molecule-controlplane` requires stagingβ†’main auto-promote PRs to be reviewed even though they're machine-authored). Those live in the repo's own `CONTRIBUTING.md` or `docs/engineering/`. + +When the repo-specific guidance and this file disagree, the repo-specific guidance wins. + +--- + +Last updated: 2026-05-06.