Contributing
Thank you for your interest in citesync. Bug reports, feature requests and pull requests are welcome. Please read the Code of Conduct first, and report vulnerabilities as SECURITY.md describes, not in a public issue.
Report a bug or ask for a feature
Open an issue with the bug or feature form. For a bug, say what you did, what you expected and what happened, with the release or commit you used. A question the README and docs don't answer is a gap in the docs: open a feature request for it.
Scope and response
One person maintains citesync, in their own time. Expect a reply to an issue or pull request within about two weeks.
Before a large pull request, such as a new feature or a change to how something works, open an issue and agree on the change there first. A small fix needs no issue. A pull request outside what the project sets out to do is closed with a link to this section.
Set up and check
The README says how to install the tools, the dependencies
and the git hooks. just check runs the checks CI runs, and just fmt fixes and
formats.
Add automated tests for new functionality and regression tests for fixes. Run a regression test before the fix and check that it fails for the reported reason. Fix every lint and type warning, or suppress it with a stated reason.
uv locks only releases at least a week old. For a newer security fix, pin its source archive at an exact commit, then return to the registry version after a week (how).
Profile
just bench times citesync check on this repo. just profile shows where the time
goes, for check on this repo and write --diff on tests/write/planted: the slowest
imports, a sampling CPU profile with full call stacks, and peak memory. It saves the
results in profile/, which git ignores; open profile/check.html in a browser to explore
the CPU profile. Most of a run is Python starting and importing modules, so a fix usually
moves an import into the function that needs it, and tests/test_rules.py checks that
check doesn't import those modules. CI doesn't time anything: run times on shared
machines vary too much to fail a build on.
When you change a compared field
- Change its comparison and message in
src/citesync/rules.py. Keep normalisation detail only there. - If the field location changes, update its row in codemeta-drift first, then pin the exported mapping here. Keep value conversions such as name splitting in citesync.
- Update the fixtures:
uv run pytest --update-expectedrewrites the expectedcases.jsonandrecord.jsonfrom actual output. Read the git diff before you commit. tests/fixtures/README.md says how the files are made. - Update the docs.
docs/config.mdlists the fields, andtests/test_docs.pyfails if one is missing there. - Run
just mutation, as the README describes.
Write commits and pull requests
- Commits follow Conventional Commits 1.0.0:
type(scope): summary, in the imperative, lower case, with no period. Add a body only when the change needs one, with a bullet per logical chunk. - The pull request title becomes the squash commit subject, so it follows the same rule.
- Both are checked against
committed.toml: a commit-msg hook (installed byprek install) refuses a commit message that breaks the rule, and thepull request titlecheck fails a pull request whose title does. Lower case isn't checked. A revert is titledrevert: <original subject>: rename theRevert "..."title that GitHub's Revert button writes. - The pull request body has the shape of
the pull request template: what it fixes and why, three or
four bullets, a
Tested:line with the proof (the command and its result, or a test that fails without the change), and aNot checked:line with what did not run and why, and any design choice or security path that only a person can judge. "Nothing" is fine. - The changelog (CHANGELOG.md) follows Keep a Changelog 1.1.0. Write each entry for the people who use the project, not as a commit subject. Mark breaking changes Breaking, and put upgrade steps first under the version.
- The release notes are that version's changelog section.
Make a release
The maintainer runs just release X.Y.Z. Publishing has the steps and the one-time setup.
Sign off your commits
Every commit in a pull request carries a Signed-off-by: line, which says you wrote the
change or have the right to submit it under this project's license: the
Developer Certificate of Origin 1.1. git commit -s
adds the line, and the commit-msg hook refuses a commit without it.
To add it to commits you already made, run git fetch origin, then
git rebase --signoff origin/main. That works in a clone of this repository, where origin
is the only remote. If you work from a fork, use the remote that points at this repository
(often upstream) in place of origin. If you have not pushed the branch yet, that is all.
If you pushed it already, update it with git push --force-with-lease, which refuses to
overwrite work you have not seen. Do not use a plain git push --force.
The dco workflow checks every pull request and fails on a commit without the line.
Bot commits on pull requests opened by a bot are exempt.
Who maintains this
Simon van Lierde maintains citesync: reviews pull requests, merges them and
makes releases. The repository belongs to simonvanlierde
on GitHub. A release sets the version in pyproject.toml and CITATION.cff, updates the citation release date, and runs uv lock and uv run citesync write to keep the lockfile and codemeta.json in step. Update the pinned versions in the README and playground snippets and add a dated ## [X.Y.Z] section to CHANGELOG.md. After the release-wide review and checks pass, push the tag vX.Y.Z;
the release workflow does the rest.
Only maintainers can merge to main. A new maintainer is added by an existing one, by name in this section.
If no maintainer can continue, the repository is archived with a note in the README,
and anyone may fork it under its license.