Bestie Features

Adding Bestie features to a package

bestie add-feature applies a named slice of the BestieTemplate copier template to an existing package: only the feature's files are written, everything else is left untouched. Requires only uv on the PATH.

bestie in the commands below stands for this full invocation:

uvx --from bestie-template bestie

(The --from is needed because the package is bestie-template and its command is bestie.) Inline the full invocation in every command — do not rely on a shell alias or variable, which won't survive when each command runs in a fresh shell.

Workflow

1. Discover what can be added:

   bestie list-features --json

   Each entry has name, description, required_fields (answers you must be able to supply), requires_answers (needs an existing .copier-answers.yml), and optionally optional_files (extra config files written only if missing, keyed by the boolean answer that enables them). Feature names are exact (e.g. the testitem runner is testitem_cli, not testitem); if you pass a name that doesn't exist, the error lists every valid name.

2. Check the working tree before applying. A feature overwrites its included_files without warning, no conflict prompt and no backup — testitem_cli replaces an existing test/runtests.jl outright, discarding whatever was there. optional_files are the opposite: written only if missing, so an existing one (e.g. a hand-tuned .lychee.toml) is left untouched. Git is the only recovery path for included_files, so run git status first:

   • Uncommitted changes to any of the feature's included_files: stop and tell the user those changes will be lost. Let them commit or stash before you continue.
   • A file the feature owns exists and is committed: say so and what will replace it, and get the user's go-ahead before applying.
   • Not a git repository: do not apply. There is no way to undo it.

3. Apply, from the package root (or pass the package path as second argument). Multiple features are one comma-separated argument, no spaces:

   bestie add-feature changelog,dependabot [PATH]

4. Verify with git status / git diff: only the feature's included_files should appear as modified, any missing optional_files as newly added, plus .copier-answers.yml if the package already had one. Read the diff of every pre-existing file the feature touched — "Applied 1 feature(s)" is printed just the same whether the file was created or overwritten, so success output is not evidence that nothing was lost.

   In that .copier-answers.yml diff, expect the feature's answers to change and _commit / _src_path to stay put. Those record the template version the package was last fully updated to, and a feature applies only a slice, so they deliberately do not move. The package is then holding one file newer than the version it records — that is the intended state, and a later template update may report a conflict on that file, which is normal. Do not "fix" the mismatch by editing _commit.

A clean diff means the feature applied, not that the package is done: a feature may require follow-up changes to files it does not own (e.g. testitem_cli replaces the test runner, so existing tests must be migrated to @testitem blocks and a test/Project.toml must exist). Check the feature's description and the rendered files for such expectations, and tell the user about any follow-up work you find.

Recommending features

When asked what a package could use rather than for a named feature, start from list-features --json and narrow it against the package itself. Present the result as a short list of what is missing and worth adding, with a one-line reason each; do not apply anything without the user's go-ahead.

• Drop what is already there. Check each feature's included_files against the package before recommending it. For files the template protects (see Protected files), the feature reports "applied" while writing nothing, so recommending one that already exists produces a no-op the user may read as a change.
• lint_action needs an answers file; lint_action_explicit doesn't. lint_action has requires_answers: true and fails on any package without .copier-answers.yml. Prefer lint_action_explicit there — it takes AddPrecommit/AddLychee as -d flags instead.
• Flag the cost of testitem_cli. It rewrites test/runtests.jl and obliges a test migration, so it is a proposal to discuss, not a quick win to bundle with the others.

Offering the badge

Packages that use BestieTemplate can carry a badge in their README saying so, as a way of showing support for the template. Packages generated from the full template have it already; no feature adds it, and add-feature never touches the README, so for a package adopting features one at a time it is a one-line edit — placed with the README's other badges, matching how they are laid out — that you make only with the user's go-ahead.

[![BestieTemplate](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/JuliaBesties/BestieTemplate.jl/main/docs/src/assets/badge.json)](https://github.com/JuliaBesties/BestieTemplate.jl)

Protected files

The template's _skip_if_exists list decides whether an existing file is preserved or replaced; it is not a per-feature property. Of the files the features own, only AGENTS.md and CHANGELOG.md are on that list — so agents and changelog never touch an existing file, while dependabot, lint_action, pre_commit, formatter_linter_config and testitem_cli overwrite theirs. test/runtests.jl is an explicit exception carved out of the list's blanket protection for **/*.jl, which is why the test runner is replaceable at all.

Both outcomes print the same "Applied N feature(s)" line, so read the diff rather than the output. Two consequences to pass on to the user:

• A protected file never receives template improvements — not on add-feature, not on a later template update. Bringing an old AGENTS.md or CHANGELOG.md up to date is a manual diff against a freshly rendered copy.
• To adopt the template's version of a protected file, the user must move or delete their own first. Do that only on their explicit instruction.