diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 5059c5a..bb318c3 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.10.5","generation_timestamp":"2024-09-09T12:04:26","documenter_version":"1.7.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.10.5","generation_timestamp":"2024-09-10T08:38:05","documenter_version":"1.7.0"}} \ No newline at end of file diff --git a/dev/10-full-guide/index.html b/dev/10-full-guide/index.html index fac59dd..9a77b7e 100644 --- a/dev/10-full-guide/index.html +++ b/dev/10-full-guide/index.html @@ -20,4 +20,4 @@ git commit -m "Apply BestieTemplate vx.y.z"

Push your code to GitHub and head to Setting up your package for information on what to do next.

Now, go to Setting up your package to check what you still need to configure for your package.

Updating

To update the package, simply call

julia> BestieTemplate.update()

You will be asked the relevant questions of the package as if you had applied it. The big differences are:

Change previous answers

You can change your previous answers. In other words, if you though something was not mature enough in the past, but you are more confident in that now, you can adopt it now. This works even if the template was not updated itself.

As with the first application, you need to run pre-commit run -a to fix the unavoidable linting and formatting issues. Check the modifications in the relevant linter and formatting files, if you changed them manually, before doing it, though.

pre-commit run -a

The underlying package copier will use git to apply the differences and it will overwrite whatever files it finds in the way. Since git is mandatory, the changes will be left for you to review.

Review the changes

I repeat, the changes will be left for you to review. Don't just add them blindly, because some of your modifications can and will be overwritten.

If you need some help with undoing some of these changes, I recommend using a graphical interface.

Setting up your package

There are various steps to setting up your package on GitHub. Some are important now, and some will be relevant when you try to make your first release.

Add to GitHub

If you haven't yet, create a repo on GitHub and push your code to it.

Info

The actions will run and you will see errors in the documentation and linting. Do not despair.

Documentation

Go to your package setting on Github and find the "Actions" tab, the "General" link. On that page, find the "Workflow permissions" and change the selection to "Read and write permissions", and enable "Allow GitHub Actions can create and approve pull requests". This will allow the documentation workflow to work for development.

Go to the Actions page, click the failing Docs workflow and click on "re-run all jobs". It should pass now.

Now, go to your package setting on GitHub and find the "Pages" link. You should see an option to set the Source to "Deploy from a branch", and select the branch to be "gh-pages" and to deploy from the "/ (root)".

After circa 1 minute, you can check that the documentation was built properly.

Info

At this point, you should have passing workflows.

  1. Tests should have been passing from the start.
  2. Lint was fixed when we pushed the code to GitHub.
  3. Docs was fixed with the permissions change.

Documentation for releases

Info

This section is only relevant when making your first release, but it might be better to get it out of the way now.

You need to set a DOCUMENTER_KEY to build the documentation from the tags automatically when using TagBot (which we do by default). Do the following:

pkg> activate --temp
 pkg> add DocumenterTools
 julia> using DocumenterTools
-julia> DocumenterTools.genkeys(user="UserName", repo="PackageName.jl")

Follow the instruction in the terminal.

Enable Codecov for code coverage

If you don't have a Codecov account, go to https://codecov.io and create one now. After creating an account and logging in, you will see your main page with a list of your packages. Select the one that you are creating, it will open a configuration page.

On the configuration page, select "Using GitHub Actions" as your CI. The first step in the list given you the CODECOV_TOKEN. Click on the "repository secret" link on that page. It should lead you to the GitHub settings > secrets and variables > actions, under a "New secret" screen. Write CODECOV_TOKEN on the "Name" field and paste the token that you see on codecov on the "Secret" field. Click "Add secret".

Step 2 is not necessary because it is already present in the template.

The next time that the tests are run, the coverage page will be updated, and the badge will be fixed.

Add key for Copier.yml workflow

Copier.yml is work in progress

This option is not selected by default because it is a work in progress. If you want to use it, you have to pass the key "AddCopierCI" => true to the data argument of generate or apply, or select "Ask me" when deciding how to answer the optional questions.

You can reapply the template in the future. This is normally a manual job, specially because normally there are conflicts. That being said, we are experimenting with having a workflow that automatically checks whether there are updates to the template and reapplies it. A Pull Request is created with the result.

Warning

This is optional, and in development, so you might want to delete the workflow instead.

If you decide to use, here are the steps to set it up:

  1. Create a Personal Access Token to be used by the Copier workflow.
  2. Go to https://github.com/settings/tokens.
  3. Create a token with "Content", "Pull-request", and "Workflows" permissions.
  4. Copy the Token.
  5. Go to your YOUR_PACKAGE_URL/settings/secrets/actions.
  6. Create a "New repository secret" named COPIER_PAT.

CITATION.cff and Zenodo deposition

Update your CITATION.cff file with correct information. You can use cffinit to generate it easily.

Before releasing, enable Zenodo integration at https://zenodo.org/account/settings/github/ to automatically generate a deposition of your package, i.e., archive a version on Zenodo and generate a DOI.

Update README.md

  1. Update the badges
  2. Add a description

Enable discussions

Enable GitHub discussions.

First release

When you are ready to make your first release, enable the Julia Registrator bot. Make sure that you haven't skipped these sections:

+julia> DocumenterTools.genkeys(user="UserName", repo="PackageName.jl")

Follow the instruction in the terminal.

Enable Codecov for code coverage

If you don't have a Codecov account, go to https://codecov.io and create one now. After creating an account and logging in, you will see your main page with a list of your packages. Select the one that you are creating, it will open a configuration page.

On the configuration page, select "Using GitHub Actions" as your CI. The first step in the list given you the CODECOV_TOKEN. Click on the "repository secret" link on that page. It should lead you to the GitHub settings > secrets and variables > actions, under a "New secret" screen. Write CODECOV_TOKEN on the "Name" field and paste the token that you see on codecov on the "Secret" field. Click "Add secret".

Step 2 is not necessary because it is already present in the template.

The next time that the tests are run, the coverage page will be updated, and the badge will be fixed.

Add key for Copier.yml workflow

Copier.yml is work in progress

This option is not selected by default because it is a work in progress. If you want to use it, you have to pass the key "AddCopierCI" => true to the data argument of generate or apply, or select "Ask me" when deciding how to answer the optional questions.

You can reapply the template in the future. This is normally a manual job, specially because normally there are conflicts. That being said, we are experimenting with having a workflow that automatically checks whether there are updates to the template and reapplies it. A Pull Request is created with the result.

Warning

This is optional, and in development, so you might want to delete the workflow instead.

If you decide to use, here are the steps to set it up:

  1. Create a Personal Access Token to be used by the Copier workflow.
  2. Go to https://github.com/settings/tokens.
  3. Create a token with "Content", "Pull-request", and "Workflows" permissions.
  4. Copy the Token.
  5. Go to your YOUR_PACKAGE_URL/settings/secrets/actions.
  6. Create a "New repository secret" named COPIER_PAT.

CITATION.cff and Zenodo deposition

Update your CITATION.cff file with correct information. You can use cffinit to generate it easily.

Before releasing, enable Zenodo integration at https://zenodo.org/account/settings/github/ to automatically generate a deposition of your package, i.e., archive a version on Zenodo and generate a DOI.

Update README.md

  1. Update the badges
  2. Add a description

Enable discussions

Enable GitHub discussions.

First release

When you are ready to make your first release, enable the Julia Registrator bot. Make sure that you haven't skipped these sections:

diff --git a/dev/20-explanation/index.html b/dev/20-explanation/index.html index bba059d..1d54e29 100644 --- a/dev/20-explanation/index.html +++ b/dev/20-explanation/index.html @@ -1,2 +1,2 @@ -Explanation · BestieTemplate.jl

Explanation

In this section, we hope to explain the motivation for the package, and what is inside the template. Some things might have been obvious when creating the package and not at the moment, so feel free to create issues to ask, or suggest, clarifications.

You can see all questions in details in the Questions page.

Tip

If something is missing or not explained enough, please open an issue.

The engine, the project generator, and the template

Let me start by marking some names clearer.

  • The template is the collection of files and folders written with some placeholders. For instance, the link to a GitHub project will be something like https://github.com/{{ PackageOwner }}/{{ PackageName }}.jl.
  • The engine is the tool that converts the template into the end result, by changing the placeholders into the actual values that we want.
  • The project generator is the tool that interacts with the user to get the placeholder values and give to the engine.

Comparison with existing solutions

Julia has a very good package generator called PkgTemplates.jl, so why did we create another one?

The short answer is that we want a more streamlined development experience, a template more focused on best practices, and the ability to keep reusing the template whenever new tools and ideas are implemented.

In more details, first, see the differences in the parts of the project in the table below:

BestieTemplate.jlPkgTemplates.jl
TemplatePart of the packagePart of the package
EngineJinjaMustache
Project generatorcopier, with some wrappers in the packagePart of the package

Now, we can split this into three comparisons.

Template differences

The template differences are mostly due to opinion and contributions and it should be easy to translate files from one template to the other. We are heavily inspired by PkgTemplates.jl, as we used it for many years, but we made some changes in the hopes of improving software sustainability, package maintainability and code quality (which we just overtly simplify as best practices). As such, our current differences (as of the time of writing) are:

  • We have more best practices tools, such as pre-commit, configuration for linters and formatters for Julia, Markdown, TOML, YAML and JSON, CITATION.cff, Lint GitHub workflow, .editorconfig file, issues and pull requests templates, etc.
  • We focus on the main use cases (GitHub and GitHub actions), so we have much less options.

Engine differences

We can't say much about these, since we don't know or care in details.

Project generator differences

PkgTemplates.jl is a project generator. This means that if you want to programmatically create templates inside Julia, this is the best solution. The questions (user interface) are implemented by the package, which then translates that into the answers for the engine. Disclaimer: We haven't worked on the package, this information is based on the docs.

We use copier as project generator. It is an external Python tool, so we also include some wrappers in the package to use it from Julia without the need to explicitly install it. Copier has many features, so we recommend that you check their comparisons pages for more information.

Most notably, the feature that made us choose copier in the first place has the ability to applied and reapplied to existing projects. This means that existing packages can benefit from all best practices that we provide. Furthermore, they can keep reaping benefits when we create new versions of the template.

Template details

Let's dive into the details of the template now.

The template contains a few required questions and then asks you whether you would like to use

  • The "recommended" options, which include our current recommendation for best practices;
  • The "minimum" options, which answers "no" to everything, but still leaves you with a decent package to start; or
  • The option to answer every optional question individually.

The motivation behind "minimum" vs "recommended" is:

The "minimum" option includes all the Julia package basic plus a few things we think are of interest to all use cases of package development. Normal use cases for the "minimum" option are:

  • You are testing the template;
  • You are developing solo and wants to "move fast and break things";
  • Your package is in very early stage.
  • You are installing the "minimum" before installing the "recommended" to decrease the PR size.

Our loose criteria to make something part of the minimum is (exceptions may apply):

  • It is not too intrusive to development (e.g., .editorconfig);
  • It is a very common practice or tool (e.g., TagBot.yml and CompatHelper.yml);
  • It is a very strong recommendation that we think you should adopt (e.g., docs).

The "recommended" option includes all the minimum things plus things that we believe will improve quality and sustainability of packages. Normal use cases for the "recommended" option are:

  • You have a large package or a collection of packages;
  • You are not developing the package alone;
  • You expect open source contributions;
  • You agree with the best practices.

Our loose criteria to make something part of the recommended, but not minimum, is (exceptions may apply):

  • Despite being good, it requires change of behaviour (e.g., pre-commit);
  • It does not make sense for solo devs (e.g., all-contributors);
  • It creates friction - which is good to ensure quality but slows developement (e.g., issue templates).

Finally, there are other optional features. These are neither recommended nor part of the minimum template, which means that unless you (know and) set them explicitly, you are not using them.

The loose criteria to make something not recommended, nor minimum, is:

  • It is a best practice, but for a niche audience (e.g., .cirrus.yml for testing on FreeBSD);

To see all the questions, head to Questions.

Basic package structure

This is the basic structure of a package:

  • PackageName.jl/
    • src/
      • PackageName.jl
    • test/
      • Project.toml
      • runtests.jl
    • LICENSE.md
    • Project.toml
    • README.md

With the exception of test/Project.toml, all other files are requirements to register a package.

Documentation

On top of the basic structure, we add some Documenter.jl structure.

  • docs/
    • src/
      • 90-contributing.md
      • 91-developer.md
      • 95-reference.md
      • index.md
    • make.jl
    • Project.toml

Brief explanation of the details:

  • The Project.toml, make.jl and src/index.md are the basic structure.
  • docs/src/90-contributing.md: Sometimes added as CONTRIBUTING.md, it explains how contributors can get involved in the project.
  • docs/src/91-developer.md: Sometimes added as README.dev.md or DEVELOPER.md, it explains how to setup your local environment and other information relevant for developers only.
  • docs/src/95-reference.md is the API reference page, which include an @autodocs.

One noteworthy aspect of our make.jl, is that we include some code to automatically generate the list of pages. Create a file in the form ##-name.md, where ## is a two-digit number, and it will be automatically added to the pages list.

index.md

You might have noticed that index.md is not numbered, and that is because Documenter.jl checks for that files specifically to define the landing page. Instead, we explicitly add "Home" => "index." to make.jl.

Linting and Formatting

The most important file related to linting and formatting is .pre-commit-config.yaml, which is the configuration for pre-commit. It defines a list of linters and formatters for Julia, Markdown, TOML, YAML, and JSON.

It requires installing pre-commit (I recommend installing it globally with pipx). Installing pre-commit (pre-commit install) will make sure that it runs the relevant hooks before committing. Furthermore, if you run pre-commit run -a, it runs all hooks.

Some hooks in the .pre-commit-config.yaml file have configuration files of their own: .JuliaFormatter.toml, .markdownlint.json, .lychee.toml, and .yamllint.yml.

Also slightly related, is the .editorconfig file, which tells your editor, if you install the correct plugin, how to format some things.

GitHub Workflows

We have a few workflows, with plans to expand in the future:

  • CompatHelper.yml: Should be well known by now. It checks that your Project.toml compat entries are up-to-date.
  • Copier.yml: This will periodically check the template for updates. If there are updates, this action creates a pull request updating your repo.
  • Docs.yml: Build the docs. Only runs when relevant files change.
  • Lint.yml: Run the linter and formatter through the command pre-commit run -a.
  • TagBot.yml: Create GitHub releases automatically after your new release is merged on the Registry.
  • For testing, we have
    • ReusableTest.yml: Defines a reusable workflow with the testing.
    • Test.yml: Defines a matrix of tests to be run whenever main is updated or a tag is created. Uses the ReusableTest workflow. If "Simplified PR Test" was not chosen, then this also runs when there are pull requests.
    • TestOnPRs.yml: Defines a test to be run when pull requests are created. Only the latest stable Julia version is tested on a ubuntu-latest image. Uses the ReusableTest workflow. If "Simplified PR Test" was not chosen, then this file does not exist.

Issues and PR templates

We include issues and PR templates for GitHub (see .github/). These provide a starting point to your project management.

Other files

  • .cirrus.yml: For Cirrus CI, which we use solely for FreeBSD testing.
  • CITATION.cff: Instead of the more classic .bib, we use .cff, which serves a better purpose of providing the metadata of the package. CFF files have been adopted by GitHub, so you can generate a BibTeX entry by clicking on "Cite this repository" on the repository's main page. CFF files have also been adopted by Zenodo to provide the metadata of your deposition.
  • CODE_OF_CONDUCT.md: A code of conduct file from Contributor Covenant.
+Explanation · BestieTemplate.jl

Explanation

In this section, we hope to explain the motivation for the package, and what is inside the template. Some things might have been obvious when creating the package and not at the moment, so feel free to create issues to ask, or suggest, clarifications.

You can see all questions in details in the Questions page.

Tip

If something is missing or not explained enough, please open an issue.

The engine, the project generator, and the template

Let me start by marking some names clearer.

  • The template is the collection of files and folders written with some placeholders. For instance, the link to a GitHub project will be something like https://github.com/{{ PackageOwner }}/{{ PackageName }}.jl.
  • The engine is the tool that converts the template into the end result, by changing the placeholders into the actual values that we want.
  • The project generator is the tool that interacts with the user to get the placeholder values and give to the engine.

Comparison with existing solutions

Julia has a very good package generator called PkgTemplates.jl, so why did we create another one?

The short answer is that we want a more streamlined development experience, a template more focused on best practices, and the ability to keep reusing the template whenever new tools and ideas are implemented.

In more details, first, see the differences in the parts of the project in the table below:

BestieTemplate.jlPkgTemplates.jl
TemplatePart of the packagePart of the package
EngineJinjaMustache
Project generatorcopier, with some wrappers in the packagePart of the package

Now, we can split this into three comparisons.

Template differences

The template differences are mostly due to opinion and contributions and it should be easy to translate files from one template to the other. We are heavily inspired by PkgTemplates.jl, as we used it for many years, but we made some changes in the hopes of improving software sustainability, package maintainability and code quality (which we just overtly simplify as best practices). As such, our current differences (as of the time of writing) are:

  • We have more best practices tools, such as pre-commit, configuration for linters and formatters for Julia, Markdown, TOML, YAML and JSON, CITATION.cff, Lint GitHub workflow, .editorconfig file, issues and pull requests templates, etc.
  • We focus on the main use cases (GitHub and GitHub actions), so we have much less options.

Engine differences

We can't say much about these, since we don't know or care in details.

Project generator differences

PkgTemplates.jl is a project generator. This means that if you want to programmatically create templates inside Julia, this is the best solution. The questions (user interface) are implemented by the package, which then translates that into the answers for the engine. Disclaimer: We haven't worked on the package, this information is based on the docs.

We use copier as project generator. It is an external Python tool, so we also include some wrappers in the package to use it from Julia without the need to explicitly install it. Copier has many features, so we recommend that you check their comparisons pages for more information.

Most notably, the feature that made us choose copier in the first place has the ability to applied and reapplied to existing projects. This means that existing packages can benefit from all best practices that we provide. Furthermore, they can keep reaping benefits when we create new versions of the template.

Template details

Let's dive into the details of the template now.

The template contains a few required questions and then asks you whether you would like to use

  • The "recommended" options, which include our current recommendation for best practices;
  • The "minimum" options, which answers "no" to everything, but still leaves you with a decent package to start; or
  • The option to answer every optional question individually.

The motivation behind "minimum" vs "recommended" is:

The "minimum" option includes all the Julia package basic plus a few things we think are of interest to all use cases of package development. Normal use cases for the "minimum" option are:

  • You are testing the template;
  • You are developing solo and wants to "move fast and break things";
  • Your package is in very early stage.
  • You are installing the "minimum" before installing the "recommended" to decrease the PR size.

Our loose criteria to make something part of the minimum is (exceptions may apply):

  • It is not too intrusive to development (e.g., .editorconfig);
  • It is a very common practice or tool (e.g., TagBot.yml and CompatHelper.yml);
  • It is a very strong recommendation that we think you should adopt (e.g., docs).

The "recommended" option includes all the minimum things plus things that we believe will improve quality and sustainability of packages. Normal use cases for the "recommended" option are:

  • You have a large package or a collection of packages;
  • You are not developing the package alone;
  • You expect open source contributions;
  • You agree with the best practices.

Our loose criteria to make something part of the recommended, but not minimum, is (exceptions may apply):

  • Despite being good, it requires change of behaviour (e.g., pre-commit);
  • It does not make sense for solo devs (e.g., all-contributors);
  • It creates friction - which is good to ensure quality but slows developement (e.g., issue templates).

Finally, there are other optional features. These are neither recommended nor part of the minimum template, which means that unless you (know and) set them explicitly, you are not using them.

The loose criteria to make something not recommended, nor minimum, is:

  • It is a best practice, but for a niche audience (e.g., .cirrus.yml for testing on FreeBSD);

To see all the questions, head to Questions.

Basic package structure

This is the basic structure of a package:

  • PackageName.jl/
    • src/
      • PackageName.jl
    • test/
      • Project.toml
      • runtests.jl
    • LICENSE.md
    • Project.toml
    • README.md

With the exception of test/Project.toml, all other files are requirements to register a package.

Documentation

On top of the basic structure, we add some Documenter.jl structure.

  • docs/
    • src/
      • 90-contributing.md
      • 91-developer.md
      • 95-reference.md
      • index.md
    • make.jl
    • Project.toml

Brief explanation of the details:

  • The Project.toml, make.jl and src/index.md are the basic structure.
  • docs/src/90-contributing.md: Sometimes added as CONTRIBUTING.md, it explains how contributors can get involved in the project.
  • docs/src/91-developer.md: Sometimes added as README.dev.md or DEVELOPER.md, it explains how to setup your local environment and other information relevant for developers only.
  • docs/src/95-reference.md is the API reference page, which include an @autodocs.

One noteworthy aspect of our make.jl, is that we include some code to automatically generate the list of pages. Create a file in the form ##-name.md, where ## is a two-digit number, and it will be automatically added to the pages list.

index.md

You might have noticed that index.md is not numbered, and that is because Documenter.jl checks for that files specifically to define the landing page. Instead, we explicitly add "Home" => "index." to make.jl.

Linting and Formatting

The most important file related to linting and formatting is .pre-commit-config.yaml, which is the configuration for pre-commit. It defines a list of linters and formatters for Julia, Markdown, TOML, YAML, and JSON.

It requires installing pre-commit (I recommend installing it globally with pipx). Installing pre-commit (pre-commit install) will make sure that it runs the relevant hooks before committing. Furthermore, if you run pre-commit run -a, it runs all hooks.

Some hooks in the .pre-commit-config.yaml file have configuration files of their own: .JuliaFormatter.toml, .markdownlint.json, .lychee.toml, and .yamllint.yml.

Also slightly related, is the .editorconfig file, which tells your editor, if you install the correct plugin, how to format some things.

GitHub Workflows

We have a few workflows, with plans to expand in the future:

  • CompatHelper.yml: Should be well known by now. It checks that your Project.toml compat entries are up-to-date.
  • Copier.yml: This will periodically check the template for updates. If there are updates, this action creates a pull request updating your repo.
  • Docs.yml: Build the docs. Only runs when relevant files change.
  • Lint.yml: Run the linter and formatter through the command pre-commit run -a.
  • TagBot.yml: Create GitHub releases automatically after your new release is merged on the Registry.
  • For testing, we have
    • ReusableTest.yml: Defines a reusable workflow with the testing.
    • Test.yml: Defines a matrix of tests to be run whenever main is updated or a tag is created. Uses the ReusableTest workflow. If "Simplified PR Test" was not chosen, then this also runs when there are pull requests.
    • TestOnPRs.yml: Defines a test to be run when pull requests are created. Only the latest stable Julia version is tested on a ubuntu-latest image. Uses the ReusableTest workflow. If "Simplified PR Test" was not chosen, then this file does not exist.

Issues and PR templates

We include issues and PR templates for GitHub (see .github/). These provide a starting point to your project management.

Other files

  • .cirrus.yml: For Cirrus CI, which we use solely for FreeBSD testing.
  • CITATION.cff: Instead of the more classic .bib, we use .cff, which serves a better purpose of providing the metadata of the package. CFF files have been adopted by GitHub, so you can generate a BibTeX entry by clicking on "Cite this repository" on the repository's main page. CFF files have also been adopted by Zenodo to provide the metadata of your deposition.
  • CODE_OF_CONDUCT.md: A code of conduct file from Contributor Covenant.
diff --git a/dev/30-questions/index.html b/dev/30-questions/index.html index a3095f0..faca7c7 100644 --- a/dev/30-questions/index.html +++ b/dev/30-questions/index.html @@ -14,9 +14,9 @@ print(read("MyPkg/Project.toml", String))
/home/runner/work/BestieTemplate.jl/BestieTemplate.jl/docs/.CondaPkg/env/lib/python3.11/site-packages/copier/vcs.py:175: 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 = "fab2be41-7ab1-5098-ba24-9ba45398fc4a"
+uuid = "1a96552d-6007-5cc9-a9fb-18287311f392"
 authors = ["Bestie"]
 version = "0.1.0"
 
 [compat]
-julia = "1.6"
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): 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:

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://abelsiqueira.com/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.

The recommended strategy uses all our recommended best practices, which might be overwhelming for anyone. 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 strategy, or by explicitly passing them to the Bestie command.

Defaults to the "recommended" strategy.

Section: Code Quality

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:

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.

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 (lts defaults to the Long Term Support version)

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.

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:

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.

+julia = "1.6"
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): 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:

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://abelsiqueira.com/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.

The recommended strategy uses all our recommended best practices, which might be overwhelming for anyone. 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 strategy, or by explicitly passing them to the Bestie command.

Defaults to the "recommended" strategy.

Section: Code Quality

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:

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.

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:

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.

diff --git a/dev/90-contributing/index.html b/dev/90-contributing/index.html index f51f2d2..46f7402 100644 --- a/dev/90-contributing/index.html +++ b/dev/90-contributing/index.html @@ -1,2 +1,2 @@ -Contributing guidelines · BestieTemplate.jl

Contributing guidelines

First of all, thanks for the interest!

We welcome all kinds of contribution, including, but not limited to code, documentation, examples, configuration, issue creating, etc.

Be polite and respectful, and follow the code of conduct.

Bug reports and discussions

If you think you found a bug, feel free to open an issue. Focused suggestions and requests can also be opened as issues. Before opening a pull request, start an issue or a discussion on the topic, please.

Working on an issue

If you found an issue that interests you, comment on that issue what your plans are. If the solution to the issue is clear, you can immediately create a pull request (see below). Otherwise, say what your proposed solution is and wait for a discussion around it.

Tip

Feel free to ping us after a few days if there are no responses.

If your solution involves code (or something that requires running the package locally), check the developer documentation. Otherwise, you can use the GitHub interface directly to create your pull request.

Additions and modifications to the template

If you have any new idea or think the template needs to be updated or fixed, please search our issues and if there isn't anything relevant, open a new issue.

+Contributing guidelines · BestieTemplate.jl

Contributing guidelines

First of all, thanks for the interest!

We welcome all kinds of contribution, including, but not limited to code, documentation, examples, configuration, issue creating, etc.

Be polite and respectful, and follow the code of conduct.

Bug reports and discussions

If you think you found a bug, feel free to open an issue. Focused suggestions and requests can also be opened as issues. Before opening a pull request, start an issue or a discussion on the topic, please.

Working on an issue

If you found an issue that interests you, comment on that issue what your plans are. If the solution to the issue is clear, you can immediately create a pull request (see below). Otherwise, say what your proposed solution is and wait for a discussion around it.

Tip

Feel free to ping us after a few days if there are no responses.

If your solution involves code (or something that requires running the package locally), check the developer documentation. Otherwise, you can use the GitHub interface directly to create your pull request.

Additions and modifications to the template

If you have any new idea or think the template needs to be updated or fixed, please search our issues and if there isn't anything relevant, open a new issue.

diff --git a/dev/91-developer/index.html b/dev/91-developer/index.html index 4ef7d1a..9b65b19 100644 --- a/dev/91-developer/index.html +++ b/dev/91-developer/index.html @@ -25,4 +25,4 @@ - Alice {% if AddBob %}- Bob{% endif} - Carlos -- Diana

Dependent files and directories

To make a file depend on a variable, you can change the name of the file to include the conditional and the .jinja extension.

{% if AddSomeFile %}some-file.txt{% endif %}.jinja

If AddSomeFile, then some-file.txt will exist.

For directories, you do the same, except that you don't add the .jinja extension.

{% if AddGitHubTemplates %}ISSUE_TEMPLATE{% endif %}

Using answers

To use the answers of a question outside of a conditional, you can use {{ SomeValue }}. This will translate to the value of SomeValue as answered by the user. For instance

whoami() = "Hi, I'm package {{ PackageName }}.jl"

This also works on file names and in the copier.yml file.

Raw tag and avoiding clashes in GitHub workflow files

Since the GitHub workflow also uses { and } for their commands, we want to enclose them using the {% raw %}...{% endraw %} tag:

os: {% raw %}%{{ matrix.os }}{% endraw %}

Removing/replacing a question

Warn

This has only been tested with a single change

Before removing a question, we should deprecate it for one major release. We also want to ensure a smooth transition when the user updates.

Luckily, we do have one test that minimally simulates this situation: "Test updating from main to HEAD vs generate in HEAD" inside file test/test-bestie-specific-api.

This test will run generate using the local main branch (which won't contain the changes), and run the update command, with defaults=true, and then compare the result to running generate directly.

+- Diana

Dependent files and directories

To make a file depend on a variable, you can change the name of the file to include the conditional and the .jinja extension.

{% if AddSomeFile %}some-file.txt{% endif %}.jinja

If AddSomeFile, then some-file.txt will exist.

For directories, you do the same, except that you don't add the .jinja extension.

{% if AddGitHubTemplates %}ISSUE_TEMPLATE{% endif %}

Using answers

To use the answers of a question outside of a conditional, you can use {{ SomeValue }}. This will translate to the value of SomeValue as answered by the user. For instance

whoami() = "Hi, I'm package {{ PackageName }}.jl"

This also works on file names and in the copier.yml file.

Raw tag and avoiding clashes in GitHub workflow files

Since the GitHub workflow also uses { and } for their commands, we want to enclose them using the {% raw %}...{% endraw %} tag:

os: {% raw %}%{{ matrix.os }}{% endraw %}

Removing/replacing a question

Warn

This has only been tested with a single change

Before removing a question, we should deprecate it for one major release. We also want to ensure a smooth transition when the user updates.

Luckily, we do have one test that minimally simulates this situation: "Test updating from main to HEAD vs generate in HEAD" inside file test/test-bestie-specific-api.

This test will run generate using the local main branch (which won't contain the changes), and run the update command, with defaults=true, and then compare the result to running generate directly.

diff --git a/dev/95-reference/index.html b/dev/95-reference/index.html index faaf105..51fe064 100644 --- a/dev/95-reference/index.html +++ b/dev/95-reference/index.html @@ -1,6 +1,6 @@ -Reference · BestieTemplate.jl

Reference

Contents

Index

Auto docs

BestieTemplate.BestieTemplate — Module

BestieTemplate.jl

This package defines a copier template for Julia packages and a basic user interface around copier to use it from Julia.

The main functions are: generate, apply, and update.

To create a new package using BestieTemplate run

julia> BestieTemplate.generate("path/to/YourNewPackage.jl")

To apply the template to an existing package

julia> BestieTemplate.apply("path/to/YourExistingPackage.jl")

Check the documentation: https://abelsiqueira.com/BestieTemplate.jl

source
BestieTemplate._copy — Method
_copy(src_path, dst_path, data; kwargs...)

Internal function to run common code for new or existing packages.

source
BestieTemplate._sanitize_package_name — Method
package_name = _sanitize_package_name(path)

Sanitize the path to guess the package_name by looking at the base name and removing an extension. If the result is not a valid identifier, returns "".

source
BestieTemplate.apply — Function
apply(dst_path[, data]; kwargs...)
-apply(src_path, dst_path[, data]; true, kwargs...)

Applies the template to an existing project at path $dst_path$. If the dst_path does not exist, this will throw an error. For new packages, use BestieTemplate.generate instead.

Runs the copy command of copier with the BestieTemplate template. If src_path is not informed, the GitHub URL of BestieTemplate.jl is used.

The data argument is a dictionary of answers (values) to questions (keys) that can be used to bypass some of the interactive questions.

Keyword arguments

  • guess:Bool = true: Whether to try to guess some of the data from the package itself.
  • warn_existing_pkg::Bool = true: Whether to check if you actually meant update. If you run apply and the dst_path contains a .copier-answers.yml, it means that the copy was already made, so you might have means update instead. When true, a warning is shown and execution is stopped.
  • quiet::Bool = false: Whether to print greetings, info, and other messages. This keyword is also used by copier.

The other keyword arguments are passed directly to the internal Copier.copy.

source
BestieTemplate.generate — Function
generate(dst_path[, data]; kwargs...)
-generate(src_path, dst_path[, data]; true, kwargs...)

Generates a new project at the path dst_path using the template. If the dst_path already exists, this will throw an error, unless dst_path = ".". For existing packages, use BestieTemplate.apply instead.

Runs the copy command of copier with the BestieTemplate template. If src_path is not informed, the GitHub URL of BestieTemplate.jl is used.

The data argument is a dictionary of answers (values) to questions (keys) that can be used to bypass some of the interactive questions.

Keyword arguments

  • warn_existing_pkg::Boolean = true: Whether to check if you actually meant update. If you run generate and the dst_path contains a .copier-answers.yml, it means that the copy was already made, so you might have means update instead. When true, a warning is shown and execution is stopped.
  • quiet::Boolean = false: Whether to print greetings, info, and other messages. This keyword is also used by copier.

The other keyword arguments are passed directly to the internal Copier.copy.

source
BestieTemplate.update — Function
update([data]; kwargs...)
-update(dst_path[, data]; kwargs...)

Run the update command of copier, updating the dst_path (or the current path if omitted) with a new version of the template with a new version of the template.

The data argument is a dictionary of answers (values) to questions (keys) that can be used to bypass some of the interactive questions.

Keyword arguments

The keyword arguments are passed directly to the internal Copier.update.

source
BestieTemplate.Copier.copy — Function
copy(dst_path[, data]; kwargs...)
-copy(src_path, dst_path[, data]; kwargs...)

Wrapper around copier.run_copy.

This is an internal function, if BestieTemplate's main API is not sufficient, open an issue. Note: this is not Base.copy, inside the Copier module we shadow that name.

source

Debug auto docs

BestieTemplate.Debug — Module

Module Debug

Tools for debugging Bestie. Nothing here is public API.

Warning

This file is not tested and not covered in codecov. Except for the data, it is not supposed to be used in the tests.

Noteworthy: BestieTemplate.Debug.Data

source
BestieTemplate.Debug.dbg_apply — Function
dbg_apply([dst_path, data]; data_choice=:minimum)

Convenience function to help debug apply. It runs apply with the dst_path destination and the given data (nothing by default).

It also uses a data_choice to determine fake starting data. This is passed to dbg_data.

It uses the pkgdir location of Bestie and adds the flags

  • defaults = true: Sent to copier to use the default answers.
  • quiet = true: Low verbosity.
  • overwrite = true: Overwrite all files.
  • vcs_ref = HEAD: Use the development version of the template, including dirty repo changes.
source
BestieTemplate.Debug.dbg_data — Function
dbg_data(data_choice, more_data)

Returns the fake debug data merged with more_data. The options for data_choice are:

  • :nothing, :none: No random data.
  • :required, :req: Only the required data is generated. You get asked which choice of optional data.
  • :minimum, :min: The required data plus the choice "minimum" for optional data.
  • :recommended, :rec: The required data plus the choice "recommended" for optional data.
  • :ask: The required data plus the choice "ask". The optional questions will be asked.
  • :ask_default: Same as :ask plus the default answers for the optional questions.
  • :ask_and_say_no: Same as :ask plus answers no/false to the optional questions.
  • :ask_and_say_yes: Same as :ask plus answers yes/true to the optional questions.
source
BestieTemplate.Debug.dbg_generate — Function
dbg_generate([dst_path, data]; data_choice=:minimum)

Convenience function to help debug generate. It runs generate with the dst_path destination (random by default) and the given data (nothing by default).

It also uses a data_choice to determine fake starting data. This is passed to dbg_data.

It uses the pkgdir location of Bestie and adds the flags

  • defaults = true: Sent to copier to use the default answers.
  • quiet = true: Low verbosity.
  • vcs_ref = HEAD: Use the development version of the template, including dirty repo changes.
source
BestieTemplate.Debug.Data — Module

Fake data for testing

  • Debug.Data: NamedTuple of Dictionaries with default data
    • Debug.Data.required: Required data if you use defaults = true
    • Debug.Data.strategy_minimum: Required data for strategy minimum, no defaults.
    • Debug.Data.strategy_recommended: Required data for strategy recommended, no defaults.
    • Debug.Data.strategy_ask: Required data for strategy ask, no defaults.
source
+Reference · BestieTemplate.jl

Reference

Contents

Index

Auto docs

BestieTemplate.BestieTemplate — Module

BestieTemplate.jl

This package defines a copier template for Julia packages and a basic user interface around copier to use it from Julia.

The main functions are: generate, apply, and update.

To create a new package using BestieTemplate run

julia> BestieTemplate.generate("path/to/YourNewPackage.jl")

To apply the template to an existing package

julia> BestieTemplate.apply("path/to/YourExistingPackage.jl")

Check the documentation: https://abelsiqueira.com/BestieTemplate.jl

source
BestieTemplate._copy — Method
_copy(src_path, dst_path, data; kwargs...)

Internal function to run common code for new or existing packages.

source
BestieTemplate._sanitize_package_name — Method
package_name = _sanitize_package_name(path)

Sanitize the path to guess the package_name by looking at the base name and removing an extension. If the result is not a valid identifier, returns "".

source
BestieTemplate.apply — Function
apply(dst_path[, data]; kwargs...)
+apply(src_path, dst_path[, data]; true, kwargs...)

Applies the template to an existing project at path $dst_path$. If the dst_path does not exist, this will throw an error. For new packages, use BestieTemplate.generate instead.

Runs the copy command of copier with the BestieTemplate template. If src_path is not informed, the GitHub URL of BestieTemplate.jl is used.

The data argument is a dictionary of answers (values) to questions (keys) that can be used to bypass some of the interactive questions.

Keyword arguments

  • guess:Bool = true: Whether to try to guess some of the data from the package itself.
  • warn_existing_pkg::Bool = true: Whether to check if you actually meant update. If you run apply and the dst_path contains a .copier-answers.yml, it means that the copy was already made, so you might have means update instead. When true, a warning is shown and execution is stopped.
  • quiet::Bool = false: Whether to print greetings, info, and other messages. This keyword is also used by copier.

The other keyword arguments are passed directly to the internal Copier.copy.

source
BestieTemplate.generate — Function
generate(dst_path[, data]; kwargs...)
+generate(src_path, dst_path[, data]; true, kwargs...)

Generates a new project at the path dst_path using the template. If the dst_path already exists, this will throw an error, unless dst_path = ".". For existing packages, use BestieTemplate.apply instead.

Runs the copy command of copier with the BestieTemplate template. If src_path is not informed, the GitHub URL of BestieTemplate.jl is used.

The data argument is a dictionary of answers (values) to questions (keys) that can be used to bypass some of the interactive questions.

Keyword arguments

  • warn_existing_pkg::Boolean = true: Whether to check if you actually meant update. If you run generate and the dst_path contains a .copier-answers.yml, it means that the copy was already made, so you might have means update instead. When true, a warning is shown and execution is stopped.
  • quiet::Boolean = false: Whether to print greetings, info, and other messages. This keyword is also used by copier.

The other keyword arguments are passed directly to the internal Copier.copy.

source
BestieTemplate.update — Function
update([data]; kwargs...)
+update(dst_path[, data]; kwargs...)

Run the update command of copier, updating the dst_path (or the current path if omitted) with a new version of the template with a new version of the template.

The data argument is a dictionary of answers (values) to questions (keys) that can be used to bypass some of the interactive questions.

Keyword arguments

The keyword arguments are passed directly to the internal Copier.update.

source
BestieTemplate.Copier.copy — Function
copy(dst_path[, data]; kwargs...)
+copy(src_path, dst_path[, data]; kwargs...)

Wrapper around copier.run_copy.

This is an internal function, if BestieTemplate's main API is not sufficient, open an issue. Note: this is not Base.copy, inside the Copier module we shadow that name.

source

Debug auto docs

BestieTemplate.Debug — Module

Module Debug

Tools for debugging Bestie. Nothing here is public API.

Warning

This file is not tested and not covered in codecov. Except for the data, it is not supposed to be used in the tests.

Noteworthy: BestieTemplate.Debug.Data

source
BestieTemplate.Debug.dbg_apply — Function
dbg_apply([dst_path, data]; data_choice=:minimum)

Convenience function to help debug apply. It runs apply with the dst_path destination and the given data (nothing by default).

It also uses a data_choice to determine fake starting data. This is passed to dbg_data.

It uses the pkgdir location of Bestie and adds the flags

  • defaults = true: Sent to copier to use the default answers.
  • quiet = true: Low verbosity.
  • overwrite = true: Overwrite all files.
  • vcs_ref = HEAD: Use the development version of the template, including dirty repo changes.
source
BestieTemplate.Debug.dbg_data — Function
dbg_data(data_choice, more_data)

Returns the fake debug data merged with more_data. The options for data_choice are:

  • :nothing, :none: No random data.
  • :required, :req: Only the required data is generated. You get asked which choice of optional data.
  • :minimum, :min: The required data plus the choice "minimum" for optional data.
  • :recommended, :rec: The required data plus the choice "recommended" for optional data.
  • :ask: The required data plus the choice "ask". The optional questions will be asked.
  • :ask_default: Same as :ask plus the default answers for the optional questions.
  • :ask_and_say_no: Same as :ask plus answers no/false to the optional questions.
  • :ask_and_say_yes: Same as :ask plus answers yes/true to the optional questions.
source
BestieTemplate.Debug.dbg_generate — Function
dbg_generate([dst_path, data]; data_choice=:minimum)

Convenience function to help debug generate. It runs generate with the dst_path destination (random by default) and the given data (nothing by default).

It also uses a data_choice to determine fake starting data. This is passed to dbg_data.

It uses the pkgdir location of Bestie and adds the flags

  • defaults = true: Sent to copier to use the default answers.
  • quiet = true: Low verbosity.
  • vcs_ref = HEAD: Use the development version of the template, including dirty repo changes.
source
BestieTemplate.Debug.Data — Module

Fake data for testing

  • Debug.Data: NamedTuple of Dictionaries with default data
    • Debug.Data.required: Required data if you use defaults = true
    • Debug.Data.strategy_minimum: Required data for strategy minimum, no defaults.
    • Debug.Data.strategy_recommended: Required data for strategy recommended, no defaults.
    • Debug.Data.strategy_ask: Required data for strategy ask, no defaults.
source
diff --git a/dev/index.html b/dev/index.html index 5cb65b3..af2fdfa 100644 --- a/dev/index.html +++ b/dev/index.html @@ -37,4 +37,4 @@ - + diff --git a/dev/objects.inv b/dev/objects.inv index 74977d7..a36a832 100644 Binary files a/dev/objects.inv and b/dev/objects.inv differ