docs: name the authors in CITATION.cff and guard it - #193
Conversation
da5bb58 to
59b6d2b
Compare
|
Important Review skippedAuto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
Comment |
|
@coderabbitai review |
✅ Action performedReview finished.
|
|
@coderabbitai full review |
✅ Action performedFull review finished. You're currently rate limited under our Fair Usage Limits Policy. Your recent PR review activity is in the 95th percentile or higher among CodeRabbit users, so adaptive limits apply. Your next review will be available in 12 minutes. |
|
@codex review |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 59b6d2b9e3
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…rence The release-field check only fired when `doi` was present, so a release commit that added `version` and `date-released` but forgot the DOI passed silently — which is the likelier mistake of the two, and it ships a release whose citation cannot be resolved. It now requires the three fields to be all present or all absent, so the omission fails in either direction. All three absent stays valid: that is the pre-release state. Also correct the Verma 2024 entry in the `references:` block, which carried Biophysical Journal 123(14):2179-2193. Crossref resolves the DOI to 123(17):2765-2780. The same error is fixed at its root in the PRD bibliography and on the parity-gallery page in #192; it is fixed here rather than there because both PRs would otherwise edit this file. Verified: adding version + date-released without a doi now fails the guard; cffconvert still reports the file valid against schema 1.2.0. Addresses the review on #193.
|
@codex review |
|
@coderabbitai full review |
✅ Action performedFull review finished. You're currently rate limited under our Fair Usage Limits Policy. Your recent PR review activity is in the 95th percentile or higher among CodeRabbit users, so adaptive limits apply. Your next review will be available in 56 minutes. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 54ab18436e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
The author list was a single CFF *entity* — "The Tether Authors" — with no named person and no ORCID, so GitHub's "Cite this repository" output credited nobody. Zenodo and JOSS both require identifiable humans, and the credit is unrecoverable once papers cite a published archive. Add the two authors as CFF person entries with ORCIDs, verified against the ORCID public API rather than transcribed by hand. Names use each record's own registered spelling. The file was also schema-INVALID on main, which nothing caught: the entity entry carried `affiliation`, which CFF 1.2.0 allows on a person but not on an entity, so it matched neither variant. Dropping that key makes the file validate; `cffconvert --validate` now reports it valid against schema 1.2.0 and renders both named authors. Replace the one-line version/doi TODO with the ordered release-time procedure. The Zenodo webhook must be enabled BEFORE the tag is pushed — if it is off at tag time that version is never archived, and the only remedy is cutting another release. That ordering was not written down anywhere. Add tests/test_citation_metadata.py: structural guards on the base 3-OS matrix (cffconvert is not in the base conda-lock) encoding the two ways this file has actually been wrong. Against the previous file they fail on exactly those two defects. Refs #162
…rence The release-field check only fired when `doi` was present, so a release commit that added `version` and `date-released` but forgot the DOI passed silently — which is the likelier mistake of the two, and it ships a release whose citation cannot be resolved. It now requires the three fields to be all present or all absent, so the omission fails in either direction. All three absent stays valid: that is the pre-release state. Also correct the Verma 2024 entry in the `references:` block, which carried Biophysical Journal 123(14):2179-2193. Crossref resolves the DOI to 123(17):2765-2780. The same error is fixed at its root in the PRD bibliography and on the parity-gallery page in #192; it is fixed here rather than there because both PRs would otherwise edit this file. Verified: adding version + date-released without a doi now fails the guard; cffconvert still reports the file valid against schema 1.2.0. Addresses the review on #193.
54ab184 to
6900e1e
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6900e1e7a8
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| # 2. Reserve the DOI in Zenodo and write it into `doi:` below, so the tagged commit | ||
| # is self-consistent rather than pointing at a DOI minted later. |
There was a problem hiding this comment.
For the Zenodo-GitHub webhook path described here, this release step cannot be performed: I checked Zenodo's GitHub integration FAQ (https://support.zenodo.org/help/en-gb/24-github-integration/73-can-i-pre-reserved-a-doi-before-a-github-release), and it says DOIs cannot be pre-reserved before using the GitHub integration. Following this ordered procedure would either block the release or put a manually reserved DOI in CITATION.cff that is not the DOI Zenodo mints for the GitHub release, so the release instructions need to use the post-release DOI update path or switch explicitly to a manual Zenodo upload.
Useful? React with 👍 / 👎.
1 participant
Summary
CITATION.cfflisted a single CFF entity —The Tether Authors— with no named person and no ORCID. GitHub's "Cite this repository" button therefore produced a citation crediting nobody, and both Zenodo and JOSS require identifiable humans. Once papers begin citing a published archive, that credit is not recoverable.The file was also schema-invalid on
main, and nothing caught it. The entity entry carriedaffiliation, which CFF 1.2.0 permits on a person but not on an entity, so the entry matched neither variant:Four changes:
affiliationkey from the entity entry, which is retained as an additional credit since it remains the copyright holder inNOTICE,REUSE.toml,pyproject.tomland every SPDX header.version/doiTODO with the ordered release-time procedure.tests/test_citation_metadata.pyso neither defect can return silently.On the names
Both were verified against the ORCID public API rather than transcribed by hand:
Mondragon, without the accent, while this repository writesMondragón Labelsewhere (including in this file's ownabstractandaffiliation). I used each record's own registered spelling rather than "correcting" a name, but if the accented form is preferred for the author entry, changefamily-names— the ORCID iD is what machine consumers key on, so either spelling is safe.On the release-time ordering
The previous comment said only "version and doi are filled at release tags". The ordering is load-bearing and the failure is silent: the Zenodo–GitHub webhook must be enabled before the tag is pushed. Zenodo only archives releases published while the webhook is active, so if it is off at tag time that version is never archived and the only remedy is cutting another release. That is now written into the file as ordered steps, including that the concept DOI belongs in README/citing while
doi:here is the version DOI.Linked tracking
version/date-released/doifields and the Zenodo webhook itself are release-time actions and stay open on that issue.Type of change
feat— new capabilityfix— bug fix (the file did not validate)docs/chore/ci/build/refactor/test/perf!/BREAKING CHANGE:— a deliberate schema-version bumpSelf-review checklist (PRD §12.4)
yaml, already present via mkdocs, exactly astests/test_adr_index.pydoes;cffconvertis deliberately not added.tests/test_citation_metadata.py, five guards.references:block is untouched. SPDX header present on the new test file.Testing
cffconvert --validate -i CITATION.cff→ "Citation metadata are valid according to schema version 1.2.0." The same command against the file onmainfails with theadditionalPropertieserror quoted above.cffconvert -f apalikenow rendersCampos-Chávez E., Mondragon A., The Tether Authors — Tetherinstead of crediting only the entity.pytest tests/test_citation_metadata.py— 5 passed.Negative control: run against the previous
CITATION.cfffrommain, 2 fail —test_at_least_one_named_personandtest_entity_authors_carry_no_person_only_fields— which are precisely the two real defects, and the other three still pass. Restored, all 5 pass.ruff checkandruff format --checkclean.