diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index ebf8d1f0..edebe051 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.11.3","generation_timestamp":"2025-01-24T02:24:50","documenter_version":"1.8.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.11.3","generation_timestamp":"2025-01-25T02:20:44","documenter_version":"1.8.0"}} \ No newline at end of file diff --git a/dev/developer/index.html b/dev/developer/index.html index ca114488..550088c7 100644 --- a/dev/developer/index.html +++ b/dev/developer/index.html @@ -133,4 +133,4 @@ # Do some other work. add_test_dependency() end

There is also a default validate implementation for FilePlugins, which checks that the plugin's source file exists, and throws an ArgumentError otherwise. If you want to extend the validation but keep the file existence check, use the invoke method as described above.

For more examples, see the plugins in the Continuous Integration (CI) and Code Coverage sections.

Supporting Interactive Mode

When it comes to supporting interactive mode for your custom plugins, you have two options: write your own interactive method, or use the default one. If you choose the first option, then you are free to implement the method however you want. If you want to use the default implementation, then there are a few functions that you should be aware of, although in many cases you will not need to add any new methods.

PkgTemplates.interactive — Function
interactive(T::Type{<:Plugin}) -> T

Interactively create a plugin of type T. Implement this method and ignore other related functions only if you want completely custom behaviour.

source
PkgTemplates.prompt — Function
prompt(::Type{P}, ::Type{T}, ::Val{name::Symbol}) -> Any

Prompts for an input of type T for field name of plugin type P. Implement this method to customize particular fields of particular types.

source
PkgTemplates.customizable — Function
customizable(::Type{<:Plugin}) -> Vector{Pair{Symbol, DataType}}

Return a list of keyword arguments that the given plugin type accepts, which are not fields of the type, and should be customizable in interactive mode. For example, for a constructor Foo(; x::Bool), provide [x => Bool]. If T has fields which should not be customizable, use NotCustomizable as the type.

source
PkgTemplates.input_tips — Function
input_tips(::Type{T}) -> Vector{String}

Provide some extra tips to users on how to structure their input for the type T, for example if multiple delimited values are expected.

source
PkgTemplates.convert_input — Function
convert_input(::Type{P}, ::Type{T}, s::AbstractString) -> T

Convert the user input s into an instance of T for plugin of type P. A default implementation of T(s) exists.

source

Miscellaneous Tips

Writing Template Files

For an overview of writing template files for Mustache.jl, see Custom Template Files in the user guide.

Predicates

There are a few predicate functions for plugins that are occasionally used to answer questions like "does this Template have any code coverage plugins?". If you're implementing a plugin that fits into one of the following categories, it would be wise to implement the corresponding predicate function to return true for instances of your type.

PkgTemplates.needs_username — Function
needs_username(::Plugin) -> Bool

Determine whether or not a plugin needs a Git hosting service username to function correctly. If you are implementing a plugin that uses the user field of a Template, you should implement this function and return true.

source
PkgTemplates.is_ci — Function
is_ci(::Plugin) -> Bool

Determine whether or not a plugin is a CI plugin. If you are adding a CI plugin, you should implement this function and return true.

source
PkgTemplates.is_coverage — Function
is_coverage(::Plugin) -> Bool

Determine whether or not a plugin is a coverage plugin. If you are adding a coverage plugin, you should implement this function and return true.

source

Formatting Version Numbers

When writing configuration files for CI services, working with version numbers is often needed. There are a few convenience functions that can be used to make this a little bit easier.

PkgTemplates.compat_version — Function
compat_version(v::VersionNumber) -> String

Format a VersionNumber to exclude trailing zero components.

source
PkgTemplates.format_version — Function
format_version(v::Union{VersionNumber, AbstractString}) -> String

Strip everything but the major and minor release from a VersionNumber. Strings are left in their original form.

source
PkgTemplates.collect_versions — Function
collect_versions(t::Template, versions::Vector) -> Vector{String}

Combine t's Julia version with versions, and format them as major.minor. This is useful for creating lists of versions to be included in CI configurations.

source

Testing

If you write a cool new plugin that could be useful to other people, or find and fix a bug, you're encouraged to open a pull request with your changes. Here are some testing tips to ensure that your PR goes through as smoothly as possible.

Updating Reference Tests & Fixtures

If you've added or modified plugins, you should update the reference tests and the associated test fixtures. In test/reference.jl, you'll find a "Reference tests" test set that basically generates a bunch of packages, and then checks each file against a reference file, which is stored somewhere in test/fixtures. Note the reference tests only run on one specific version of Julia; check test/runtests.jl to see the current version used.

For new plugins, you should add an instance of your plugin to the "All plugins" and "Wacky options" test sets, then run the tests with Pkg.test. They should pass, and there will be new files in test/fixtures. Check them to make sure that they contain exactly what you would expect!

For changes to existing plugins, update the plugin options appropriately in the "Wacky options" test set. Failing tests will give you the option to review and accept changes to the fixtures, updating the files automatically for you.

Running reference tests locally

In the file test/runtests.jl, there is a variable called REFERENCE_JULIA_VERSION, currently set to v"1.7.2". If you use any other Julia version (even the latest stable one) to launch the test suite, the reference tests mentioned above will not run, and you will miss a crucial correctness check for your code. Therefore, we strongly suggest you test PkgTemplates locally against Julia 1.7.2. This version can be easily installed and started with juliaup:

juliaup add 1.7.2
-julia +1.7.2

Updating "Show" Tests

Depending on what you've changed, the tests in test/show.jl might fail. To fix those, you'll need to update the expected value to match what is actually displayed in a Julia REPL (assuming that the new value is correct).

+julia +1.7.2

Updating "Show" Tests

Depending on what you've changed, the tests in test/show.jl might fail. To fix those, you'll need to update the expected value to match what is actually displayed in a Julia REPL (assuming that the new value is correct).

diff --git a/dev/index.html b/dev/index.html index b0cc93ab..826398c3 100644 --- a/dev/index.html +++ b/dev/index.html @@ -10,4 +10,4 @@ Codecov(), Documenter{GitHubActions}(), ], -)

For a much more detailed overview, please see the User Guide documentation.

Contributing

Issues and pull requests are welcome! New contributors should make sure to read the ColPrac Contributor Guide. For some more PkgTemplates-specific tips, see the Developer Guide documentation.

source

Index

+)

For a much more detailed overview, please see the User Guide documentation.

Contributing

Issues and pull requests are welcome! New contributors should make sure to read the ColPrac Contributor Guide. For some more PkgTemplates-specific tips, see the Developer Guide documentation.

source

Index

diff --git a/dev/migrating/index.html b/dev/migrating/index.html index f20c2c7f..baa0c590 100644 --- a/dev/migrating/index.html +++ b/dev/migrating/index.html @@ -1,2 +1,2 @@ -Migrating To PkgTemplates 0.7+ · PkgTemplates.jl
GitHub

Migrating To PkgTemplates 0.7+

PkgTemplates 0.7 is a ground-up rewrite of the package with similar functionality but with updated APIs and internals. Here is a summary of things that existed in older versions but have been moved elsewhere or removed. However, it might be easier to just read the User Guide.

Template keywords

The recurring theme is "everything is a plugin now".

OldNew
license="ISC"plugins=[License(; name="ISC")]
develop=true *plugins=[Develop()]
git=falseplugins=[!Git]
julia_version=v"1"julia=v"1"
ssh=trueplugins=[Git(; ssh=true)]
manifest=trueplugins=[Git(; manifest=true)]

* develop=true was the default setting, but it is no longer the default in PkgTemplates 0.7+.

Plugins

Aside from renamings, basically every plugin has had their constructors reworked. So if you are using anything non-default, you should consult the new docstring.

OldNew
GitHubPagesDocumenter{TravisCI}
GitLabPagesDocumenter{GitLabCI}

Package Generation

One less name to remember!

OldNew
generate(::Template, pkg::AbstractString)(::Template)(pkg::AbstractString)

Interactive Mode

OldNew
interactive_template()Template(; interactive=true)
generate_interactive(pkg::AbstractString)Template(; interactive=true)(pkg)

Other Functions

Two less names to remember! Although it's unlikely that anyone used these.

OldNew
available_licensesView licenses on GitHub
show_licenseView licenses on GitHub

Custom Plugins

In addition to the changes in usage, custom plugins from older versions of PkgTemplates will not work in 0.7+. See the Developer Guide for more information on the new extension API.

+Migrating To PkgTemplates 0.7+ · PkgTemplates.jl
GitHub

Migrating To PkgTemplates 0.7+

PkgTemplates 0.7 is a ground-up rewrite of the package with similar functionality but with updated APIs and internals. Here is a summary of things that existed in older versions but have been moved elsewhere or removed. However, it might be easier to just read the User Guide.

Template keywords

The recurring theme is "everything is a plugin now".

OldNew
license="ISC"plugins=[License(; name="ISC")]
develop=true *plugins=[Develop()]
git=falseplugins=[!Git]
julia_version=v"1"julia=v"1"
ssh=trueplugins=[Git(; ssh=true)]
manifest=trueplugins=[Git(; manifest=true)]

* develop=true was the default setting, but it is no longer the default in PkgTemplates 0.7+.

Plugins

Aside from renamings, basically every plugin has had their constructors reworked. So if you are using anything non-default, you should consult the new docstring.

OldNew
GitHubPagesDocumenter{TravisCI}
GitLabPagesDocumenter{GitLabCI}

Package Generation

One less name to remember!

OldNew
generate(::Template, pkg::AbstractString)(::Template)(pkg::AbstractString)

Interactive Mode

OldNew
interactive_template()Template(; interactive=true)
generate_interactive(pkg::AbstractString)Template(; interactive=true)(pkg)

Other Functions

Two less names to remember! Although it's unlikely that anyone used these.

OldNew
available_licensesView licenses on GitHub
show_licenseView licenses on GitHub

Custom Plugins

In addition to the changes in usage, custom plugins from older versions of PkgTemplates will not work in 0.7+. See the Developer Guide for more information on the new extension API.

diff --git a/dev/user/index.html b/dev/user/index.html index 7083a79a..5990e6de 100644 --- a/dev/user/index.html +++ b/dev/user/index.html @@ -168,4 +168,4 @@ end

Then the template is just an include away:

const t = include("template.jl")

The only disadvantage to this approach is that the saved template is much less human-readable than code you wrote yourself.

One more method of saving templates is to simply use the Serialization package in the standard library:

const t = Template(; #= ... =#)
 using Serialization
 open(io -> serialize(io, t), "template.bin", "w")

Then simply deserialize to load:

using Serialization
-const t = open(deserialize, "template.bin")

This approach has the same disadvantage as the previous one, and the serialization format is not guaranteed to be stable across Julia versions.

+const t = open(deserialize, "template.bin")

This approach has the same disadvantage as the previous one, and the serialization format is not guaranteed to be stable across Julia versions.