Add CITATION.cff and automated Zenodo deposit - #124
Draft
stefanoamorelli wants to merge 2 commits into
Draft
Conversation
stefanoamorelli
force-pushed
the
feat/zenodo-citation
branch
from
July 26, 2026 10:23
e0757f7 to
f33cf86
Compare
stefanoamorelli
changed the title
Papers already cite the Top 10 (NVIDIA's garak paper cites the first
version), but with no DOI there is no identifier for Crossref, OpenAIRE
or Google Scholar to resolve against, so finding that use means manual
searching. This adds citation metadata and a workflow that deposits each
edition to Zenodo, which mints the DOI.
CITATION.cff carries the authors of the 2026 entries. GitHub renders it
as "Cite this repository", and the release workflow builds the Zenodo
record from it, so the author list is maintained in one place rather
than two.
.github/zenodo.config.json holds the file list for each deposit.
`{edition}` comes from the release tag, so the 2027 edition needs no
config change. Each key under `deposits` is a separate Zenodo record,
so any future publication from this repo can take its own concept DOI
instead of becoming a version of the Top 10.
.github/scripts/zenodo_release.py builds the bundle and deposits it
through the Zenodo REST API, with `--check` to validate the config and
CITATION.cff, `--dry-run` to print the file list, and `--sandbox` to
target sandbox.zenodo.org. The workflow deposits on release and runs the
first two on pull requests that touch these files. documentation/ZENODO.md
covers setup and the release steps, and the README gains a citation
section and a DOI badge, commented out until the first release supplies
the number.
The 2026 deposit holds 22 files (2.6 MB): the ten entries, the preface,
the AISVS appendix, three published figures and CITATION.cff. It
excludes the 2025 list, 2026/working/ and the diagram tool's scratch
files under report/images/screenshots and report/images/uploads.
Editions are versions of one Zenodo record, each with its own DOI under
a concept DOI that resolves to the newest. Cite the concept DOI. This
follows DataCite's versioning guidance for major revisions of a work.
I did not use Zenodo's GitHub integration. It archives the whole
repository tarball at the tag with no include/exclude option, so the
2026 DOI would ship the 2025 list and the working drafts, and it
supports only one record per repository.
Four values are still missing and marked TODO where they belong: the
real publication date, which stands at the sprint plan's 2026-06-15
target; the contributor list, for reviewers and editors who are not
credited as entry authors; the concept DOI, which Zenodo issues at the
first publish; and author ORCIDs, which are optional.
Publishing also needs the ZENODO_TOKEN secret, and the
ZENODO_CONCEPT_RECID variable once the first publish reports it.
Without the latter, each release mints an unrelated record and the
citation history splits.
Signed-off-by: Stefano Amorelli <stefano@amorelli.tech>
The deposit path had no test coverage: every assertion so far came from --check and --dry-run, which never issue a request. test_zenodo_release.py stubs the requests module and runs both paths, the first deposition and a new version of an existing concept record. It asserts the call sequence, that inherited files are removed before the new bundle is uploaded, that draft mode skips the publish action, and that --sandbox never reaches the production host. It also pins the metadata shape: creators as 'Family, Given', publication_date as ISO8601, and no 569JNRXghklprefixed config comments leaking into the payload. Confirmed cc-by-sa-4.0 against Zenodo's live licence vocabulary. The /api/licenses path now redirects to /api/vocabularies/licenses. The tests stub the API, so they do not prove Zenodo accepts the metadata. That still needs a sandbox run with a real token. Signed-off-by: Stefano Amorelli <stefano@amorelli.tech>
stefanoamorelli
force-pushed
the
feat/zenodo-citation
branch
from
July 26, 2026 11:06
f33cf86 to
b3e6502
Compare
Collaborator
Author
|
cc @rocklambros |
Collaborator
|
@stefanoamorelli Thanks for putting this together. The version-DOI-under-a-concept-DOI structure is the right model, and skipping Zenodo's native GitHub integration was the correct call given it would archive the whole tarball including the 2025 list and the working drafts. Holding this for now. The 2026 content is locked ahead of release, and we do not want a deposit workflow pointed at a moving target. For the first edition we will likely do the Zenodo deposit manually once the document is released, then come back and wire up the automation with the concept record ID already in hand. That removes the risk you flagged of a first automated run splitting the citation history before Leaving this open as a draft. I will follow up here once the release date is fixed. If we go the manual route for 2026, |
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
2 participants
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.
As discussed internally, citing the
OWASP Top 10 for LLM Applicationsis currently difficult. For example, NVIDIA's garak paper (arXiv:2406.11036) cites the first version, but finding that reference took manual searching, and there is no identifier for Crossref, OpenAIRE or Google Scholar to resolve against.With this PR I'm giving the project a DOI, a permanent identifier that resolves to the work no matter where it moves, through Zenodo, the open repository run by CERN.
Context
Zenodo mints two kinds of DOI. Each release gets a version DOI that points at that exact edition and never changes. All of them sit under a single concept DOI, sometimes called the parent DOI, which resolves to whichever edition is newest.
Future editions are additive: add
2027/final/, updateCITATION.cffwith that edition's authors, tagv2027. Each version keeps the author list it was published with, so contributors to an earlier edition stay credited on that edition's DOI permanently.CITATION.cffpowers GitHub's "Cite this repository" and is the single input for the Zenodo record, so the author list is maintained in one place. The deposit is scoped to2026/final/: the ten entries, the preface, the AISVS appendix and the figures.Pending items
ZENODO_TOKENsecretItems after merge
v2026; the workflow deposits and publishesZENODO_CONCEPT_RECIDvariable from the run log, otherwise every future edition mints an unrelated record and the citation history splitsCITATION.cff, the README badge and genai.owasp.org