Changelog
All notable changes to this project are documented here.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
Unreleased
Added
- Documentation code examples have keyboard-accessible copy buttons and feedback when copying is blocked.
- The website publishes an accessibility statement, with keyboard instructions and testing limitations. Documentation links include page-specific social previews.
Changed
- The playground and documentation use a shared green design with local IBM Plex Sans fonts. File actions sit above the preview; documentation search sits beside the article on desktop, with compact navigation on phones (playground guide).
Fixed
- Playground file selectors display their dropdown arrows under the website's Content Security Policy.
0.6.0 - 2026-11-14
Added
- The documentation website includes installation, playground guides and reference pages beside the playground. Search the full documentation without leaving the website; guides remain readable without JavaScript.
- The playground's Field lookup searches the pinned CodeMeta mappings across six metadata formats, including fields those formats cannot represent (playground).
- Shared website links show a social card with an example of package metadata converted to CITATION.cff.
- Opt-in
required-fieldschecks report missing values in selected metadata files asrequired-field-missingerrors. Missing files and values fail even when the source lacks the facts. Default omission handling and write behavior stay the same. dataset-codemetaanddataset-license(plus--dataset-codemetaand--dataset-license) write and check a dataset CodeMeta file (@type: Dataset, defaulting todataset.codemeta.json) forsourceledger release --codemeta, keeping code and dataset licences separate, including RO-Crate and Croissant checks and optional required-field checks (configuration).
Changed
- On the same v0.5.0 metadata,
checkaveraged 60.2 ms versus 61.5 ms in 0.5.0 (about 2% lower). Both used Python 3.14.4 with JIT disabled and 30 runs after three warm-ups; shared-host variation exceeds the difference.
Fixed
-
Both pre-commit hooks now recognize
dataset.codemeta.json, including nested paths. For custom names, usealways_run: true(hook setup). -
CLI help and finding links open the on-site documentation.
-
Existing dataset CodeMeta files now have their Dataset resource type checked and repaired by
write(configuration). -
Software citation exports no longer inherit a dataset's licence or other fields when the software source lacks them. Dataset files supply export values only when explicitly selected as the source.
-
Choosing an output format stays selected while the preview updates.
-
Documentation navigation preserves command names and marks the current guide or section. Reference tables scroll on narrow screens without splitting filenames; field lookup starts with a search prompt.
0.5.0 - 2026-11-10
To upgrade from 0.4.0:
- citesync needs Python 3.13 or newer, the git hooks included.
- A run that couldn't finish exits 3, not 2: a script that tests for 2 tests for 3. In
--jsonoutput,versionis nowschema_version, and every report haserrors(output). checkcan fail on a codemeta.json that passed before: an unknown key is now anunknown-termerror, andtypst.tomlkeywords compare with their separators.ignore = ["unknown-term"]andkeywords-ignore-separators = truekeep the old behaviour (configuration).
Added
checkreports a codemeta.json key that isn't a term of its CodeMeta version as anunknown-termerror, with the closest term or the version that has it, and one another declared context may define as aforeign-termwarning. The term lists come from codemeta-drift's export, for CodeMeta 3.0, 3.1 and 4.0 (checks). A codemeta.json that passed before can now fail;ignore = ["unknown-term"]in the config turns the check off.- The playground makes incomplete R DESCRIPTION, Julia Project.toml, Typst typst.toml and Quarto _extension.yml templates beside the Python, Rust and JavaScript ones (playground).
checkcomparesro-crate-metadata.jsonandcroissant.json, as sourceledger'sreleasewrites them, with the source on every field, from codemeta-drift's new rows. It finds them at the repo root, or undermanifests,writenever changes them, andinittakes nothing from them (dataset files).citesync export --format risand--format endnoteprint a RIS or EndNote tagged record of type computer program, each tag where codemeta-drift's rows put it. List a.risor.enwfile underexportsto keep it in step; the playground offers both (citation exports).citesync export --format dataciteprints DataCite Metadata Schema 4.7 XML (citation.datacite.xml, resource typeSoftware). List a.datacite.xmlfile underexportsto havewritekeep it in step andcheckreport it asexport-stale. It needs a DOI, an author, a publisher and a release year, and says which source field to set when one is missing. The playground offers it when the record has all four (citation exports).
Changed
- Breaking: exit codes and JSON reports follow one convention across the tools: 0 done, 1 an error finding, 2 a usage error, 3 citesync couldn't run (a bad config, a missing source file), 130 interrupted with Ctrl-C. A run that couldn't run exited 2 before, the same code as a mistyped option. The
--jsonreport names its versionschema_version, notversion, and has anerrorslist of{message, help}objects; a run that couldn't finish prints a report with only its errors instead of a line on stderr (exit codes, JSON). - Breaking:
typst.tomland_extension.ymlare read through their own rows in the field mapping, not Cargo's and npm's.initandexportnow take a Quarto extension'stitleas its name;checkstill doesn't compare it.typst.tomlkeywords are now compared with their separators (big datais notbig-data), as other manifests' are; setkeywords-ignore-separators = trueto keep the old leniency (plugin manifests). - The field mapping uses codemeta-drift 0.8.0, which adds rows for DataCite, typst.toml, Quarto extensions, RIS, EndNote, RO-Crate and Croissant among others, reads PKG-INFO's
Authoras a list, and mapping paths can now combine parts with+and filter on a member of a list. - PKG-INFO, METADATA, R DESCRIPTION and Julia Project.toml files are read through codemeta-drift's own rows for those formats, not reshaped into PEP 621 or CodeMeta first. What each one gives is unchanged, and
checkfindings on them now carry a line number (formats). - The playground's input and output file lists are grouped under labelled headers, sorted by name and searchable, and Names look right closes the name split until the author names change (playground).
Fixed
- An empty
.gitfolder, such as a stray/tmp/.git, no longer marks a repo root. Like git, citesync now needs a.gitfolder withHEAD, or a.gitfile. Before, a stray one moved the root, and GitHub and SARIF output gave paths relative to the wrong folder. citesync initandexport --format cffname each manifest they skipped, such as a private package.json, and say how to read it. Before, its licence and keywords were left out without a word (init).- A codemeta.json that holds its version as
softwareVersionis checked against the source, andwriteupdates it there. Before, its version was never compared. - The
schema.jsonldexport writeslicenseonly as a URL: the SPDX page for a single licence id, or the URL the source gives. ALicenseRef-id, an expression such asMIT OR Apache-2.0and other text are left out instead of written as a made-up or non-URL value. - A PKG-INFO or METADATA
Authorsuch asDatadog, Inc.is one author, not two: a company suffix stays with the name before it, and anet al.entry is dropped (formats). initreads the manifests themanifestssetting lists, so a Quarto extension under_extensions/<name>/can give the new CITATION.cff (init).- A codemeta.json with no
@contextis reported as having none, not as@context None is not CodeMeta. write --diff -qno longer prints thewould fixcount on stderr.
Removed
- Breaking: Python 3.12 is no longer supported. citesync needs Python 3.13 or newer.
0.4.0 - 2026-11-01
Added
citesync export --format apa|bibtex|csl-json|jsonldprints a citation made from the source. List files underexportsto havewritekeep them in step,checkreport a stale one, and the pre-commit hooks run when one changes (citation exports).citesync export --format cff|codemeta|zenodoprints the CITATION.cff, codemeta.json or .zenodo.json citesync would make from the source, without writing it (citation files).- APA 7 references and schema.org JSON-LD for websites, in the CLI and the playground.
- Check and update Typst
typst.tomland Quarto_extension.ymlplugin manifests, so a release moves their version with CITATION.cff;initreads them too (plugin manifests).
Changed
- The field mapping uses codemeta-drift 0.5.0, with its schema 1.4 contract and rows for PKG-INFO, R DESCRIPTION, Julia and BibTeX. Its paths for the six formats citesync already read are unchanged.
- PKG-INFO and METADATA take the description from Summary only, not the README in Description or the body, and the repository from a Project-URL labelled source, repository, sourcecode or github before Home-page (distribution metadata).
- BibTeX and CSL-JSON citation keys come from the title, such as
credit-matrix, instead ofsoftware. - BibTeX citations are biblatex-software
@softwareentries with the version, licence, DOI, SWHID, abstract and keywords, named as codemeta-drift's bibtex rows name them. Plain BibTeX styles print them as@misc(citation exports). - An R DESCRIPTION gives the citation name as
Package: Title, as cffr and codemetar do, instead of the title alone (R and Julia imports). - A Julia Project.toml no longer gives a description or licence: the format has neither field, so keys added by hand aren't read (R and Julia imports).
Fixed
citesync initkeeps every author when package.json is the source and codemeta.json or .zenodo.json lists more than one (init).citesync writenames the file it can't write and why, such as one in a read-only folder, instead of reporting an unexpected error (writing).- An
authorlist in package.json is reported asunreadableinstead of being skipped without a finding (checks). citesync initstops when the source named with--sourceorsourceis missing, instead of building CITATION.cff from another file (init).
0.3.0 - 2026-11-01
Added
- Generate citation files in the browser playground from an existing metadata file or basic project details, with live previews, input detection and editable author names. Export CITATION.cff, CodeMeta, Zenodo metadata, BibTeX and CSL-JSON; Python, Rust and npm outputs are labelled as incomplete package templates (guide).
- Import Python PKG-INFO/METADATA, R DESCRIPTION and Julia Project.toml/JuliaProject.toml in the CLI and playground without executing package code. Imported files remain read-only; unsupported or omitted values are reported (supported files).
- Create a missing .zenodo.json with
citesync writewhenfileslists it. Setzenodo-contributor-typeto supply a default for new contributors; existing types are preserved (configuration, writing). - Use the contribution handoff guide for linked CodeMeta people and roles from CRediT Matrix, and the Pandoc guide for software citations from CSL-JSON or BibTeX.
- A Matrix consumer check runs the published Credit Matrix 0.10.0 CLI through citesync write/check, including linked roles, local identities and explicit Zenodo contributor types.
Changed
- The field mapping uses codemeta-drift 0.4.0, with original crosswalk cells and its schema 1.3 contract. Field paths remain unchanged.
- The playground uses larger text for file previews, code snippets, hints and footer links.
Fixed
- CodeMeta person identifiers that are not ORCIDs no longer overwrite ORCIDs in other files. Writes preserve these identifiers and refuse to remove a person if that would discard them. Both
id/@idandtype/@typespellings are supported (contribution guide). citesync writepreserves a byte order mark at the start of CITATION.cff (writing).
0.2.0 - 2026-10-30
To upgrade from 0.1.0:
citesync checkhas five new error rules:contributor-mismatch,date-mismatch,swhid-mismatch,zenodo-license-listandfile-missing. To turn any of them off for now, list it underignore(docs/rules.md).codemeta-versionno longer defaults to 3.0. To keep checking codemeta.json's@contextas before, setcodemeta-version = "3.0".- Use citesync through its command line or the pre-commit hook. Its Python modules are internal and may change in any release.
write-manifeststakes onlyversion,author,contributor,license,codeRepositoryandkeywords, the fields a manifest holds. Take any other field off the list.- The text output changed: each finding starts with
file:line:coland has ahelp:line under it, a failing check ends with anN fixableline, andcitesync writeends withN fixed, M left in K files. In GitHub output, each annotation ends with itshelp:line and the::notice::line gives write's new count, so scripts should read--format jsoninstead (docs/output.md).
Added
citesync initwrites a CITATION.cff from codemeta.json, .zenodo.json and the package manifests when a repo has none. It passescitesync checkwhen those files already agree, andcitesync writefixes the rest (docs/init.md).- Contributors are compared across codemeta.json, .zenodo.json and package.json, the same way as authors (
contributor-mismatch). - Release dates are compared across CITATION.cff, codemeta.json and .zenodo.json (
date-mismatch). - Software Heritage identifiers (SWHIDs) are compared across CITATION.cff, codemeta.json and .zenodo.json, and
citesync writefixes them (swhid-mismatch, docs/check.md). version-behind-tagwarns when the source's version is older than the repo's newest git tag.--format sarifprints a SARIF log that GitHub code scanning can upload.citesync writecreates codemeta.json when thefilessetting lists it and it doesn't exist yet.citesync --helplists the exit codes and where config is read from.citesyncwith no command prints the help.- Two rules for repos where Zenodo reads CITATION.cff:
zenodo-license-listandzenodo-drops-field. - A keyword that differs from another file's only in hyphens, underscores or spaces is named as such, and
citesync writegives it the source's spelling.keywords-ignore-separators = truetreats such keywords as equal. - A failing
citesync checksays how many findingscitesync writewould fix, andcitesync writehow many it fixed and left (docs/check.md). -vnames each manifest check left out, and why (manifest-skipped).citesync configprints the repo root in use.--color auto|always|neversets colour whateverNO_COLORandFORCE_COLORsay, and-Vis short for--version.- Each finding on a key gives the key's line and column, so an editor or code scanning can jump to it (docs/output.md).
- A mistyped rule id,
--formatvalue orwrite-manifestsfield gets a "did you mean" suggestion. On Python before 3.14, option values get none.
Changed
- Breaking:
codemeta-versionhas no default. When it's unset, any CodeMeta version passes andcitesync writeleaves@contextalone. - Breaking: a file listed in the
filessetting that doesn't exist is afile-missingerror. 0.1.0 skipped it. - The field mapping comes from codemeta-drift 0.3.0, which adds contributors, release dates and SWHIDs.
citesync checkstarts about a third faster.- Breaking:
write-manifests = "all"means the six manifest fields, and naming any other field is a config error. - A keyword finding between citation files lists the missing and extra words, not both files' lists.
- A missing source file names the directory citesync looked in. Run outside any citation files, citesync uses the git root, and
--rootmust be a directory. - A bad
ignoreentry is named in the error, and an unquotedcodemeta-version = 3.0says to write it as a string (docs/config.md). - The warning about an unused
ignoreentry is quiet under-q.
Fixed
citesync writedropped an author's ORCID when the source renamed them and had no ORCID for them. It now leaves that file's authors for you to edit (docs/write.md).citesync writewrote a CITATION.cff entity (an author with only a name) to codemeta.json as aPerson. It's now anOrganization.citesync writereformatted the existing entries of a JSON author list when it added an author.python -m citesyncfailed with "No module namedcitesync.__main__".- With
doi: ""in CITATION.cff, the DOI underidentifierswas ignored. - codemeta.json entries written with
typeandidinstead of@typeand@idwere ignored. - A name in one string, such as codemeta.json
name, written family name first (Tu Youyou,屠呦呦) was anauthor-mismatchagainst CITATION.cff's given and family names, andcitesync writerewrote it. - A title with an accent typed two different ways didn't match itself.
citesync writefolded an author'sname-particleandname-suffixintofamily-nameswhen it changed the given name.- GitHub annotations didn't attach to their files when the root was a subdirectory of the git repo.
- codemeta.json keywords given as one string weren't split on full-width (
,) or ideographic (、) commas. - A manifest or .zenodo.json that starts with a byte order mark gave a confusing parser error.
- A file behind a symlink that points out of the repo was read, and
writecould change it. It's nowunreadable. - Control characters in a file could retitle the terminal or hide lines. They now print as
\xNN. - Printing non-ASCII text to a stdout that isn't UTF-8, such as a Windows pipe, crashed.
- Some inputs made
citesync checkrun for minutes, such as an author string with a long run of spaces or a keyword list thousands long. - A repository URL with whitespace before a trailing slash, such as
https://example.org/r /, kept that whitespace when read. citesync writedropped the comments above a---line at the top of CITATION.cff.- An author with an ORCID and no name was written to pyproject.toml, Cargo.toml or package.json as an empty entry, one more on each run.
citesync writenow leaves that list for a hand edit and says why. citesync writeturned every line end of a file with both LF and CRLF line ends into CRLF, even when it changed nothing else. It now keeps the more common one (docs/write.md).
0.1.0 - 2026-10-29
Added
citesync check: compares title/name, version, authors with ORCID, licence, DOI, repository URL, description and keywords across CITATION.cff, codemeta.json, .zenodo.json, pyproject.toml, Cargo.toml and package.json, with any of them as the source. Exit 0 when they agree, 1 on an error finding, 2 when citesync couldn't run (a bad config or option, a missing source file, an internal error).- Each finding names its rule, such as
version-mismatchorkeywords-not-subset, and has a severity.citesync ruleslists the rules andcitesync explain <rule>describes one; docs/rules.md has them all. - A file citesync can't read or parse is an
unreadablefinding, with the parser's line and column when it gives them, and the other files are still checked against each other. - Output as text, JSON (
--format jsonor--json) or GitHub workflow annotations (--format github). Text is coloured on a terminal (NO_COLORandFORCE_COLORare honoured) and ends with a summary line;--quietprints only errors. JSON is one document with aversion, the tool, a summary and the findings, each with its rule, severity, help, a link to the rule's docs and its position when known. GitHub output ends with a notice that counts the findings. JSON always lists every finding, whatever-qor-vsay. - A JSON compatibility policy: a minor release may add rule ids and optional fields, so ignore what you don't know; removing or retyping a field bumps the report's
version, in a major release. citesync --version.- Without
--root, citesync walks up from the current directory to the nearest directory with a citation file or a citesync config, stopping at the git root. - A
role-danglingwarning for a CodeMetaRolein codemeta.json'sauthororcontributorlist, such as a CRediT role from credit-matrix, whoseschema:authorORCID no listed person has.writekeeps Roles as they are. - A pre-commit hook,
citesync, for prek or pre-commit. It runscitesync checkwhen a commit changes a citation file, a package manifest or citesync's config, at any depth, and fails the commit on an error finding. - A manual-stage hook,
citesync-write, that runscitesync writewhen you ask for it. ignorein the config drops the findings of the rules it lists, and warns about an entry that matched nothing.citesync config, and config discovery fromcitesync.toml,.citesync.toml, pyproject.toml, Cargo.toml or package.json. Config keys are kebab-case, such ascodemeta-version.- The field mapping, vendored from codemeta-drift 0.1.0 with its JSON Schema.
- An author with only a name, such as an organization, compares as a family name in CITATION.cff, codemeta.json and .zenodo.json, and write keeps it.
- Keywords compare case-insensitively, as author names do, so
LCAmatcheslca. Setkeywords-case-sensitive = truein the config to compare them by case. codemeta.json may give them as one comma-separated string, as schema.org allows. - Repository URLs compare by the repository they name:
http://www.github.com/Owner/Repo/tree/v1.0matcheshttps://github.com/owner/repo. Branch, tag and file pages count on GitHub, GitLab, Codeberg, Gitea and Bitbucket; paths ignore case on GitHub only. Findings show the URLs as written. - A codemeta.json
identifiergiven as a schema.org PropertyValue is read as a DOI when itspropertyIDisDOIor itsvalueorurlis a DOI. Other PropertyValues, such as a SWHID or a ROR id, are skipped. - Versions compare as PEP 440 versions, so
v1.2.3matches1.2.3,1.0matches1.0.0and0.3.1-rc.1matches0.3.1rc1. A version that isn't PEP 440, such asunreleased, must match exactly. citesync write: rewrites the citation files that disagree with the source, and the manifest fields listed inwrite-manifests, keeping comments, key order, formatting and CRLF line ends, and writing through symlinks. Fields a file leaves out stay out. A value a file can't hold without losing something is left for you, with the reason: a compound licence in .zenodo.json, anANDlicence in CITATION.cff or codemeta.json, a version semver can't spell in Cargo.toml or package.json, a version that isn't PEP 440 in pyproject.toml, or a renamed author whose old entry holds an email or affiliation. It reports the findings left ascheckdoes, each saying what to do, and never writes an ignored finding or an unreadable file. Exit 0 when the files agree afterwards, 1 when an error finding remains, 2 when it couldn't run and wrote nothing.citesync write --diffprints the edits write would make as a unified diff and writes nothing. Exit 0 when there is nothing to change, 1 when there is or when a file can't be read (listed on stderr), asruff format --diffdoes.