How we recommend staying up-to-date with Pants.
Reminder: change the
pants_versionoption in the
[GLOBAL]scope in your pants.toml to upgrade.
You can see all releases at https://pypi.org/project/pantsbuild.pants/#history.
Upgrade one minor release at a time
Per our Deprecation policy, deprecations must last a minimum of one minor release. For example, something may be deprecated in 2.1.0 and then removed in 2.2.0.
This means that it is helpful to upgrade one minor release at a time so that you can see all deprecation warnings.
You do not need to land every upgrade into your organization—often, you will want to upgrade your organization multiple versions at a time, e.g. 2.1.0 to 2.4.0. But, when you are working on the upgrade locally, it is helpful to iterate one version at a time.
First, see if Pants can automatically fix any safe deprecations for you:
# You may want to use `--no-fmt` if your BUILD files are # not already formatted by Black. ❯ ./pants update-build-files --no-fmt
You can add
update-build-files to your continuous integration so that developers don't accidentally use removed features:
❯ ./pants update-build-files --check
Then, see if there are any remaining deprecation warnings:
❯ ./pants ❯ ./pants list :: > /dev/null ❯ ./pants filedeps :: > /dev/null
It is also helpful to spot-check that your main commands like
test still work by running on a single target.
Use dev releases for the newest
As described in our Release strategy, we make weekly dev releases with all the latest features and bug fixes we've been working on. While dev releases are less stable, they mean you get access to improvements sooner.
If you encounter any blocking issues, you can easily roll back to a prior version by changing the
pants_versionoption. (Please let us know the issue by opening a GitHub issue or messaging us on Slack).
Ignore deprecation messages with
Sometimes when upgrading, you will not have time to fully fix the deprecation. The
ignore_warnings option allows you to silence those deprecations.
ignore_warnings option expects a string with the start of the deprecation warning. You can also prefix the string with
$regex$ to use a regex pattern instead of literal string matching.
[GLOBAL] ignore_warnings = [ "DEPRECATED: option 'config' in scope 'flake8' will be removed", "$regex$DEPRECATED:\\s*", ]
Check for updates to the
curl -L -o ./pants https://pantsbuild.github.io/setup/pants to check if there have been any changes, e.g. adding support for running Pants with new Python interpreters.
Find any bugs or issues?
Please either open a GitHub issue or head over to Slack. We'd be happy to help and would appreciate knowing about the issue!
Updated 7 months ago