Release lifecycle marking #225
Conversation
Initial proposal for rules for marking status of released version.
specification/versioning.md
Outdated
| - Release which was superseded by newer version, thus has entered deprecation | ||
| period `MUST` be marked as **Deprecated** and `MUST` indicated planned | ||
| end of support date. This indicates that users should plan for upgrade to | ||
| latest or active version respectively before date given. |
There was a problem hiding this comment.
Does this concern only major versions? Or are we supposed to add EOS dates to minor releases?
There was a problem hiding this comment.
Minor and Major:
- Major version can be used and live for more than 12M
- In some cases Major releases may be rare
There was a problem hiding this comment.
@mateuszrzeszutek any additional comment, feedback, recommendations?
There was a problem hiding this comment.
Personally, I would prefer to have one definition of life cycle status which we could use on all levels:
- releases of components
- features of components
- GDI specification
- other? 😅
The other think is how we "mark" the life cycle status of a release.
If we have a consensus on it then I propose to make two separate issues. The first one, to refine the life cycle status definition. And a second, to define how releases are affected by its life cycle statuses.
specification/templates/CHANGELOG.md
Outdated
| ### Life cycle status | ||
|
|
||
| Use one of: | ||
| - *Latest* | ||
| - *Active* | ||
| - *Deprecated:* End of Support expected on 2024-04-01 | ||
| - *End of Support:* Support has ended on 2024-04-01 | ||
|
|
||
|
|
There was a problem hiding this comment.
This file in an example.
The requirements for changelog should be defined here: https://github.com/signalfx/gdi-specification/blob/main/specification/repository.md#required-files
There was a problem hiding this comment.
So theses are different aspects that I see
- Released functionality maturity (distro level): - no change -SemVer 2.0 + OTel compatible maturity model
- Component maturity - same as above - no change - also out of scope for this PR
- Release lifecycle - this is what is proposed here as an extension not replacement of existing rules
- GDI Spec - not related to release lifecycle as specification does not produce binary that we would have to directly support
Thus I would still suggest to consider the change above
There was a problem hiding this comment.
@pellared I want to limit the current PR to pint No. 3 - We can add the component level clarifications separately. Please let me know if you are ok with this
specification/versioning.md
Outdated
| Each release `MUST` clearly state the life cycle | ||
| status and described as: Active, Latest, Deprecated, End of Support. |
There was a problem hiding this comment.
This definition conflicts with https://github.com/signalfx/gdi-specification#lifecycle-status (the section would need to be updated as well).
Do we want to use different "status definitions" and "life cycle" for specification, features, releases? Maybe we could align and use the same approach on al levels?
Personally, I would keep the existing list defined in https://github.com/signalfx/gdi-specification#lifecycle-status, but just add "End of Support".
There was a problem hiding this comment.
It is possible to use the same list of labels/statuses on levels however the meaning might be little different depending on the context although it will sound artificial as we want to describe different aspect of management eg lifecycle instead of maturity. If we decide to go this way we will have to do a definition matrix to clearly explain meaning of each status in each aspect we want to control.
There was a problem hiding this comment.
@pellared I would suggest to clarify the is section stating that lifecycle status consist of maturity status and release status. Please let me know what you think.
It would look something like this
Lifecycle status
The support guarantees and allowed changes are governed by the lifecycle of the
document. Lifecycle stages are defined in the
versioning document. Lifecycle consist of maturity status
of the specification and its elements and release status of versions released.Maturity status
Status Explanation No explicit "Status" Equivalent to Experimental. Experimental Breaking changes are allowed. Stable Breaking changes are no longer allowed. [1] Deprecated Changes are no longer allowed, except for editorial changes. Release status
Status Explanation Supported Release currently supported. Deprecated Release is deprecated and pending End of Support. End of Support Release no longer supported.
There was a problem hiding this comment.
I like this idea 👍 Still I think it would be easier if we move the requirements for releases to a separate document.
Co-authored-by: Robert Pająk <[email protected]>
Co-authored-by: Robert Pająk <[email protected]>
Active an Latest replaced with supported Changes made in both files: versioning.md and CHANGELOG.md
…fx/gdi-specification into versioning-release-status
| @@ -77,3 +77,35 @@ until the end of that component’s existence: | |||
| MUST be provided as the latest `PATCH` version for the latest `MINOR` version | |||
| of the latest `MAJOR` and SHOULD NOT be provided for previous `PATCH` or | |||
| `MINOR` releases. | |||
|
|
|||
| ## Release life cycle management | |||
There was a problem hiding this comment.
How about moving this to a separate file specification/releases.md. It would be more obvious that versioning.md is about versioning of the specification and release.md is about requirements connected with releases.
If you agree, please remember to add a - [Releases](specification/releases.md) in README.md.
There was a problem hiding this comment.
I like this idea once we've approved the content.
| Each repository `MUST` use [GitHub releases mechanism](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases) | ||
| to create a versioned snapshot of components and features | ||
| delivered to the users. If the release is also distributed via other | ||
| distribution channels (e.g. CDN, Registries, AppStores) it `MUST` state | ||
| its life cycle status according to following rules by any means available | ||
| in the given software distribution solution. | ||
|
|
||
| Each release `MUST` clearly state the life cycle | ||
| status and described as: Supported, Deprecated, End of Support. | ||
| At minimum the required information should be included in [CHAANGELOG.md](https://github.com/signalfx/gdi-specification/blob/main/specification/templates/CHANGELOG.md) | ||
| and equivalent mechanism provided by system used for distributing software. | ||
|
|
||
| If new version is released previously released versions `MUST` be evaluated | ||
| according to stability guarantees and marked as: | ||
|
|
||
| - Latest release `SHOULD` be marked as **Supported** indicating that this is | ||
| version recommended to new and existing users | ||
| - If applicable latest release of previous `MAJOR` line that is still under | ||
| active development `MUST` be marked as **Supported** indicating that previous | ||
| `MAJOR` line is under active development and users not ready to adopt | ||
| latest `MAJOR` version may use previous versions. | ||
| - Release which was superseded by newer version, thus has entered deprecation | ||
| period `MUST` be marked as **Deprecated** and `MUST` indicated planned | ||
| end of support date. This indicates that users should plan for upgrade to | ||
| one of supported versions before date given. | ||
| - Release which deprecation period has ended `MUST` be marked as | ||
| **End of support** and `MUST` indicate date on which the release was marked | ||
| as end of support. This indicates that support for given release is no longer | ||
| provided and the users should immediately upgrade to newer supported version. |
There was a problem hiding this comment.
I made some nit changes, remove some IMO unnecessary sentences or wording, I tried to restructure it a little to make it easier to read and validate when adopting the spec.
| Each repository `MUST` use [GitHub releases mechanism](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases) | |
| to create a versioned snapshot of components and features | |
| delivered to the users. If the release is also distributed via other | |
| distribution channels (e.g. CDN, Registries, AppStores) it `MUST` state | |
| its life cycle status according to following rules by any means available | |
| in the given software distribution solution. | |
| Each release `MUST` clearly state the life cycle | |
| status and described as: Supported, Deprecated, End of Support. | |
| At minimum the required information should be included in [CHAANGELOG.md](https://github.com/signalfx/gdi-specification/blob/main/specification/templates/CHANGELOG.md) | |
| and equivalent mechanism provided by system used for distributing software. | |
| If new version is released previously released versions `MUST` be evaluated | |
| according to stability guarantees and marked as: | |
| - Latest release `SHOULD` be marked as **Supported** indicating that this is | |
| version recommended to new and existing users | |
| - If applicable latest release of previous `MAJOR` line that is still under | |
| active development `MUST` be marked as **Supported** indicating that previous | |
| `MAJOR` line is under active development and users not ready to adopt | |
| latest `MAJOR` version may use previous versions. | |
| - Release which was superseded by newer version, thus has entered deprecation | |
| period `MUST` be marked as **Deprecated** and `MUST` indicated planned | |
| end of support date. This indicates that users should plan for upgrade to | |
| one of supported versions before date given. | |
| - Release which deprecation period has ended `MUST` be marked as | |
| **End of support** and `MUST` indicate date on which the release was marked | |
| as end of support. This indicates that support for given release is no longer | |
| provided and the users should immediately upgrade to newer supported version. | |
| Each release MUST clearly state the life cycle | |
| status and described as one of: | |
| **Supported**, **Deprecated**, **End of Support**. | |
| Each repository MUST use [GitHub releases mechanism](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases) | |
| to publish versioned artifacts of components | |
| delivered to the users. | |
| The release the life cycle status MUST be included | |
| in [CHANGELOG.md](templates/CHANGELOG.md). | |
| When the component is also distributed via other channels | |
| (e.g. CDN, Registries, AppStores) it MUST state | |
| its life cycle status according to following rules by any means available | |
| in the given software distribution solution. | |
| When a new version is released it MUST be marked as **Supported**, | |
| and all previously released versions MUST be evaluated | |
| according to stability guarantees and marked as: | |
| - If applicable latest release of previous `MAJOR` line that is still under | |
| active development MUST remain as **Supported** indicating that previous | |
| `MAJOR` line is under active development and users not ready to adopt | |
| the latest `MAJOR` version may use previous versions. | |
| - Release which was superseded by newer version, thus has entered deprecation | |
| period `MUST` be marked as **Deprecated** and MUST indicated planned | |
| end of support date. This indicates that users should plan for upgrade to | |
| one of supported versions before date given. | |
| - Release which deprecation period has ended MUST be marked as | |
| **End of support** and MUST indicate date on which the release was marked | |
| as end of support. This indicates that support for given release is no longer | |
| provided and the users should immediately upgrade to newer supported version. |
| period `MUST` be marked as **Deprecated** and `MUST` indicated planned | ||
| end of support date. This indicates that users should plan for upgrade to |
There was a problem hiding this comment.
Do we have already a requirement how long it must be supported? If so can we define it? Otherwise it will be hard to adopt the specification.
What if the latest release fixes a security vulnerability? Shouldn't we immediately drop supported require a version bump?
Co-authored-by: Robert Pająk <[email protected]>
Initial proposal for rules for marking status of released version. It will allow to clearly define window of support (all releases currently supported) and pass the information to the end users.
If the change is accepted we all released versions described in the changelog should be updated with appropriate status