Workflow to create and update [compat] section of Project.toml

General Usage
1

What is the preferred workflow to create the [compat] section for a new package, and then maintain it up to date?

Creating

Can you tell if the following algorithm for creation of [compat] section is reasonable:

  • Create package and test that it works.
  • Write up the version of Julia and the versions of the packages currently installed.
  • Go over the list of versions.
    If the version is “0.x.y”, add to [compat] the range [0.x.y - 0.x+1.0).
    If the version is “x.y.z>=1”, add to [compat] the range [x.y.0 - x+1.0.0).

The logic here is the following
As far as I understand semver (which I, in all honesty, do not), minor version bump (patch version bump in the case “<1”) indicates the adding of new backward-compatible functionality. Since it may be hard to tell when the functionality that your package uses was added, the range goes from current minor version (or patch version for “<1”) till next breaking change.

Maintaining

I can imagine the following algorithm for maintaining.

  • If you update dependencies and everything works, add new version to [compat].
  • If you update dependecies and something breaks, fix it, drop all previous versions (for dependencies that caused breakage) in [compat], add new version.
  • If you update your package and you know that you use some knew functionality from dependency, do the same as in the previous case (drop previous versions, add new one).

Do you think this algorithm is reasonable enough?

What algorithms do you use yourselves?

2

I tend to use the same algorithm as you are when creating compat bounds. I sometimes perform an extra step by checking whether things work for older Julia versions: if I can support Julia 1.0 without any extra hassle, I think it might be worth it (I usually don’t bother doing this for every dependency, tough).

But I’m actually not sure that this is an optimal way of doing things; let’s wait to see what interesting workflows are proposed in other answers.

As for keeping compat bounds up to date, you might want to take a look at CompatHelper.jl, which is a tool specifically designed to help with this. Quoting the project README:

Whenever one of your package’s dependencies releases a new version, CompatHelper opens a pull request on your repository that modifies your [compat] entry to reflect the newly released version.

It is then super easy to look at the CI output for the PR and decide whether you actually want to bump the compat bounds or not.

3

This package may come in handy: GitHub - GunnarFarneback/PackageCompatUI.jl: Terminal UI for [compat] section of Julia Project.toml files.
However, it depends on Julia 1.6 features so you need to have a Julia from the 1.6 branch or master, e.g. a nightly build, to run it. For now you also need to add it by URL. It will be registered once 1.6 is out.

1 Like
4

Could you please elaborate what this package does besides providing a cli to edit [compat] section?
For example, does compat_ui() automatically detects ranges of versions for dependencies and puts it into Project.toml?

5

Well, that is pretty much exactly what it does.

You mark what versions you want your package to be compatible with and it computes what should go into the [compat] section and updates Project.toml when you exit.

1 Like
6

That is indeed helpful. Actually, I had in mind that CompatHelper is used to track the updates to dependencies. However, the cases where something breaks or you start using new functionality still require some manual tinckering with the versions.