documentation-specialist 4b532ac0a6 docs(contributing): add org-wide CONTRIBUTING.md — Gitea-canonical SCM, branch+PR+merge-commit, no force-push to main

First content for `Molecule-AI/.github/CONTRIBUTING.md`. GitHub
renders `<org>/.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)

2026-05-06 18:38:51 -07:00

4.3 KiB

Raw Permalink Blame History

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. All commits, PRs, and issues happen here.
GitHub mirror at 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, or on the specific repo if it's repo-scoped.
Security issues: see 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.

Branch off the right base. Most repos: main. Platform repos (molecule-core, molecule-controlplane): staging. The destination repo's README will say.
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.
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.
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.
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.
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.

4.3 KiB Raw Permalink Blame History