isabella232 / pkgdev.jl

Tools for Julia package developers

PkgDev

Overview

PkgDev provides tools for Julia package developers. The package is currently being rewritten for Julia 1.x and only for brave early adopters.

Usage

PkgDev.tag(package_name, version=nothing; registry=nothing, release_notes=nothing)

Tag a new release for package package_name. The package you want to tag must be deved in the current Julia environment. You pass the package name package_name as a String. The git commit that is the HEAD in the package folder will form the basis for the version to be tagged.

If you don't specify a version, then the version field in the Project.toml must have the format x.y.z-DEV, and the command will tag version x.y.z as the next release. Alternatively you can specify one of :major, :minor or :patch for the version parameter. In that case PkgDev.tag will increase that part of the version number by 1 and tag that version. Finally, you can also specify a full VersionNumber as the value for the version parameter, in which case that version will be tagged.

The only situation where you would specify a value for registry is when you want to register a new package for the first time in a registry that is not General. In all other situations, PkgDev.tag will automatically figure out in which registry your package is registered. When you do pass a value for registry, it should simply be the short name of a registry that is one of the registries your local system is connected with.

If you want to add custom release notes for TagBot, do so with the release_notes keyword.

PkgDev.tag runs through the following process when it tags a new version:

1. Create a new release branch called release-x.y.z.
2. Change the version field in Project.toml and commit that change on the release branch.
3. Change the version field in Project.toml to x.y.z+1-DEV and commit that change also to the release branch. 4a. For packages in the General registry: add a comment that triggers Registrator. 4b. For packages in other registries: Open a pull request against the registry that tags the first new commit on the release branch as a new version x.y.z.
4. Open a pull request against the package repository to merge the release branch into master.

If you have TagBot installed for your package with the branches: true setting, it will automatically merge the release-x.y.z branch into master once the pull request for the registry has been merged. If you use the package butler (desribed below) it auto-configures your repository for this workflow.

PkgDev.enable_pkgbutler(package_name; channel=:auto, template=:auto)

Enables the Julia Package Butler for package package_name. The package must be deved in the current Julia environment. The command will make various modifications to the files in the deved folder of the package. You then then need to commit these changes and push them to GitHub. The command will also add a deploy key to the GitHub repository of the package and show instructions on how to add two GitHub Actions secrets to the repository.

The channel argument can be :auto, :stable or :dev. There are two channels of updates: stable and dev. The dev channel will run the Julia Package Butler workflow every 5 minutes and it will use the master branch of the Julia Packge Butler engine, i.e. it will get new features more quickly. The stable branch runs the Julia Package Butler workflow every hour, and new features in the Julia Package Butler engine are only pushed out to the stable channel once they have been tested for a while on the dev channel. If you specify :auto as the argument, any existing channel choice you have previously made for the package will be retained, otherwise the package will be configure for the stable channel.

The template argument can be :auto, :default or :bach. Different templates will configure different aspects of your package. At this point everyone should use the :default template (or :auto template), everything else is considered experimental.

PkgDev.switch_pkgbutler_channel(package_name, channel)

Switch the Julia Package Butler channel for package package_name. The package you want to tag must be deved in the current Julia environment and the Julia Package Butler must already be enabled for the package. The channel argument can be :auto, :stable or :dev, see the documentation for PkgDev.enable_pkgbutler for an explanation of the different channels.

PkgDev.switch_pkgbutler_template(package_name, template)

Switch the Julia Package Butler template for package package_name. The package you want to tag must be deved in the current Julia environment and the Julia Package Butler must already be enabled for the package. The template argument can be :auto, :default or :bach.

PkgDev.format(package_name)

Format all the Julia source code files for the package with name package_name. The package you want to format must be deved in the current Julia environment. This function uses DocumentFormat.jl.