HEP 2: Release and deprecation policies #388
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,62 @@ | ||
| # HEP 2: Release and deprecation policies | ||
|
|
||
| This HEP describes the release and deprecation policies adopted by the HoloViz Projects. The overall goal of this HEP is to ensure that these policies are consistently applied across the Projects, which will help provide a consistent user experience and help contributors and maintainers make decisions (in particular when dealing with a project they are not very familiar with). The HEP formalizes as a set of practices adopted over time and also introduces a few more rules (e.g. minimum deprecation period). | ||
|
|
||
| ## Versioning | ||
|
|
||
| The Projects deliver final releases with a version number of the form `<major>.<minor>.<patch>` (e.g. `1.2.3`): | ||
|
|
||
| - `patch` releases (e.g. 0.1.**0** -> 0.1.**1**) should never intentionally and rarely, if ever, unintentionally break API. Should be safe to upgrade to the latest patch release if you encounter any problems. | ||
| - `minor` releases (e.g. 0.**1**.1 -> `0.**2**.0) should not have API changes that affect most users. API changes in minor releases should be rare, but are not unheard of, particularly for recently added functionality whose API is still being refined, or for bugs found in older code that can't be fixed without changing API at least slightly. | ||
| - `major` releases (e.g. **0**.2.0 -> **1**.0.0) will typically break APIs, but should normally include significant new functionality to motivate users to update their code. Major breaking API changes should be postponed to a major release and paired with significant user-visible advantages. | ||
|
|
||
| While this versioning scheme is inspired by [Semantic Versioning](https://semver.org/) (*SemVer*), like many other Python projects, **the HoloViz Projects do not strictly follow it** as incompatible (aka breaking) API changes are not limited to `major` releases. | ||
|
|
||
| The Projects can deliver three types of pre-releases / development versions: | ||
maximlt marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| - `alpha` (e.g. `1.2.3a1`): Projects can deliver alpha releases for users to benefit from and/or test bug fixes and new features, early in the development phase of a new version. alpha releases are common across the Projects. | ||
| - `beta` (e.g. `1.2.3b1`): Projects can deliver beta releases for the same reasons, except they indicate the project is in a more advanced development phase of a new version. beta releases are not common across the Projects, they're more likely to be useful when a major release is in development, to progressively deliver large new features and API breaking changes. | ||
| - `release candidate` (e.g. `1.2.3rc1`): Projects must deliver a release candidate version before the final release. | ||
|
There was a problem hiding this comment. This could also explicitly say that no new features can be added after the first RC, and only regressions and bugs should be handled. Must is also a strong word. I would say another of the dev releases is also good enough for a patch release. An expectation of a release candidate for some is that it has a time period where people have a chance to test it. What I see in our cases is that we make a release candidate to test if our CI runs correctly (with downstream test), and when it is finished, we make the official release. There was a problem hiding this comment.
Yes, I didn't think about that this is interesting.
I'm suggesting replacing the alpha releases (often just one) made before a patch release with release candidates.
Yes, that's true. The HEP could explain that release candidates are always announced sometime before the final release.
Not always, we have applications that test release candidates before the final release. It's not the most common case though, even if it's difficult to say whether other users rely on dev releases in their internal code bases. |
||
|
|
||
| ## Supported versions | ||
|
|
||
| Exception in certain exceptional cases, the Projects do not backport changes to previous major or minor releases. | ||
|
|
||
| ## Release process | ||
|
|
||
| Releasing a new version consists of packaging the software and distributing it. The Projects are set up to automatically perform this process on a Continuous Integration (CI) system (e.g. Github Actions). The process is triggered automatically when a new tag (of the form `v1.2.3`) is pushed to the Git repository. The tag message should be of the form `Version x.x.x` for final releases and `Version x.x.x. alpha1/beta1/RC1` for pre-releases. | ||
|
There was a problem hiding this comment. I think the tag message should be removed or at least loosened, as it is, in my opinion, not important. There was a problem hiding this comment. I suggested that because I observed that the message was pretty inconsistent across releases in a project, and across projects. I like consistency. But you're also right that it is not the most important part of the HEP. |
||
|
|
||
| ## Distribution | ||
|
|
||
| HoloViz maintainers are responsible for distributing the Projects on these platforms: | ||
|
|
||
| - Pre-releases are distributed on [PyPI](https://pypi.org) and on the *pyviz/label/dev* channel of [Anaconda.org](https://anaconda.org). | ||
| - Final versions are distributed on [PyPI](https://pypi.org), and on the *conda-forge* and *defaults* channels of [Anaconda.org](https://anaconda.org). | ||
|
|
||
| ## Release cadence | ||
|
|
||
| The Projects have not adopted a regular release cadence, a new release happens whenever maintainers find it is appropriate. A Project is free to adopt a regular release cadence. | ||
|
|
||
| Major regressions in a release should be fixed and released in a new patch version as soon as possible. | ||
|
|
||
| ## Deprecation and removal policy | ||
|
|
||
| The Projects can deprecate a feature in any type of final release (patch, minor, or major). Maintainers have to make sure that their users are well informed of the deprecation. They **must** mention the deprecation in the following ways: | ||
|
|
||
| - Programmatic warning: The `warnings` module from the standard library must be used to emit a deprecation warning (`import warnings; warnings.warn(...)`). The warning message must indicate that the feature is deprecated (it can indicate which version deprecated it) and that it is going to be removed in a future version, without indicating in which version exactly (see why below). The warning type must be a subclass of `DeprecationWarning`, `PendingDeprecationWarning`, or `FutureWarning`. `stacklevel` must be set so the warning appears in the correct place. For example: `warnings.warn('Function foo is deprecated since Panel 1.2.3 and will be removed in a future release, use bar instead.', DeprecationWarning, stacklevel=3)`. When a programmatic warning cannot be implemented, the *Pull Request* deprecating the feature must clearly explain why. | ||
| - Docstring (if applicable): the docstring of the deprecated feature must be updated to mention the deprecation, when possible the [`deprecated`](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-deprecated) Sphinx directive should be used. | ||
| - Documentation: all usage of the deprecated feature must be removed from the documentation, except from the section that serves as the reference API. Special cases (e.g. major API change) will need extra documentation. | ||
| - Release notes: the release notes must list the deprecated feature. | ||
|
|
||
| When a feature has been deprecated, its warning and documentation must stay in place for some time long enough to let most users find out about it. For example, Panel users who lock the dependencies of their application should be given sufficient time between the deprecation of a feature and its removal so as not to miss the deprecation warnings and be left with broken code, once they attempt to upgrade their version of Panel to the latest. A deprecated feature **can only be removed 18 months after users have been informed of its deprecation**. This period, introduced by this HEP, factors in the facts that: | ||
|
|
||
| - Users cannot build expectations about when in time a feature is going to be removed if the deprecation indicates a version number (e.g. `'This feature will be removed in version 1.2.3'`) as the Projects don't release new versions based on a regular cadence. | ||
|
There was a problem hiding this comment. I don't buy this. Adding a version when the removal is being made is fine for both the users and us as developers. I also think defining the deprecation period of 18 months is too long for some packages (Panel) because a lot of releases can have happened in that time period, whereas for other packages, it may not be enough (colorcet). In a worst-case scenario, a user could download a package on the last day of the 17th month and start using it, only to see it removed the next day because of a new release. By keeping a table, updating it, and checking it, we also add extra burden on us as maintainers to keep it up to date. Having the deprecations as close to the code as possible makes it easier to avoid it from getting out of sync. Again, I'm very much on having at least the option to put the version where the removal is gonna happen in the warning message, like what Matplotlib and xarray does. To be clear, this is not what all packages do. An example of this is pandas, which postpone it to the future, but they seem to be moving towards more major releases with breaking changes. There was a problem hiding this comment.
My main goal here is to define a minimum deprecation period that all HoloViz projects can adhere to. I think it'd have benefits for its users and maintainers. I could see allowing projects to specify the removal version as long as they ensure that it meets the minimum deprecation period. For example, if a project releases
I don't think the number or frequency of releases matters so much for the deprecation period. The deprecation period is mostly a tradeoff between letting users have enough time to adapt (apps and libraries) and reducing the cost of maintaining a project. I want HoloViz as a whole project to agree on a minimum deprecation period. Individual projects are free to adopt longer deprecation periods.
This isn't a very good counter-example, as this is all about probability, and in that case well, bad luck! The same could happen with a shorter or longer deprecation period. Just to be clear, I'm not saying you should make a new release right after the deprecation period is over.
I don't think HoloViz projects are used to deprecating and removing features, while I'd argue they should do it more to clean up their ever-growing API that sometimes confuses their users. For instance, I personally rarely check whether some code could be removed when I do a new minor release. I haven't built that muscle working on HoloViz projects. How about other maintainers? So I'm suggesting here a systematic approach to dealing with deprecated features, I don't think it's so much extra burden, and I anyway think it's part of the maintainer's job and more precisely of the release manager.
|
||
| - Many HoloViz users are not professional software developers/engineers, they use Python to help them accomplish their work and as such touch code less frequently. | ||
|
|
||
| Maintainers are encouraged to create a table of deprecated features (e.g. in an *Issue*) that includes the dates after which these features can be removed, and check regularly this table not to miss the opportunity to remove a deprecated feature. | ||
|
|
||
| ## Backwards compatibility | ||
|
|
||
| The HoloViz Projects serve different purposes in the ecosystem. Some are more foundational and have been in place for a long time, this includes for instance Colorcet or Param. Given their position, these Projects should be treated with extra care when it comes to backwards compatibility. For instance, maintainers of these Projects should favor making breaking changes in major releases and adopting longer deprecation periods. On the other hand, some Projects are newer and have an API that is still being gradually refined (e.g. hvPlot). These Projects are not expected to be as stable, they change more quickly. | ||
|
|
||
| Overall, the HoloViz Projects are known to be stable and their users have built this expectation. The functionalities they provide are generally not moved or removed lightly. Maintainers should aim to keep the Projects stable, moving or removing a feature from a code base must be motivated by a significant maintenance cost, in particular when it is done outside of a major release. | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would remove the sentence about "significant new functionality", I think we should be perfectly comfortable making a major release solely to make API changes.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The sentence says
should normally include significant new functionalityso it doesn't make it a strong requirement.By the way, I literally copied these definitions from a comment from @jbednar holoviz/panel#5221 (comment).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Right after that comment I wrote "I'd be interested in whether other team members think this description is accurate.", but no one engaged with it. Reading it now, I'm happy for @philippjfr to make the call -- would we normally provide some carrot along with the stick, i.e. provide some enticement to make it worth switching? You make more releases than I do, so I leave it to your discretion.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
FWIW I re-used your description as I found it appropriate.