Merge pull request 'docs(contributing): org-wide CONTRIBUTING.md — Gitea-canonical SCM + branch+PR+merge-commit + no-force-push' (#2) from docs/contributing-md-2026-05-06 into main

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: `<type>/<short-summary>`. 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.