Decide on deprecation strategy

[lukpueh]

The current plan is to develop the new TUF alongside the old TUF (see #1126).
How long after the refactor is complete will we continue to support the old code base? What does support look like? Bug fixes? Security fixes? We need a roadmap there. The main reason to keep the old code base around is to have a client that supports Python 2.7 (see #1125). Not sure if this is a good reason for very much longer.

Independently of the refactor, we might generally want to think of a deprecation strategy for the future. E.g. do we want to display deprecation warnings for n releases before we drop interface functions? This probably only makes sense if we follow a stricter release schedule than we do now.

[joshuagl]

There's also a difference between accepting bug and security fixes, and making releases that include them, and actually fixing bugs and addressing security issues.

I don't think we have the resources to maintain two versions of the codebase, so I'd like us to end up on a path that means that once the refactor is complete we delete the old code and forget about it ASAP.

I'm absolutely in favour of defining and adhering to a stricter release schedule and having a deprecation strategy so that we aren't removing API without warning.

[mnm678]

I agree that we want to focus our efforts on the new code. I'd propose that we continue to review bugs and security fixes for some period of time (maybe a year), and possibly contribute security patches during this time. Then, if anyone still really needs that code, they could fork and maintain themselves so that we can focus on the new version.

I'm absolutely in favour of defining and adhering to a stricter release schedule and having a deprecation strategy so that we aren't removing API without warning.

Even if we don't have a strict schedule, we should have some way to communicate to users when the API will change (maybe something like tap 14, but for the API)

[joshuagl]

I think we need both a deprecation strategy for the current release series (particularly as we expect the refactor to do away with support for older Python versions), and a deprecation/API stability strategy for releases after the refactor.

For the current release series, I think what would make most sense is to focus any maintenance efforts on the client. That is the piece of the current series which is most difficult to upgrade (repository owners can switch to Python3 easily but might not be able to influence repository users to make the same upgrade).

One strategy for the client might be to create a branch of the repository which removes all of the non-client code and commit to maintain that for at least one year. I'd propose the maintenance strategy clearly define expectations:

• that we will review any functional bug and security fixes proposed to the branch (PRs)
• that severe security issues and functional bugs will be addressed on a best effort basis
• that we will release updates with any generated fixes in a timely fashion

I think it might also make sense to have that branch produce a separate PyPI package for the Python2 supporting client which is clearly marked (on PyPI) as not actively adding new features and only supporting Python 2.7.

[joshuagl]

I think we need both a deprecation strategy for the current release series (particularly as we expect the refactor to do away with support for older Python versions), and a deprecation/API stability strategy for releases after the refactor.

For the current release series, I think what would make most sense is to focus any maintenance efforts on the client. That is the piece of the current series which is most difficult to upgrade (repository owners can switch to Python3 easily but might not be able to influence repository users to make the same upgrade).

One strategy for the client might be to create a branch of the repository which removes all of the non-client code and commit to maintain that for at least one year. I'd propose the maintenance strategy clearly define expectations:

• that we will review any functional bug and security fixes proposed to the branch (PRs)
• that severe security issues and functional bugs will be addressed on a best effort basis
• that we will release updates with any generated fixes in a timely fashion

pip's deprecation of Python 2.7 phrases this quite nicely

bugs reported with pip which only occur on Python 2.7 would likely not be addressed directly by pip’s maintainers. Pull Requests to fix Python 2.7 only bugs will be considered, and merged (subject to normal review processes). Note that there may be delays due to the lack of developer resources for reviewing such pull requests.

[trishankatdatadog]

Agreed. We have finite resources, and this is a reasonable policy.

[joshuagl]

a deprecation/API stability strategy for releases after the refactor.

Does anyone have any opinions on API stability/deprecation policy?

Python has a policy of annual releases (PEP 602) with a promise of "at least two releases before a deprecated feature is removed from Python or a __future__ behavior is enabled by default."

I don't think that's an exact model for us to follow, two years sounds like a long time for a small team to maintain deprecated API. However, waiting at least a couple of releases with the API being marked as obsolete/deprecated before it's actually removed seems reasonable.
That does somewhat require us to have decent, online documentation which our users might read these obsoletion notifications in (see #1053, should probably move that into the 1.0 project board).

Related to a proposed deprecation policy, we might also want to think about release schedule:

• Do we anticipate major releases of the reference implementation being tied to a major release of the specification? If yes, that would tie our major releases to the specification. We don't expect the specification major version to change often.
• How frequently do we expect to make non-major releases? With the frequency dependabot PRs I think we should strive for regular releases, even if they are only patch releases which bump pinned dependencies. Our extremely outdated ROADMAP.md suggests we will release every 3 months. It seems reasonable to strive for releases at least every three months, with more frequent releases when we have changes to release, or more urgent fixes.

I think we have three questions to answer and document:

1. what's our proposed release schedule? or at least our worst case release scenario i.e. a release at least once every 3 months, to include dependency updates.
2. what's our proposed API stability/deprecation policy? i.e. API to be marked as obsolete and not removed for at least two significant releases after the release where it is first marked obsolete (where significant releases are major or minor, not patch).
3. what's our release versioning strategy? will we tie major version to specification versions? If yes, we might confuse users unless we also match minor version – why does python-tuf 1.2.3 implement TUF specification 1.0.15?

[jku]

Do we anticipate major releases of the reference implementation being tied to a major release of the specification?

This sounds like possibly a bad idea. You already mentioned the confusion on minor number, but also: Software version should reflect changes in the software. Major changes to the software may be required without any changes to the spec.

Also, as a thought exercise I can imagine a spec revision that is in some way incompatible with previous version, but that the following python-tuf releases supported both versions of the spec in some manner (like possibly the client could work as spec v1 client and spec v2 client).

what's our proposed release schedule?

Does this need to be documented? Your proposal of "Planned maximum release cadence of 3 months" sounds good but as you said this follows from dependency changes so could change over time...

what's our proposed API stability/deprecation policy?

This is very tied to the question what is our API? Currently this is not really defined and then it's quite hard to make promises about supporting the API... This also ties into publishing the documentation: I like some level of documentation for all functionality but once it's on readthedocs or something, the internal functionality should be clearly marked as such if it's published at all.

Sorry, no great answers to the actual question...

[joshuagl]

Do we anticipate major releases of the reference implementation being tied to a major release of the specification?

This sounds like possibly a bad idea. You already mentioned the confusion on minor number, but also: Software version should reflect changes in the software. Major changes to the software may be required without any changes to the spec.

Also, as a thought exercise I can imagine a spec revision that is in some way incompatible with previous version, but that the following python-tuf releases supported both versions of the spec in some manner (like possibly the client could work as spec v1 client and spec v2 client).

👍

what's our proposed release schedule?

Does this need to be documented? Your proposal of "Planned maximum release cadence of 3 months" sounds good but as you said this follows from dependency changes so could change over time...

Perhaps not. The reason I suggested it is because I thought that promising to not remove deprecated API for two releases probably isn't very meaningful unless those release map to some notion of time. If we make two releases in two weeks, then remove the deprecated API that won't be very useful. Maybe this just indicates that any deprecation policy should include a notion of time?

what's our proposed API stability/deprecation policy?

This is very tied to the question what is our API? Currently this is not really defined and then it's quite hard to make promises about supporting the API... This also ties into publishing the documentation: I like some level of documentation for all functionality but once it's on readthedocs or something, the internal functionality should be clearly marked as such if it's published at all.

Which suggests we might want to consider this before 1.0, where the deprecation policy would apply, but after we've done some more of the development work and have a better idea of what we're committing to.

[lukpueh]

Part 1 of this issue (deprecation of "legacy" implementation) has been formalized in ADR 2 and finalized with the release of 1.0.0.

Do we want to have a written statement for future deprecation? (see 2nd paragraph in issue description above)

[jku]

I think we should have a deprecation strategy where warnings are added (at least to release notes) before the change... But it's not something I would document very strictly: API removal/change situations are so different and hard to estimate.

In other words I'm not sure if we can be more specific than "we aim to not break existing code without warning at least a release before". That feels like what any reasonable 1.0 library would do so maybe it doesn't need to be stated?

[lukpueh]

Agreed. I think the commitment to semver along with an initial stable release already goes a long way.

[lukpueh]

Maybe @joshuagl also wants to weigh in? Otherwise I suggest to close this issue.

[joshuagl]

Let's file a new, more specific, issue if we decide we want to change anything.