Questions
In this page we list all the questions of the template, in various formats. Some of these questions are skipped because they are guessed.
To answer any of these question directly via the Julia API, you can pass a dictionary to the generate
or apply
functions. For instance:
using BestieTemplate
data = Dict(
"PackageName" => "NotMyPkg",
"PackageOwner" => "bestie",
"Authors" => "Bestie",
)
BestieTemplate.generate(
"MyPkg",
data,
defaults=true, # Choose default for other questions - will fail if there is none
quiet=true,
)
print(read("MyPkg/Project.toml", String))
name = "NotMyPkg"
uuid = "dafd072f-ad57-5bec-afdf-fac858ad604d"
authors = ["Bestie"]
version = "0.1.0"
[compat]
julia = "1.10"
We have not managed to create a table of contents because we can't create the anchors in the headers. If you have an idea of what to do, help is appreciated.
Table format
We should have a single table and sortable columns. Probably done with external scripts, because injecting JS from here does not seem possible.
Questions ordered by strategy level
Question name | Section | Strategy | Default |
---|---|---|---|
Authors | essential | Tiny | |
JuliaMinVersion | essential | Tiny | LTS version (Currently 1.10) |
License | essential | Tiny | MIT |
LicenseCopyrightHolders | essential | Tiny | Authors |
PackageName | essential | Tiny | |
PackageOwner | essential | Tiny | |
PackageUUID | essential | Tiny | Random UUID |
AddCompatHelperCI | ci | Light | depends on strategy |
AddDocsCI | ci | Light | depends on strategy |
AddTagBotCI | ci | Light | depends on strategy |
AddTestCI | ci | Light | depends on strategy |
JuliaMinCIVersion | ci | Light | lts or JuliaMinVersion |
AddFormatterAndLinterConfigFiles | code-quality | Light | depends on strategy |
AddLychee | code-quality | Light | depends on strategy |
ConfigIndentation | code-quality | Light | 2 |
JuliaIndentation | code-quality | Light | 4 |
MarkdownIndentation | code-quality | Light | 2 |
AddDocs | community | Light | depends on strategy |
AddGitHubPRTemplate | community | Light | depends on strategy |
AddLintCI | ci | Moderate | depends on strategy |
AddDependabot | code-quality | Moderate | depends on strategy |
AddPrecommit | code-quality | Moderate | depends on strategy |
AutoIncludeTests | code-quality | Moderate | depends on strategy |
AddMacToCI | ci | Robust | depends on strategy |
AddWinToCI | ci | Robust | depends on strategy |
AddAllcontributors | community | Robust | depends on strategy |
AddCitationCFF | community | Robust | depends on strategy |
AddCodeOfConduct | community | Robust | depends on strategy |
AddContributionDocs | community | Robust | depends on strategy |
AddGitHubTemplates | community | Robust | depends on strategy |
CodeOfConductContact | community | Robust | Authors' e-mail |
AddCopierCI | ci | Advanced | depends on strategy |
RunJuliaNightlyOnCI | ci | Advanced | depends on strategy |
UseCirrusCI | ci | Advanced | depends on strategy |
CheckExplicitImports | code-quality | Advanced | depends on strategy |
ExplicitImportsChecklist | code-quality | Advanced | exclude_all_qualified_accesses_are_public |
StrategyConfirmIncluded | strategy | NA | false |
StrategyLevel | strategy | NA | 1 |
StrategyReviewExcluded | strategy | NA | false |
Questions ordered by section name
Question name | Section | Strategy | Default |
---|---|---|---|
AddCompatHelperCI | ci | Light | depends on strategy |
AddDocsCI | ci | Light | depends on strategy |
AddTagBotCI | ci | Light | depends on strategy |
AddTestCI | ci | Light | depends on strategy |
JuliaMinCIVersion | ci | Light | lts or JuliaMinVersion |
AddLintCI | ci | Moderate | depends on strategy |
AddMacToCI | ci | Robust | depends on strategy |
AddWinToCI | ci | Robust | depends on strategy |
AddCopierCI | ci | Advanced | depends on strategy |
RunJuliaNightlyOnCI | ci | Advanced | depends on strategy |
UseCirrusCI | ci | Advanced | depends on strategy |
AddFormatterAndLinterConfigFiles | code-quality | Light | depends on strategy |
AddLychee | code-quality | Light | depends on strategy |
ConfigIndentation | code-quality | Light | 2 |
JuliaIndentation | code-quality | Light | 4 |
MarkdownIndentation | code-quality | Light | 2 |
AddDependabot | code-quality | Moderate | depends on strategy |
AddPrecommit | code-quality | Moderate | depends on strategy |
AutoIncludeTests | code-quality | Moderate | depends on strategy |
CheckExplicitImports | code-quality | Advanced | depends on strategy |
ExplicitImportsChecklist | code-quality | Advanced | exclude_all_qualified_accesses_are_public |
AddDocs | community | Light | depends on strategy |
AddGitHubPRTemplate | community | Light | depends on strategy |
AddAllcontributors | community | Robust | depends on strategy |
AddCitationCFF | community | Robust | depends on strategy |
AddCodeOfConduct | community | Robust | depends on strategy |
AddContributionDocs | community | Robust | depends on strategy |
AddGitHubTemplates | community | Robust | depends on strategy |
CodeOfConductContact | community | Robust | Authors' e-mail |
Authors | essential | Tiny | |
JuliaMinVersion | essential | Tiny | LTS version (Currently 1.10) |
License | essential | Tiny | MIT |
LicenseCopyrightHolders | essential | Tiny | Authors |
PackageName | essential | Tiny | |
PackageOwner | essential | Tiny | |
PackageUUID | essential | Tiny | Random UUID |
StrategyConfirmIncluded | strategy | NA | false |
StrategyLevel | strategy | NA | 1 |
StrategyReviewExcluded | strategy | NA | false |
Ordered list
Section: Essential
PackageName
Question (in the CLI): Package name (without '.jl')
Description:
The package name. Must start with a capital letter, and be comprised of letters and numbers.
Required.
For new packages, it will be inferred from the path, the first argument of
generate
.For existing packages, it will be inferred from the Project.toml
name
field.
PackageUUID
Question (in the CLI): UUID (For existing packages, copy the UUID from Project.toml, otherwise use the one generated below)
Description:
The unique identifier of the package.
Required.
Defaults to randomly generated UUID.
For existing packages, it will be inferred from the Project.toml
uuid
field.
PackageOwner
Question (in the CLI): GitHub username or organization that owns the package (This will be used for URLs)
Description:
The owner of the package repo, i.e., the user or organization in the package URL.
This assumes that GitHub is being used, which, at the moment, is the only possibility.
Does not have a default.
For existing packages, it will be inferred from the
repo
information in thedocs/make.jl
file.
Authors
Question (in the CLI): Package authors separated by commas (We recommend the form NAME <EMAIL>, but this can be ignored)
Description:
The authors of the package in a single line, separated by commas. The actual content is not verified.
We recommend using the format
NAME <EMAIL>
for each author, so that it is consistent with most uses of author. However, that is not necessary.If you follow the recommended format, there are better defaults in other places.
Another common alternative is to list the main author and add
and contributors
. This is also completely valid.Can't be empty.
Required. No default.
For existing packages, it will be inferred from the
authors
information in the Project.toml.
LicenseCopyrightHolders
Question (in the CLI): License Copyright Holders (Added in front of "Copyright (c) " notices, when applicable)
Description:
Some license files include a "Copyright (c) <LicenseCopyrightHolders>" notice.
Defaults to names in the Authors question, if they follow the recommended format.
For instance, if the Authors field is "NAME1 <EMAIL1>,NAME2 <EMAIL2>", this will default to "NAME1, NAME2".
License
Question (in the CLI): Package license (You need an OSI license to register. You can suggest new licenses in the issues)
Description:
Multiple choice question to select a License.
Defaults to the MIT License, which is the most common choice for Julia packages.
JuliaMinVersion
Question (in the CLI): Minimum Julia version (Used in Project.toml. The suggestion below is the LTS version)
Description:
Minimum compat Julia version. This will be used in the Project.toml and as a suggestion for the minimum Julia version in the CI, which is another question.
Defaults to the LTS version.
For existing packages, it will be inferred from the compat section in the Project.toml files.
Section: Strategy
StrategyReviewExcluded
Question (in the CLI): Do you want review each excluded item?
StrategyLevel
Question (in the CLI): Which level of selection would you like? (How many default to yes)
StrategyConfirmIncluded
Question (in the CLI): You have select strategy '{{ StrategyLevelName }}'. Do you want to confirm each included item?
Section: Code Quality
JuliaIndentation
Question (in the CLI): Indentation length for Julia files (Used in .JuliaFormatter and .editorconfig)
Description:
The number of spaces that define an indentation level.
This is used in the following configuration files:
.JuliaFormatter.toml
: To control indentation in Julia;
.editorconfig
: To suggest indentation in many languages;This does NOT enforce indentation by itself, you still need tools to indent these.
pre-commit
is the recommended way to run these tools.For existing packages, this will be inferred from the indent value in the
.JuliaFormatter.toml
file.Strategy: Light
CheckExplicitImports
Question (in the CLI): Add ExplicitImports check to pre-commit (Check correct usage of using vs import and public API usage. See https://github.com/ericphanson/ExplicitImports.jl)
Description:
ExplicitImports performs a few checks to determine if this package is using other packages correctly.
See https://github.com/ericphanson/ExplicitImports.jl
Defaults to false, since many Julia packages have not adopted the idea yet.
Strategy: Advanced
AddFormatterAndLinterConfigFiles
Question (in the CLI): Configuration files for linters and formatters (Just adding the configuration files, no tools will be installed)
Description:
Whether to add the following configuration files:
.JuliaFormatter.toml
.editorconfig
.markdownlint.json
.yamlfmt.yml
.yamllint.yml
Some might be picked up automatically by your editor.
They are all used by the pre-commit tool, if you select AddPrecommit.
Strategy: Light
ConfigIndentation
Question (in the CLI): Indentation length for configuration files (Used to format YAML and JSON files)
Description:
The number of spaces that define an indentation level.
This is used in the following configuration files:
.pre-commit-config.yml
: In the hookpretty-format-json
to control the indentation of JSON files.
.yamllint.yml
: To control indentation in YAML files;
.editorconfig
: To suggest indentation in many languages;This does NOT enforce indentation by itself, you still need tools to indent these.
pre-commit
is the recommended way to run these tools.For existing packages, this will be inferred from the indent value in the
.JuliaFormatter.toml
file.Strategy: Light
AddDependabot
Question (in the CLI): Add Dependabot (Whether to add dependabot.yml, which runs periodically to update your GitHub actions versions)
Description:
Adds dependabot.yml (https://docs.github.com/en/code-security/dependabot),
which runs on GitHub repos periodically to make automated updates to your
GitHub actions.
Strategy: Moderate
AddLychee
Question (in the CLI): Add Lychee (Add .lychee.toml, configuration for the Lychee link checker)
Description:
Adds the configuration file for .lychee.toml, a link checker.
To run it, install lychee (https://github.com/lycheeverse/lychee) and run
lychee --config .lychee.toml .
It is also used by the Lint.yml action if AddLintCI is true.
Strategy: Light
AddPrecommit
Question (in the CLI): Pre-commit (Whether to add pre-commit.org. It runs before every commit fixing your formatting and preventing bad practices)
Description:
Pre-commit runs several "hooks" whenever you make a commit. These hooks mostly fall into these categories:
Formatters: Not only JuliaFormatter, but also formatters for Markdown, TOML, YAML, and JSON files.
Linters: Analyze the code to prevent "bad" things. Sometimes includes formatting rules, but frequently useful for what falls outside formatting, but leads to poor code performance or possible pitfalls. In Julia, JET would be a candidate for this, although we don't have any Julia linters in the pre-commit hooks (yet).
Quality of Life checks: Prevents commits if you have
.rej
files, if you are on the main branch, if you forget a git merge marker, etc.Many pre-commit hooks are also available as editor plugins, and could be run continually in your editor, although we don't have a list for that (yet).
Strategy: Moderate
AutoIncludeTests
Question (in the CLI): Auto-include test files named test-<name>.jl
(Incentivizes splitting your tests and better naming them, and helps avoiding forgetting to include the tests manually)
Description:
This write a
runtests.jl
file that automatically recursively includes alltest-*.jl
files in thetest
folder inside@testset
s.This incentivizes separating the tests and makes sure that you don't forget to include them.
Strategy: Moderate
MarkdownIndentation
Question (in the CLI): Indentation length for Markdown files (Used in .markdownlint.json and .editorconfig)
Description:
The number of spaces that define an indentation level.
This is used in the following configuration files:
.markdownlint.json
: To control indentation in Markdown;
.editorconfig
: To suggest indentation in many languages;This does NOT enforce indentation by itself, you still need tools to indent these.
pre-commit
is the recommended way to run these tools.For existing packages, this will be inferred from the indent value in the
.JuliaFormatter.toml
file.Strategy: Light
ExplicitImportsChecklist
Question (in the CLI): Checklist for ExplicitImports (Comma-separated list to be passed to ExplicitImports' –checklist. Defaults to a reasonable strictness. Use all
to run everything or see all options in https://github.com/ericphanson/ExplicitImports.jl?tab=readme-ov-file#command-line-usage)
Description:
ExplicitImports performs various checks. Some depend on the imported
packages fixing the definition of public API to Julia's latest definitions,
so using "all" is prone to failures until most Julia packages adopt the new
definition.
Valid values for each check are:
Individual checks:
all_explicit_imports_are_public
,
all_qualified_accesses_are_public
,
all_explicit_imports_via_owners
,
all_qualified_accesses_via_owners
,
no_implicit_imports
,
no_self_qualified_accesses
,
no_stale_explicit_imports
Select all checks: all
Exclude a check: prepend an individual check with 'exclude_'
The selection logic is performed in the order given.
If you pass only exclusions, it will assume that it starts from a complete list, and then excludes.
If you pass any individual checks, it will assume that it starts from an empty list, and then includes.
Passing both individual and exclusion checks does not make sense.
Strategy: Advanced
Section: Community
AddGitHubTemplates
Question (in the CLI): GitHub issue templates (Add forms for issue creation to improve the description quality)
Description:
Whether to add GitHub issue templates files. These files become forms when an user wants to create an issue on GitHub. They are useful for separating the kind of questions the user needs to fill and the automatic label added to the created issue.
Strategy: Robust
AddDocs
Question (in the CLI): Add docs (Add docs folder with initial files)
Description:
Whether to add a docs folder with the basics to write documentation using Documenter.jl.
Strategy: Light
AddCitationCFF
Question (in the CLI): Add CITATION.CFF file (Citation information for your file)
Description:
The Citation File Format (CFF) is a standard for describing how to cite
software and data, and is especially useful for scientific software.
It gets picked up by Zenodo to generate DOIs and by GitHub to generate a citation line.
Strategy: Robust
AddGitHubPRTemplate
Question (in the CLI): Add a GitHub Pull Request template (Pre-populate the pull requests to improve the description quality)
Description:
Whether to add a GitHub Pull Request template file. This file pre-populates
the pull request description with a template that incentivizes the
developer to describe the pull request better.
Strategy: Light
AddContributionDocs
Question (in the CLI): Add documentation files on how to contribute to the project (90-contributing.md will give general guidelines, and 91-developer.md will give practical information)
Description:
There are two files for contributors:
90-contributing.md
is aimed at anyone interested in contributing to the project. It provides general guidelines on how to communicate and where to find help.
91-developer.md
is aimed at code contributors. It provides more focused information for people that will need to clone the package to contribute to it, such as branching guidelines, pre-commit installation, building documentation, and making a new release.Some projects will add files like
CONTRIBUTING.md
andREADME.dev.md
with this information, or just paste everything in theREADME.md
. We choose to have this information as part of the Julia docs, to focus information in a single source (documentation pages).Strategy: Robust
AddAllcontributors
Question (in the CLI): Add allcontributors (allcontributors.org is a project that adds collaborators information in the README and the docs)
Description:
To make it easy to recognize contributions of every kind, we recommend using allcontributors.
The proposed workflow with allcontributors is to add a comment like "@allcontributors, please add @username for <type>" in a PR or issue. The bot will create a PR adding the information to the relevant places (README.md and docs/src/index.md).
Strategy: Robust
AddCodeOfConduct
Question (in the CLI): Code of conduct file (Add a CODEOFCONDUCT.md file from Contributor Covenant?)
Description:
This uses version 2.1 of the Contributor Covenant code of conduct.
Strategy: Robust
CodeOfConductContact
Question (in the CLI): Contact person/entity listed in the CODEOFCONDUCT.md file (Will be listed as contact to enforce the code of conduct, if necessary)
Description:
This is the contact person or entity for enforcement of the code of conduct. It will be added to the CODEOFCONDUCT file, in a section titled "Enforcement".
Defaults to the first authors' e-mail using a Regex substitution from the
Authors
question.Strategy: Robust
Section: Continuous Integration
UseCirrusCI
Question (in the CLI): FreeBSD CI test with CirrusCI (Add CirrusCI to run the package tests on FreeBSD?)
Description:
Controls whether to add a
.cirrus.yml
to run tests on the Cirrus CI platform for the FreeBSD Operating System.Strategy: Advanced
AddDocsCI
Question (in the CLI): Add docs workflow (Add docs workflow to automatically build the docs)
Description:
Whether to add the Docs.yml workflow that automatically builds and deploys
the docs to GitHub Pages.
Strategy: Light
AddMacToCI
Question (in the CLI): MacOS CI test (Package tests run on Ubuntu latest. Do you want to add macOS latest as well?)
Description:
Controls whether
macos-latest
is added to list of OSs being tested in the Test workflow.Strategy: Robust
RunJuliaNightlyOnCI
Question (in the CLI): Julia nightly CI test (Package tests run on Julia version {{ JuliaMinVersion }} and on the latest stable release. Do you also want to run them on the nightly version?)
Description:
Controls whether the nightly version of Julia is added to the list of Julia versions being tested in the Test workflow.
Strategy: Advanced
AddLintCI
Question (in the CLI): Lint.yml (Whether to add a Lint.yml workflow that runs a link checker and the pre-commit hooks, if enabled by AddPrecommit)
Description:
Whether to add a Lint.yml workflow that runs a link checker and the
pre-commit hooks, if enabled by AddPrecommit.
Strategy: Moderate
AddTagBotCI
Question (in the CLI): Add TagBot workflow (Add TagBot.yml to automatically create tags, releases and changelogs after registering a package)
Description:
Add TagBot.yml to automatically create tags, releases and changelogs after
registering a package.
Strategy: Light
AddCompatHelperCI
Question (in the CLI): Add CompatHelper workflow (Add CompatHelper.yml to automatically update the compat section of Project.toml)
Description:
Whether to add the CompatHelper.yml workflow that runs periodically to
automatically update the compat section of the Project.toml file.
Strategy: Light
JuliaMinCIVersion
Question (in the CLI): Minimum Julia version used in the tests (min, lts, or a version. See https://github.com/julia-actions/setup-julia#examples for accepted values)
Description:
The Test workflow runs two versions of Julia by default: the latest stable release, which is defined by "1", and this version.
It defaults to either "lts", or the version that you answered in JuliaMinVersion, if it wasn't the LTS.
Also accepts "min", which defaults to the minimum supported version in the compat section of Project.toml, or a version specification. See https://github.com/julia-actions/setup-julia#examples for more options.
Strategy: Light
AddTestCI
Question (in the CLI): Add tests workflows (Add tests workflow)
Description:
Whether to add the ReusableTest.yml, Test.yml and TestOnPRs.yml workflows
that automatically runs the tests in various platforms.
Strategy: Light
AddWinToCI
Question (in the CLI): Windows CI test (Same as above, but for Windows)
Description:
Controls whether
windows-latest
is added to list of OSs being tested in the Test workflow.Strategy: Robust
AddCopierCI
Question (in the CLI): Copier.yml (Add workflow to check for template updates? This is a work in progress workflow that checks whether there has been an update to the template and automatically create a pull request)
Description:
!!! warning Highly experimental
This feature is highly experimental and can be removed without a deprecation period.
Controls whether to add a workflow to check for updates in the template and create a PR applying them.
Strategy: Advanced