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"

Table format

Questions ordered by strategy level

Questions ordered by section name

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

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

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

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