Code Ownership¶
Poriscope keeps a CODEOWNERS file at .github/CODEOWNERS mapping paths in the
repository to the people who maintain them.
Its only purpose is routing: when you open a pull request, GitHub reads that file and automatically requests a review from whoever maintains the files you touched, so the person most likely to spot a problem hears about the change without anyone having to remember to tag them.
Important
CODEOWNERS in Poriscope is advisory, not a gate. It is a guideline, not a hard
edit limit, and it is deliberately not a barrier to contribution.
GitHub offers a branch-protection setting called Require review from Code Owners
that turns the file into a merge block. That setting is switched off on purpose,
for every branch. Nothing in CODEOWNERS prevents you from merging, and if you are
contributing a plugin from a fork you do not need a listed owner’s approval.
If you touch a file someone else maintains, they will simply be asked to look. That is the whole mechanism.
Why This Is Advisory¶
Poriscope is designed to accept plugin contributions from outside the lab —
.github/workflows/ci-fork-pr.yml exists specifically to run validation on
fork-originated pull requests. A required-owner-review rule would put a single named
individual in front of every one of those contributions, including files whose maintainer
happens to be busy, on leave, or no longer with the lab.
Correctness is the job of the automated gates described in Quality Control and Developer Workflow, which
every pull request must pass. Those are the checks that block. CODEOWNERS sits
alongside them as a courtesy to reviewers, not as an additional hurdle.
Who Owns What¶
Path |
Maintainer(s) |
|---|---|
Everything not listed below |
Kyle Briggs |
|
Kyle Briggs |
|
Kyle Briggs, Carolina González |
|
Kyle Briggs, Carolina González |
|
Carolina González |
All other |
Kyle Briggs |
|
Nada Kerrouri, Kyle Briggs |
|
Carolina González |
|
Carolina González, Kyle Briggs |
|
Kyle Briggs, Carolina González |
|
Carolina González, Kyle Briggs |
Where more than one name is listed, both are asked to review; because the file is advisory, neither is required to respond before a merge.
The PeakFinder family carries one extra convention that is worth knowing if you are
working through the maintenance queue rather than contributing a plugin: the logic in
PeakFinder.py and Basic_PeakFinder.py belongs to its maintainer and is left to
her, while docstring, signature and type-hint changes to those files are ordinary work.
That policy is recorded in future_fixes.md.
Relationship to the # Contributors: Headers¶
Every source file under poriscope/ and scripts/ opens with the MIT licence header
followed by a # Contributors: block naming the people who wrote it.
scripts/new_plugin.py fills that block in from your Git author name when it generates
a new plugin, so it stays accurate for new code automatically.
Those headers and CODEOWNERS answer two different questions and will not always
agree:
The header records who wrote the file. It is attribution, and it is permanent.
CODEOWNERSrecords who maintains the file now. It changes as people join the lab, move between areas, or leave it.
Two consequences follow. First, files written by contributors who have since left the lab
pass to Kyle Briggs, so their CODEOWNERS entry no longer names the original author
even though the header still does — and rightly so, since the header is a record of
authorship. Second, the test suites under tests/ carry no headers at all but do have a
maintainer, so the two sources cannot be derived from one another in either direction.
Changing an Ownership Entry¶
Edit .github/CODEOWNERS in a normal pull request. Two things to keep in mind:
Patterns are last-match-wins. The most specific rule must come last, which is why the global
*fallback sits at the top of the file rather than the bottom.A name only works if it has write access to the repository. GitHub silently ignores a line naming anyone else, which means a mistyped handle does not raise an error — it just quietly stops requesting anybody.