An existing repository adopts the blueprint by command¶
Context¶
A new copy becomes a repository with blueprint.py create, whose preflight checks first what it needs (decision 0078). The other journey of the guide, An existing repository, had no command: after copier copy, its step 3 asked a person to write the version of the latest release into version.txt and .release-please-manifest.json, to start CHANGELOG.md with ## Unreleased and to give .github/labels.toml the labels of the bots by hand, and step 4 to remove the workflows that the blueprint replaces, without a list of them (#836). A label that is missing lets a bot fail later, and a wrong manifest lets release-please propose the wrong version. Decision 0154 made settings check name a classic branch protection, the first part of the issue.
Three questions decide the shape of the command:
.github/labels.tomlbelongs to the project, and a copied repository has no template to read the labels of the bots from.- Each kind of release keeps its version in another place:
version.txtfor the kindsimple,pyproject.tomlorpackage.jsonfor a Python or Node package. - The preflight of
createchecks that the name is still free, which a repository that exists never is.
Options¶
- Keep the steps by hand in the guide, with a list of the labels and the workflows.
- A migration of
migrate --fixthat adds the labels in every repository on each update. - A command
blueprint.py adoptthat a person runs once, aftercopier copy, with a preflight of its own.
Decision¶
Option 3. adopt writes only what is missing, so a second run writes nothing:
- The version comes from the tag of the latest release on GitHub, its end such as
1.2.3ofv1.2.3, or from--version X.Y.Zfor a repository whose releases GitHub doesn't have; one without a release stays at0.0.0, and its first release is0.1.0. GitHub's latest release leaves out drafts and pre-releases, and a repository may tag its releases without releases on GitHub, so a repository without a latest release that has the tag of a version stopsadopt, which names the highest one for--version:0.0.0there would let release-please count on from the start. A tag of the latest release other thanv<version>, which release-please writes without a component, gets a warning, since release-please may not find that release and then lists every commit in its first one;last-release-shaofrelease-please-config.jsonfixes that. release-please reads the version from.release-please-manifest.jsonfor every kind of release, soadoptwrites it there, and intoversion.txtonly for the kindsimplethatrelease-please-config.jsonnames, the only kind that has that file. The manifest of a Python or Node package belongs to the project, and release-please writes the next version into it with the release. - The changelog gets
## Unreleasedabove the section of its first release. - The labels of the bots are a list in
blueprint/adopt.py, which every repository gets, and a test keeps it equal totemplate/.github/labels.toml.jinja: those of the grouprelease,maintenanceandno-bot-fixes.adoptadds those that the file lacks, in a section of its own at its end, and leaves a label of the project with the same name, in any case, as it is. - The preflight asks Python, Git, where origin pushes to, the GitHub CLI, the repository on GitHub and its latest release, and writes nothing while a finding is marked with ✘, as that of
createdoes. - The workflows of
.github/workflows/that.github/blueprint/owned.txtdoesn't list are named for the maintainer to keep or remove;adoptremoves none, since only the maintainer knows which of them the blueprint replaces.
A migration (option 2) was not chosen: a repository that the blueprint made has the labels from its first copy, and adding them on every update would bring back a label that a project removed on purpose.
Consequences¶
- Step 3 of An existing repository is one command, and step 4 starts from its list of the workflows.
- A new label of the bots in the template needs the same label in
LABELSofblueprint/adopt.py, or the test fails. adoptchanges nothing on GitHub: the labels reach GitHub withsettings applyafter the merge, as before, and a classic branch protection stays whatsettings applynames (decision 0154).