LTS Release Strategy and corresponding changes

[pradeepp88]

Creating this PR to add the LTS (Long Term Support) Release Strategy for Aca-py releases. This closes #2993

The following are the summary of changes.

1. Releases section added to Readme
2. LTS Release Strategy document added to docs
3. Snyk container image scanning mode changed to 'monitor' for LTS images
   4. Supported Features checklist updated with LTS versions

[swcurran]

@WadeBarnes -- love to get your eyes on this a bit around two specific questions:

• Are you happy with the Snyk approach to scanning images (which I think is the plan) for the security vulnerabilities that we have to be able to patch in LTS versions of ACA-Py? My question is about whether that gets us the dependabot style dependencies that we would get from source code scanning. I'm assuming so, but don't understand this well enough that I can confirm it for myself.
• Is there sufficient guidance on the mechanics of releasing a patch -- e.g. easy enough that I can follow it...

Thanks!

[esune]

Added a couple of comments/questions. Looking good overall!

[esune]

Can we assume/declare that patches applied after a LTS release is designated will become the new LTS release? Example: 0.12.1 is designated as LTS, vulnerabilities are found and 0.12.2 is released and becomes the new LTS for that, and so on.
If we don't do this (and maintain multiple branches for an LTS) we will likely get flagged multiple times for the same problem.

[swcurran]

I think the intention is that a minor release — e.g. 0.12 — is the LTS and any patch releases are part of that. So currently we have 0.11 and 0.12 as LTS for the times specified, and the patch releases are part of that.

[esune]

Is the idea to keep an active branch for each LTS minor version? Could we have a x.x-lts branch instead that starts at the time a release is designated as LTS and continues until support is dropped?

[swcurran]

Yes, but we still need to have an explicit identifier on each patch.

[esune]

We will have a tag for each release we create, so that we can go back to that point at any time. I think that having multiple branches for each minor could cause us to get alerts for old branches for which a newer release has already fixed the vulnerabilities.

[pradeepp88]

This workflow will kick off only if there is a push to the branch. Example 0.12.2 is released, it will be added to Snyk monitor i.e. new project is created in Synk account.
Once the newer patch version of LTS (ex. 0.12.2) is added to the monitor, older patch version (0.12.1) needs to be removed from monitoring by deleting the project in Snyk account.

[esune]

I feel like this might generate operational overhead since we have to track/manage branches in two places (the repo and the Snyk project) - hence the idea of having a -lts branch for the major.minor version designated as such. It would keep being updated for the life of the LTS release, tags will be created for each minor release to have point-in-time traceability and it will only require maintainers to go and delete the project in Snyk (unsure on how to access that at this time) once the LTS status expires.

[swcurran]

There will be exactly one long-lasting branch per LTS minor release, and all of the patch releases will be from that branch. We currently have 0.11.x and 0.12.x branches for the 0.11 and 0.12 LTS, respectively — although we are planning to rename them to 0.11-lts and 0.12-lts. They will be created at the latest patch created at the time we declare it an LTS. So, for example:

• Release a minor version — e.g. 1.0.0
• Wait a bit for it to stabilize — perhaps a 1.0.1, and 1.0.2, or even a 1.1.0
• Declare it LTS and create the “1.1.lts” branch at tag 1.1.0
• 1.1.1 and so on are all on the LTS branch.

As such, the synk yml only needs to be updated when we declare an LTS, and removed when we end of life it.

[esune]

@WadeBarnes -- love to get your eyes on this a bit around two specific questions:

* Are you happy with the Snyk approach to scanning images (which I think is the plan) for the security vulnerabilities that we have to be able to patch in LTS versions of ACA-Py?  My question is about whether that gets us the `dependabot` style dependencies that we would get from source code scanning.  I'm assuming so, but don't understand this well enough that I can confirm it for myself.

* Is there sufficient guidance on the mechanics of releasing a patch -- e.g. easy enough that I can follow it...

Thanks!

I think the Snyk approach is good for LTS, as it should catch anything that is in the image and therefore on the related code branch. For the release steps I think they would be the same as for a regular release, except they will be targeting the specified LTS branch. It might be a good idea to create a "maintainer handbook", possibly as we go through the process the first time?

[swcurran]

My apologizes for having taken so long to read through this. I think there needs to be some updates to the document to clarify what is meant — particular around release numbering. Here are my comments and suggestions.

First, please change the Aca-pys to ACA-Py in the PR 😄 .

Next up, the confusion about release numbering. Because we have been so slow in getting to Release 1.0.0, we’ve been treating the second and third (the y and z in the semver x.y.z numbering scheme) as major and minor releases instead of what they should be — minor and patch. That is not inadvertent, particularly as it relates to LTS, and will not continue past the 1.0.0 release. Going forward, we will use proper x.y.z for proper major.minor.patch. From time-to-time, we will declare a certain x.y release as an LTS, and will release as needed z patches for the LTS.

So:

• For prior to 1.0.0, a change in the minor release number has served as a breaking change indicator.
• From 1.0.0 on, the major release number will serve as the breaking change indicator.

The LTS description needs to be updated to reflect that.

In either case, the combination of x.y (major.minor) will be used when designating an LTS, and all of the patches (zs) based on those numbers will be for the purpose of LTS releases. I would expect that pretty much any release that is NOT an LTS patch will trigger a minor (y) update.

The declaration of an x.y combination should be in the README.md.

As per Aries RFC 0799 LTS, the end date for an LTS is defined only when the next LTS is declared and is 9 months after that date. As such, for now, 0.11 is an LTS with a deadline of April 11, 2024 + 9 months, or January 11, 2025. The end date for 0.12 is undefined, as a successor LTS has not been defined. I think in the current PR, the end-dates are calculated as 9 months from the release of the designated LTS vs. from the next LTS.

I think more of the material from the Aries RFC could be used in the LTS document.

When we declare an LTS (some x.y.0), we will create a branch at that point (labelled, presumably x.y or maybe x.yLTS), and that is what will be monitored for vulnerabilities going forward. We’ll PR or apply cherry-picked PRs to that branch and then do the patch releases from there using the normal release process.

One thing I’m not sure how best to handle is the tagging of an LTS image. Obviously, it will get the normal x.y.z tag, but is it also possible to publish docker images with an “LTS” tag that moves (like “latest”) along the path of any LTS release?

@pradeepp88 — do you have time to take a crack at updating the text in the PR to reflect these suggestions?

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarCloud

[pradeepp88]

Updated the LTS Strategy document with updates. @swcurran @esune please review.

[esune]

I like the wording changes, I think now the document is definitely clearer. I am still thinking about overhead in the management of minor branches in the repo and Snyk - see comment in snyk-lts.yml

[swcurran]

There is currently no defined end date for 0.12.x, and the end date for 0.11.x is January 2025 (9 months after we declared 0.12.x to be LTS).

[swcurran]

Suggest we change the text above to be [0.12-lts] and [0.11-lts] and update this note to say that those are the= names of the branches from which the LTS patch releases are produced.

[swcurran]

Nit-pick, but it should always be “ACA-Py”.

[swcurran]

Same nit-pick — “ACA-Py”, not “Aca-Py” or “Ace-py”.

[swcurran]

“uses”, not “will use”. You might want to add a “semver” reference here — https://semver.org/

[swcurran]

“Major” is the first digit, so change the example to “1.0.0”.

[swcurran]

Suggested rewording:

From time to time, ACA-Py maintainers will declare that a given major.minor combination will be an LTS release. At that point a branch will be created from the git tag for that release, and series of patch releases will be published as needed to provide long term support. For example, Release 1.1.0 might be declared LTS. A branch 1.1-lts will be created, and patches 1.1.1, 1.1.2, etc. will be published from that branch as needed to meet LTS requirements.

[swcurran]

Tweak the sentence to: "After a LTS release is designated, major and minor releases will continue to be published from the ACA-Py main branch."

[swcurran]

I’ve suggested a few more changes that I think clarify the approach.

I think the snyk yml change is needed. We’ve explained the approach, but as I write this, I realize that I’m kind of assuming the processing will be against the repo branch, and not against the container generated from the latest release. As such, I may not be right…

The goal of the snyk scanning is that we be notified of any vulnerability in the last patch for the LTS.

[swcurran]

@pradeepp88 -- we really need this completed urgently. Can you make the changes? Or are you OK with me grabbing the files and putting them into my own PR? You should get the credit, so wouldn't normally ask, but we really need this PR merged very soon!

Thanks

[swcurran]

Closing this as replaced by #3143 that used the changes from this PR as the basis for that one. We just can't wait to get the updates into this PR. Thanks for pushing this issue, @pradeepp88 --- sorry we couldn't wait on your PR.