Document supported software versions

[mohe2015]

Hi,

if there are already resources to the following please just link them.

As this came up in https://github.com/NixOS/nixpkgs/pull/131821 I would like some information on supported versions of the software (cli and certificates) and of their stability guarantee. Is a 0.x update considered breaking? Are older than the latest versions considered to be still supported and if yes which ones exactly? What about security vulerabilities? Will they be fixed only in the latest versions or also in older ones?

If you have a stable distribution should 0.x updates not be done and only e.g. 0.15.y updates be done?

Edit: Do you / could you highlight security updates in release notes?

Kind regards Moritz

[dopey]

Hey @mohe2015 these are excellent questions. We should publish our current answers in our documentation (@tashian @devadvocado) - @mohe2015 is there a standard location for this sort of documentation? As part of our install documentation?

Is a 0.x update considered breaking?

We bend over backwards to make sure our new releases are backwards compatible. We don't make any guarantees, but so far we have not broken this trend.

Are older than the latest versions considered to be still supported and if yes which ones exactly?

Older versions are not supported. Meaning that we will not go back and patch older versions.

What about security vulerabilities? Will they be fixed only in the latest versions or also in older ones?

Security vulnerabilities will only be updated in new releases.

If you have a stable distribution should 0.x updates not be done and only e.g. 0.15.y updates be done?

0.x updates or 0.15.y updates should both be fine. No reason to avoid updating to the next minor version. Thus 0.16 is backwards compatible.

Do you / could you highlight security updates in release notes?

We do not. We definitely can and should. @devadvocado

Relatedly - we're a small team and weary about adding more to our release process, however, we would be grateful for recommendations process-wise that would make your life easier. As someone who monitors multiple projects, we would love to hear your opinions on what works or doesn't, and what could be small but impactful improvements in our release, stability, and vulnerability documentation.

cheers

[mohe2015]

Hey @mohe2015 these are excellent questions. We should publish our current answers in our documentation (@tashian @devadvocado) - @mohe2015 is there a standard location for this sort of documentation? As part of our install documentation?

For security related things Github at least recommends a SECURITY.md at https://github.com/<user>/<project>/security/policy (https://gist.github.com/mohe2015/e1ed6c61dc215eef64162434b7168b35 is my example). I don't know the standard practice though. I think the supported software versions / link to SECURITY.md should be in the README.md of the respective project so it's easily found.

Do you / could you highlight security updates in release notes?

We do not. We definitely can and should. @devadvocado

Github has a security advisory feature https://github.com/<user>/<project>/security/advisories which may be helpful additionally to mentioning it in the release notes in the title and/or at the top. In my opinion you should also think about requesting CVEs (as far as I know it's a simple web form to request them). @risicle

Relatedly - we're a small team and weary about adding more to our release process, however, we would be grateful for recommendations process-wise that would make your life easier. As someone who monitors multiple projects, we would love to hear your opinions on what works or doesn't, and what could be small but impactful improvements in our release, stability, and vulnerability documentation.

cheers

cc @risicle

[devadvocado]

Had the security section in the CHANGELOG, but will investigate the security readme recommendation. Thanks and closing for now!