A repository keeps its own answers of bestpractices.dev in a file of the project¶
Context¶
Decision 0047 made .bestpractices.json a file of the blueprint, which every update renders anew, and left the answers that only a project knows to bestpractices.dev. Since 1.23.0, the job best practices entry of Links compares the public entry with the file every week and keeps an issue whose links force each answer of the file that the entry gives otherwise (decision 1046). That left no place for an answer that only one repository can give (#1086):
- An answer of a criterion that the file leaves out, such as
security_review, stayed as it was typed on the site, but nothing in Git held it, and nothing noticed when it went stale. - An answer of a criterion that the file answers too, such as the end-to-end tests of homedarts-for-autodarts under
test, counted as a difference. Saving the links replaced it with the template's words; not saving them left the issue open for ever. The links of player-switch-for-autodarts#302, saved on 2026-11-20, replaced eight answers that way. - A repository had no way to give such an answer: a change of
.bestpractices.jsongets a notice of the check lint and conflicts with the next update that changes the same line, and neithercopier.ymlnor.github/repository.tomlhas a place for it.
On 2026-11-21 the maintainer saved the links of all eight issues, so every entry gave the template's answers, and the answers that only a repository can give were gone from the entries.
Options¶
- Change
.bestpractices.jsonin the repository: the notice of lint, and a conflict with the next update that changes the line. - A question of
copier.yml, or a key of.github/repository.tomlor.github/repository.project.toml: the answers of Copier choose what the template renders, and these files are the settings that the settings bot applies; neither is a place for justifications. - A list of fields that the bot skips: the entry would drift without anyone noticing, and the answer would be nowhere in Git to review.
- Render the project's answers into
.bestpractices.json, or have the fix bot write them there: Copier can't read a file of the project without--trust, and a written file of the blueprint conflicts on the next update. - A file of the project,
.github/bestpractices.project.toml, beside the blueprint's file, whose answers the bot compares and forces like those of the file, checked by a step ofscripts/check.sh.
Decision¶
Option 5:
- The file: one table for each criterion, named as in
.bestpractices.json, such as[test]or[osps_br_07_01]. A table for a criterion that.bestpractices.jsonanswers gives onlyjustification, which replaces the file's; the status stays the template'sMet. A table for any other criterion givesstatusandjustification. The template renders the file once, with a comment alone; it is in_skip_if_existsand in the list of the files of the project ofAGENTS.md, which also says that an answer of the repository alone goes there, never into.bestpractices.json, andINSTEADofblueprint/ownership.pynames it for a pull request that changes a file of the blueprint. - The answers of a repository are both files:
answers()ofblueprint/best_practices.pyreads.bestpractices.jsonwith the tables of the project file in place of the same fields, andkeep_issue()compares, links and closes on these answers, sodifferences(),edit_links()andbody()have one source. The issue marks each answer that is the project's own and says that it is changed in the file, not on the site, since the next weekly run forces it back over an edit on bestpractices.dev, and that Save (and continue) 🤖 reads only.bestpractices.json. A repository without the project file, or with only the empty one, gets the same issue as before. - The check:
blueprint.py best-practices --verify, the step Answers for bestpractices.dev ofscripts/check.sh, checks the file without the network and passes when it is missing. It fails on a criterion thatbestpractices-criteria.jsondoesn't know or a key other thanstatusandjustification; a status for a criterion that.bestpractices.jsonanswers; a criterion of its own without both; a status other thanMet,UnmetorN/A, orN/Awhere the criterion doesn't allow it;Metwithout a link where the criterion needs one; a link to a file or a heading of the repository that the checkout doesn't have, asgone_files()andanchors()read them; a link that doesn't use https; a justification too long for one link of the issue (LIMIT); and a justification thatsame()finds equal to the one of.bestpractices.json. That every status has its justification is the blueprint's own rule, stricter than the site, so that every answer in Git says why it holds. - The fix:
--verify --fix, theautofixof the step, removes a statusMetfor a criterion that.bestpractices.jsonanswers and a justification that only repeats the file's, so a release that starts to answer a criterion fixes itself in the update pull request of every repository. A statusUnmetorN/Afor a criterion that the template now guarantees still fails: one of them is wrong, and a person decides which. - The blueprint's own answers: its
.github/bestpractices.project.tomlgives the justifications oftest,test_continuous_integrationandversion_tags_signedthat only the blueprint can give, each checked against the repository as it is: the coverage ofblueprint.pyagainst a simulated GitHub, the tests of the nine kinds and the Variants workflow, and the signed tags since v0.6.0.
This isn't option 2 of 0047, a file copied once that never learns of a change of the blueprint: the template still gives every answer that it guarantees, and an update still brings each of them; the project file holds only what the template can't say.
Consequences¶
- An answer that only one repository can give lives in Git, is reviewed in its pull request and reaches the entry through the links of the weekly issue, which closes once the entry gives it.
--verifynotices a file or a heading that is gone, and a copy of the template's words, but not words that no longer hold: a person keeps each sentence true, as for every answer of the project.- Each repository brings back the answers that saving the links of 2026-11-21 replaced by moving them into its own file; the changelog says how.
- Whether bestpractices.dev limits the length of a justification below the length of one link is not measured; the check holds a justification to what one link of the issue can carry.