Questions

In this page we list all the questions of the template, in the order that they are asked. Some of these questions are skipped because they are guessed.

To answer any of these question via the Julia interface, 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))
/home/runner/work/BestieTemplate.jl/BestieTemplate.jl/docs/.CondaPkg/env/lib/python3.11/site-packages/copier/vcs.py:183: ShallowCloneWarning: The repository '/home/runner/work/BestieTemplate.jl/BestieTemplate.jl' is a shallow clone, this might lead to unexpected failure or unusually high resource consumption.
  warn(
name = "NotMyPkg"
uuid = "09685a5d-b33c-5678-bf18-1613ec994774"
authors = ["Bestie"]
version = "0.1.0"

[compat]
julia = "1.10"
Help wanted

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.

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 the docs/make.jl file.

AuthorName

Question (in the CLI): (Deprecated in 0.10.0) Name of the package author (Used to kickstart a few files)

Description:

!!! warning Deprecated

AuthorName has been replaced by Authors.

Defines the name of the author.

AuthorEmail

Question (in the CLI): (Deprecated in 0.10.0) E-mail of the package author (Used to kickstart a few files)

Description:

!!! warning Deprecated

AuthorEmail has been replaced by Authors.

Defines the e-mail of the author.

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".

Indentation

Question (in the CLI): (Deprecated in 0.12.0) Indentation length (Used in .JuliaFormatter and other configuration files of formatters and linters if you add them)

Description:

The number of spaces that define an indentation level.

This is used in many configuration files:

  • .JuliaFormatter.toml: To control indentation in Julia;

  • .editorconfig: To suggest indentation in many languages;

  • .markdownlint.json: To control indentation in Markdown;

  • .pre-commit-config.yml: In the hook pretty-format-json to control the indentation of JSON files.

  • .yamllint.yml: To control indentation in YAML files;

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.

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

AnswerStrategy

Question (in the CLI): Strategy for optional questions (You can see the full list of questions in https://JuliaBesties.github.io/BestieTemplate.jl/dev/30-questions/)

Description:

This defines how to deal with the rest of the questions.

The "minimum" strategy answers "no" to every question. This is not the same as a bare-bones package. The resulting package will have the minimum amount of best practices that we recommend.

Both "recommended" strategies use all our recommended best practices. You then have the option to ignore or ask the optional questions. The optional questions include features that are being tested or that are too specific to be recommended.

The "recommended" strategy might be overwhelming for most people. See the answers below this step to see all the options. This is not the same as saying "yes" to everything.

The "ask" strategy does not select anything from the list below. All questions will be asked.

Notice that some options are only available through the "ask" or "recommended and ask" strategies, or by explicitly passing them to the Bestie command.

Defaults to the "recommended" strategy.

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.

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.

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 hook pretty-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.

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).

Defaults to yes for the recommended strategy, or no otherwise.

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 all test-*.jl files in the test folder inside @testsets.

This incentivizes separating the tests and makes sure that you don't forget to include them.

Defaults to yes for the recommended strategy, or no otherwise.

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.

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:

    • allexplicitimportsarepublic,

    • allqualifiedaccessesarepublic,

    • allexplicitimportsviaowners,

    • allqualifiedaccessesviaowners,

    • noimplicitimports,

    • noselfqualified_accesses,

    • nostaleexplicit_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.

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.

Defaults to no.

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.

Defaults to yes for the recommended strategy, or no otherwise.

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.

Defaults to yes for the recommended strategy, or no otherwise.

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.

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.

Defaults to no.

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.

Defaults to yes for the recommended strategy, or no otherwise.

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.

Defaults to yes for the recommended strategy, or no otherwise.

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 and README.dev.md with this information, or just paste everything in the README.md. We choose to have this information as part of the Julia docs, to focus information in a single source (documentation pages).

Defaults to yes for the recommended strategy, or no otherwise.

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).

Defaults to yes for the recommended strategy, or no otherwise.

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.

Defaults to yes for the recommended strategy, or no otherwise.

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.