Development¶

This page is for maintainers of pkdb_data. It describes the checks that run on study folders, the pins that fix their result, the workflows and the settings they need. Curators find the workflow of a study in the curation guide. Everything about study format 2 runs on format 2 folders only; format 1 folders are skipped.

Pre-commit¶

Set up the hooks once per checkout:

uvx pre-commit install

Install uv first, because the hooks need uvx on the PATH. The first run needs network access, since uv fetches Python 3.14 and the pinned pkdb. Run all hooks on the repository with uvx pre-commit run --all-files. The hook pkdb-check then runs pkdb check --staged, which checks only the staged studies. To check every study with the pinned pkdb, for example after a change of a pin, run env PKDB_NO_UPDATE=1 uvx --python 3.14 --with-requirements requirements/pkdb.txt pkdb check --format human.

Other repository settings that matter to curators: .gitignore ignores the state files .*.pkdb-base of the workbook sync, and .gitattributes sets LF line ends for TSV and JSON files and marks PDF, PNG, JPG and XLSX files as binary. The line studies/**/*.xlsx is added to .gitignore only in the cutover pull request. Until then pkdb check refuses a tracked format 2 workbook.

Pins¶

Two files fix what the checks answer, so a result changes only when the data or a reviewed pin changes. Pre-commit and the workflows read the same files.

• requirements/pkdb.txt holds pkdb==0.12.15, the release whose vocabulary has the effect summaries ACE inhibition maximum, ACE inhibition tmax and ACE inhibition AUEC and those of renin activity (change absolute), and the filtration fraction, whose vocabulary has the substance chlorthalidone and the method ambulatory blood pressure monitoring, whose pkdb migrate refuses unmapped numbers of the rows that it converts, whose vocabulary has radioactivity excretion rate, whose paper tables can have their raw table as the source when no image exists, whose pkdb migrate keeps the WebPlotDigitizer projects of a format 1 folder and whose vocabulary has the terms of the remaining format 1 studies, that does not check the rows of dismissed review items, whose scatters hold several points of one subject (each row of scatters_<source>.tsv is a point, and pkdb migrate pairs the points of a format 1 dataset by its shared fields, row among them), whose curation app shows the tables of a study first, the notes of each table at the table and the PDF of the study beside its tables, numbers the lines of a table from its header as line 0, whose pkdb migrate writes the counts of the format 1 tables and single-row array outputs as outputs and refuses a study whose format 1 rows hold numbers in any column that study.json does not map (unmapped_value), and whose bundled vocabulary has the terms of the format 1 studies, among them disease duration, csf/plasma ratio, renal plasma flow and negative inhibition values; it keeps the substance labels of the study issues, which releases before 0.12.3 remove again. Dependabot cannot update it, because it runs out of disk space cloning this repository (Dependabot::OutOfDisk). To update it, change the version, run the command that checks every study (see Pre-commit) and open a pull request. Curators and agents install the pinned release with uv tool install --python 3.14 --force pkdb --with-requirements requirements/pkdb.txt, run it again after a pin change and set PKDB_NO_UPDATE=1; the hook and the CI decide, so nobody curates with a newer release. A change of this file makes the studies workflow check every study.
• vocabulary.lock.json is the vocabulary snapshot of the server. It is written by pkdb vocabulary sync --output vocabulary.lock.json with PKDB_ENDPOINT set to the server. The vocabulary workflow refreshes it every week. A change of this file makes the studies workflow check every study.

Workflows¶

studies. A pull request checks the changed study folders with pkdb check --changed <merge base>. A push to develop checks the studies changed since the previous head. A change of requirements/pkdb.txt or vocabulary.lock.json, and a manual run, check every study. The workflow clones the repository without blobs and with a sparse checkout, and fetches whole study folders: the changed ones, or the study format 2 folders when it checks every study. .github/scripts/sparse-studies.sh selects them, and the vocabulary workflow uses it too. Whole folders keep the result the same as in the hook, which sees every file of a study. It never contacts the server.

issues. Keeps one GitHub issue per study aligned with its title, labels, assignees and state (see GitHub issues of studies). One run at a time. A manual run has the input dry_run, which shows the plan and changes nothing; start the workflow once with it after the first merge. The step pkdb issues sync --adopt, which gives existing studies an issue, is a manual step of the cutover and is not part of the workflow.

vocabulary. Runs pkdb vocabulary sync. When the lock changed, it checks every study with the new lock and opens or updates the pull request vocabulary/refresh with the new lock and the check summary. It closes that pull request again when the vocabulary of the server returns to the version in develop. A pull request opened with the workflow token starts no other workflows. A maintainer closes and reopens the pull request to run the required studies check, and merges when it passes.

Settings the workflows need¶

Rulesets¶

The rulesets in .github/rulesets/ require the checks docs and studies on develop. A maintainer with admin permission applies them after the merge, and again after every change of the JSON files:

gh auth login
.github/rulesets/apply.sh

The script is idempotent. A ruleset removed from the directory stays on GitHub and has to be deleted there.

Releases¶

A release names a state of develop, which main then tracks, and its notes list the changes since the release before. To make one:

1. On a branch of develop, set version and date-released in CITATION.cff, write release-notes/<version>.md, and merge the branch through a pull request.
2. Move main to the merge commit: git push origin <commit>:main. The ruleset of main allows only this fast-forward.
3. Create the release, which creates its tag: gh release create <version> --target <commit> --title <version> --notes-file release-notes/<version>.md.

The major version changes with the study format or the layout of the repository.

Documentation¶

The site builds independently of pkdb. From the repository root:

uvx --from "$(cat docs/requirements.txt)" zensical build --clean --strict
python3 scripts/llms_txt.py

zensical serve with the same --from argument previews the site. Update zensical.toml when you add or remove a page. Do not commit the generated site/.