docs: add org-default CONTRIBUTING guide (public workflow distillation) - #2
docs: add org-default CONTRIBUTING guide (public workflow distillation)#2jeremylongshore wants to merge 1 commit into
Conversation
…AI workflow) WHAT — adds a CONTRIBUTING.md to the org's community-health repo, so it auto-applies as the default contributing guide across every intent-solutions-io repo that lacks its own. It is the public-safe distillation of our internal way-of-working standard. WHY — the team (and their AI agents) were not working repos identically; the rules existed but were scattered and mostly internal. A public org-default CONTRIBUTING is the highest-reach, lowest-effort place to state the universal parts — branch/commit/PR discipline, the Outsider Test, the CI-is-the-gate / AI-review-is-advisory model, maintainers-merge, tests-as-evidence, and how to work with AI agents. Public tier: no internal-only content (no compensation/PII, no infra/secrets, no internal handles). Chose the org .github repo over per-repo copies because a single default propagates to all repos automatically and can't drift out of sync the way copy-pasted files do. HOW verified — Markdown renders; links resolve (the how-we-build page + intentsolutions.io); content reviewed against the public disclosure tier (no comp/PII/infra leakage). Refs: the internal canonical standard "How to work a repo with AI" (intent-os).
📝 WalkthroughWalkthroughAdds ChangesContribution Guidance
Estimated code review effort: 1 (Trivial) | ~3 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://cdn.statically.io/img/avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@CONTRIBUTING.md`:
- Around line 16-20: Update step 4 in the contribution workflow to state that
contributors should push their branch and then open a pull request, removing the
implication that pushing alone creates one. Keep the surrounding CI and review
instructions unchanged.
- Around line 114-115: Update the contribution-policy wording in CONTRIBUTING.md
to avoid asserting that contributing alone constitutes agreement to the
repository LICENSE. State instead that contributions are subject to the
repository’s applicable license and any required contribution agreements, while
preserving the references to CODE_OF_CONDUCT.md and SECURITY.md.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
| 2. **Branch from `main`** (`git fetch` first; `main` often moves under you). **Never commit to `main` | ||
| directly.** | ||
| 3. Make your change; run the repo's **tests, type-check, and lint** locally *before* you commit. | ||
| 4. **Push — that opens your pull request.** CI and the review bot pick it up from there. | ||
| 5. Address review + CI, then a **maintainer merges** (see *Reviews & merging*). |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== CONTRIBUTING.md relevant lines =="
sed -n '1,30p' CONTRIBUTING.md
echo
echo "== Workflow/docs references to opening PR or branch push =="
rg -n --glob '!node_modules' --glob '!dist' --glob '!build' \
'opens your pull request|open a pull request|open your pull request|push your branch|PR|pull request|pull request' CONTRIBUTING.md .github 2>/dev/null || true
echo
echo "== Repo automation files =="
fd -a '.workflow$|action.yml|action.yaml|zizmor|README|docs|CONTRIBUTING|CLA|DCO' . | sed 's#^\./##' | head -100Repository: intent-solutions-io/.github
Length of output: 3436
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== Repo files =="
git ls-files | sed -n '1,200p'
echo
echo "== GitHub workflow/config files =="
git ls-files .github workflows actions | sed -n '1,200p' || true
echo
echo "== Search for org-wide / repo files that mention PR-creation automation =="
rg -n --glob '.github/**' --glob '{CONTRIBUTING,README,CLAUDE,AGENTS,CLA,DCO,*.yml,*.yaml}' \
'pull request|Pull Request|create-pr|gh pr create|open a pull request|that opens|opens your pull request|auto.*pr|github-actions|actions' \
.github 2>/dev/null || trueRepository: intent-solutions-io/.github
Length of output: 499
Do not imply that pushing automatically opens a pull request.
A push creates or updates the remote branch; contributors must open the PR separately. Change this to “Push your branch, then open a pull request,” or document an org-wide automation that creates PRs from pushed branches.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@CONTRIBUTING.md` around lines 16 - 20, Update step 4 in the contribution
workflow to state that contributors should push their branch and then open a
pull request, removing the implication that pushing alone creates one. Keep the
surrounding CI and review instructions unchanged.
| Be respectful and constructive; assume good faith. By contributing, you agree your contributions are | ||
| licensed under the repository's `LICENSE`. See `CODE_OF_CONDUCT.md` and `SECURITY.md` where present. |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf 'Repository files relevant to licensing/contribution policy:\n'
git ls-files | rg '(^|/)(CONTRIBUTING\.md|LICENSE|LICENSES|CODE_OF_CONDUCT\.md|SECURITY\.md|CLA|DCO|CONTRIBUTOR|.*CONTRIBUT.*)' || true
printf '\nCONTRIBUTING.md around lines 100-125:\n'
sed -n '100,125p' CONTRIBUTING.md 2>/dev/null || true
printf '\nLICENSE files overview:\n'
for f in $(git ls-files | rg '(^|/)LICENSE(\.md)?$|(^|/)LICENSES/|(^|/)CODE_OF_CONDUCT\.md|(^|/)SECURITY\.md|(^|/)cla|(^|/)dco' || true); do
echo "### $f"
sed -n '1,80p' "$f" 2>/dev/null | rg -n 'license|licensed|contribute|contribution|CLA|DCO|grant|copyright|copyright notice|indemnification|developer|certificate|ownership|assign' -C 1 || true
done
printf '\nSearch terms in tracked text:\n'
rg -n --hidden --glob '!node_modules' --glob '!dist' --glob '!build' \
'agree[ your]? contributions are licensed|your contributions are licensed|BY contributing|contributing.*agree|CLA|DCO|contributor license|contribution .*\[Dd\]eveloper|Repository terms|applicable license|Terms of Service' . || trueRepository: intent-solutions-io/.github
Length of output: 1524
🌐 Web query:
GitHub .github repository organization-wide CONTRIBUTING.md purpose applies to all repositories in organization
💡 Result:
The purpose of a CONTRIBUTING.md file within a public, organization-owned repository named.github is to serve as an organization-wide default set of contribution guidelines [1][2][3]. This functionality allows organizations to standardize communication regarding how contributors should participate in projects across their entire organization [4][3]. Key details regarding this feature include: Scope and Precedence: The organization-wide CONTRIBUTING.md acts as a fallback [1][4]. If an individual repository contains its own CONTRIBUTING.md file, that repository-specific file takes precedence and is used instead [1][4]. The organization-wide default is only surfaced in repositories that do not define their own contribution guidelines [1][2]. Requirement for Public Repository: To function as an organization-wide default, the.github repository must be public [1][5][2]. Private.github repositories are not supported for this purpose [1][2]. Integration: Although the organization-wide CONTRIBUTING.md file does not appear in the file browser or Git history of the individual repositories that use it, GitHub automatically surfaces the content during relevant developer workflows, such as when a contributor creates a new issue or opens a pull request [6][7][3]. It is also displayed in the repository's community profile standards [4][6][3]. This mechanism is part of a broader feature set for community health files, which also supports other standardized files such as CODE_OF_CONDUCT.md, SECURITY.md, and various templates, all following the same override logic [4][6][3].
Citations:
- 1: https://github.com/github/docs/blob/main/content/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file.md
- 2: https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file
- 3: https://github.blog/changelog/2019-02-21-organization-wide-community-health-files/
- 4: https://tenthirtyam.org/dispatches/2026/04/01/set-shared-github-defaults-with-a-github-repository/
- 5: https://docs.github.com/en/enterprise-server@3.17/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file
- 6: https://devsolus.com/what-is-github-contributing-md-for/
- 7: https://stackoverflow.com/questions/72929081/what-is-github-contributing-md-for
🌐 Web query:
GitHub docs org-wide contributing.md fallback repository-specific LICENSE CLA DCO contribution guidelines
💡 Result:
To set up organization-wide contribution guidelines on GitHub, you can use a default community health repository [1][2]. By creating a public or internal repository named.github in your organization, any community health file—including CONTRIBUTING.md—placed within it will automatically serve as the default for any repository in that organization that does not provide its own specific version [1][3]. The lookup order for contribution guidelines, when a repository contains multiple files, is:.github directory, then the repository root, and finally the docs directory [4][2]. Regarding licensing, CLAs (Contributor License Agreements), and DCOs (Developer Certificate of Origin): 1. Licensing: GitHub's Terms of Service state that when you contribute to a repository containing a license, you license your contribution under those same terms and attest that you have the right to do so [5]. 2. DCO: A DCO is a per-commit attestation of origin. It can be enforced at the organization level via the web interface by enabling the "Require contributors to sign off on web-based commits" setting in the organization's repository defaults [6]. Alternatively, individual contributors can sign off on commits manually using the git commit --signoff flag [7][5]. 3. CLA: Unlike the native DCO support, there is no built-in, native GitHub feature to enforce a formal, signed CLA across an entire organization [5]. Implementing a CLA typically requires third-party tooling or a custom service (often integrated via GitHub Apps or webhooks) that validates a contributor's agreement status before allowing a merge [7][8]. Organizations with specific legal needs should consult with their legal counsel to determine the appropriate agreement type [9][5]. In summary, while CONTRIBUTING.md files and basic commit signoff (DCO) policies can be managed organization-wide through native GitHub features, formal CLA enforcement requires external implementation [6][1].
Citations:
- 1: https://docs.github.com/en/enterprise-server@3.20/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file
- 2: https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors
- 3: https://github.com/github/docs/blob/main/content/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file.md
- 4: https://github.com/github/docs/blob/main/content/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors.md
- 5: https://ospo.docs.cern.ch/howtos/running-open-source-projects/CLAs-and-DCOs/
- 6: https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-organization-settings/managing-the-commit-signoff-policy-for-your-organization
- 7: https://tenthirtyam.org/dispatches/2026/04/08/dco-vs-cla-managing-contribution-agreements-in-open-source/
- 8: https://github.com/X-oss-byte/ContributorLicenseAgreement
- 9: https://github.com/github/github-ospo/blob/main/policies/contributor-license-agreements.md
Avoid making a blanket licensing-agreement claim.
This org-wide CONTRIBUTING.md is used as a fallback for repositories that do not define their own contribution policy, where licenses or contribution terms like CLAs/DCOs may differ. Reword this to say contributions are subject to the repository’s applicable license and any contribution agreement requirements rather than asserting agreement by contribution alone.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@CONTRIBUTING.md` around lines 114 - 115, Update the contribution-policy
wording in CONTRIBUTING.md to avoid asserting that contributing alone
constitutes agreement to the repository LICENSE. State instead that
contributions are subject to the repository’s applicable license and any
required contribution agreements, while preserving the references to
CODE_OF_CONDUCT.md and SECURITY.md.
1 participant
What
Adds
CONTRIBUTING.mdto the org community-health repo so it auto-applies as the default contributing guide across everyintent-solutions-iorepo that doesn't have its own. It's the public-safe distillation of our internal "how to work a repo with AI" standard.Why
The team and their AI agents weren't working repos identically; the rules existed but were scattered and mostly internal. A public org-default
CONTRIBUTINGis the highest-reach, lowest-effort place to state the universal parts: branch/commit/PR discipline, the 7-question Outsider Test, CI-is-the-gate / AI-review-is-advisory, maintainers-merge, tests-as-evidence, and how to work with AI agents. Chose the org.githubdefault over per-repo copies because one default propagates automatically and can't drift the way copy-pasted files do. Public tier — no internal-only content (no compensation/PII, no infra/secrets, no internal handles).Verification
Markdown renders; the two external links resolve (the how-we-build page + intentsolutions.io); reviewed against the public disclosure tier.
Refs
Public distillation of the internal canonical standard "How to work a repo with AI."
intentsolutions.io
Summary by CodeRabbit