Repository navigation
docs: make the contributing guide org-wide - #47
Merged
Merged
Conversation
Make CONTRIBUTING.md the contributor guide for every repository of the organisation: add "Getting started" (joining Slack, organisation teams, one-time contributions from forks), the table of commit types and the rule for deployed or published changes, the rule for pull requests prepared with AI agents and the citation authorship rule; align the title rule with the PR title check; state that repositories have no CONTRIBUTING.md of their own. Drop the links to the deprecated elixir-cloud-aai.github.io and the name "ELIXIR Cloud & AAI". Closes #39 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reviewer's GuideThe PR turns CONTRIBUTING.md into the mandatory organisation-wide contributor guide, adding onboarding, support, AI, citation, commit, and title guidance while removing deprecated links and repository-level overrides; README.md is updated to document the same no-overrides policy. File-Level Changes
Possibly linked issues
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
uniqueg
marked this pull request as ready for review
November 1, 2026 03:27
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've found 3 issues
Prompt for AI Agents
Please address the comments from this code review:
## Individual Comments
### Comment 1
<location path="CONTRIBUTING.md" line_range="105-106" />
<code_context>
+Use `feat`, `fix`, `perf`, `refactor` and `style` only for changes to what is
+deployed or published: the app or library, its Helm chart or its packages.
+Everything else uses `build`, `ci`, `docs`, `test` or `chore`. Where a
+repository has the `PR title` check, it enforces these rules for pull request
+titles.
+
+## Citation metadata
</code_context>
<issue_to_address>
**Invalid titles pass the check**
When a repository uses the PR title check and a title violates the imperative-mood or type-selection guidance, `check.sh` validates title structure and mechanical rules but does not enforce imperative mood or whether the type matches the change. The title passes despite the guide saying the check enforces these rules.
Make the check enforce imperative mood and type selection, or clarify in the guide that it does not.
Also at `CONTRIBUTING.md:82-83`.
</issue_to_address>
### Comment 2
<location path="CONTRIBUTING.md" line_range="122" />
<code_context>
-[FOCA](https://foca.readthedocs.io/en/latest/contributing/) and
-[Cloud Registry](https://cloud-registry.readthedocs.io/en/latest/contributing/)).
-Where they differ from this guide, the repository's docs apply.
+Repositories don't have their own `CONTRIBUTING.md`. Their development setup,
+the checks to run locally, language guidelines, the release process and the
+documentation build are described in their documentation, linked from the
</code_context>
<issue_to_address>
**Repository guides remain in force**
When an organisation repository still has its own `CONTRIBUTING.md`, gitHub displays the repository's own `CONTRIBUTING.md` instead of the organisation default, so changing the shared guide does not give those contributors the claimed organisation-wide guidance.
Remove or redirect repository-specific `CONTRIBUTING.md` files so contributors receive the organisation guide.
Also at `README.md:32-34`.
</issue_to_address>
### Comment 3
<location path="CONTRIBUTING.md" line_range="104" />
<code_context>
+
+Use `feat`, `fix`, `perf`, `refactor` and `style` only for changes to what is
+deployed or published: the app or library, its Helm chart or its packages.
+Everything else uses `build`, `ci`, `docs`, `test` or `chore`. Where a
+repository has the `PR title` check, it enforces these rules for pull request
+titles.
</code_context>
<issue_to_address>
**Revert titles get conflicting types**
When a contributor reverts an earlier change that was not deployed or published, the table specifies `revert`, but the following rule assigns changes outside deployed or published work to `build`, `ci`, `docs`, `test` or `chore`. Contributors receive conflicting instructions for the title type.
Explicitly exempt `revert` from the rule assigning all other changes to `build`, `ci`, `docs`, `test` or `chore`.
Also at `CONTRIBUTING.md:100`.
</issue_to_address>Linked issues
#39 docs: make the contributing guide org-wide · 9 of 9 met
| # | Requirement | Status | Notes |
|---|---|---|---|
| 1 | Add the getting-started guidance for finding or opening an issue, introducing yourself, joining an organisation team, and contributing once from a fork. | ✅ Met | The new section covers each step, including team eligibility and maintainer approval for checks from forks. |
| 2 | Add the commit-type table and limit feat, fix, perf, refactor and style to deployed or published changes. | ✅ Met | The table lists the types and the guide states which changes use the deployed-or-published types. |
| 3 | Align the title rule with the PR title check. | ✅ Met | The guide specifies the 50-character limit, imperative description, capitalization exception for acronyms, and no trailing period. |
| 4 | Add the rules for pull requests prepared with AI agents. | ✅ Met | The guide says they follow the same rules, are opened as drafts, and have a named person responsible for them and answering review comments. |
| 5 | Add the CITATION.cff authorship rules and leave version and date guidance in repository documentation. | ✅ Met | The new section covers authorship, ordering, affiliations and entry changes; version and date guidance is left to repository documentation. |
| 6 | Rewrite repository specifics to direct contributors to each repository's documentation linked from its README. | ✅ Met | The section says repositories have no own CONTRIBUTING.md and identifies the repository-specific details to find in their documentation. |
| 7 | Drop the deprecated contributor-guide and workflow links, carry over the needed joining guidance, and use the current website where appropriate. | ✅ Met | The deprecated guide link is removed; the new getting-started section covers joining, and the introduction links to elixir-on.cloud. |
| 8 | Replace “ELIXIR Cloud & AAI” with “ELIXIR On-Cloud”. | ✅ Met | The contributing guide now uses ELIXIR On-Cloud. |
| 9 | State the no-overrides policy for organisation community health files and keep repository specifics in repository documentation. | ✅ Met | The README now states that repositories do not override the shared files and directs repository specifics to their documentation. |
Sourcery assessment
Approval pending. 3 findings to address first.
Blocking findings: CONTRIBUTING.md:106, CONTRIBUTING.md:122, CONTRIBUTING.md:104
Say which title rules the PR title check enforces and which reviews check, and that reverts use the type revert. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Makes
CONTRIBUTING.mdthe contributor guide for every repository of theorganisation, so that the repositories' own contributing pages can go (#38):
yourself in
#oss-community(or message a project lead), organisationteams (
membersfor ELIXIR members,oss-contributorsfor otherverified contributors) let you assign issues to yourself, one-time
contributors open pull requests from forks;
feat,fix,perf,refactorandstyleare only for changes to what is deployed orpublished;
PR titlecheck (at most 50 characters,imperative, no capitalised first word, acronyms fine, no trailing period);
cloud-components) and the citation authorship rule for
CITATION.cff(version and date stay in the repositories' docs);
CONTRIBUTING.mdof their own; their specifics live in their documentation, linked from
the README's "Contributing" section;
links to the deprecated
elixir-cloud-aai.github.ioand replaces"ELIXIR Cloud & AAI" with "ELIXIR On-Cloud" (website: elixir-on.cloud);
no-overrides policy.
Closes #39
Light lane: documentation text only (no code, workflows or configuration),
so no reviewer subagents; I reviewed the diff myself.
Verification
pre-commit run --all-filesandpre-commit run --all-files --hook-stage manual gitleaks-all: all hookspassed (markdownlint included).
bash tests/pr-title/test.sh,bash tests/gate/test.sh: passed(unaffected).
tests/release/test.shnot run (unaffected; not touched).PR titlecheck enforces vs. what reviews check; reverts userevert).Declined review findings
own contributing guide still override this one). Intended: removing the
overrides is tracked in the other child issues of docs: no overrides of org community files #38, which this issue
blocks.
Open questions
None.
🤖 Generated with Claude Code