Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Release lifecycle marking #225

Draft
wants to merge 8 commits into
base: main
Choose a base branch
from
Draft

Release lifecycle marking #225

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
9c52399
Release lifecycle marking
akubik-splunk Mar 30, 2023
e3d8c5c
Update specification/versioning.md
akubik-splunk Mar 30, 2023
85a4fd3
Update specification/versioning.md
akubik-splunk Mar 30, 2023
414b731
Updates after review
akubik-splunk Apr 4, 2023
2fb616a
Merge branch 'versioning-release-status' of https://github.com/signal…
akubik-splunk Apr 4, 2023
4e4af47
md lint fixes
akubik-splunk Apr 4, 2023
866050d
Merge branch 'main' into versioning-release-status
akubik-splunk Apr 4, 2023
1f17e86
Update specification/templates/CHANGELOG.md
akubik-splunk Apr 6, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions specification/templates/CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,15 @@ and this repository adheres to [Semantic Versioning](https://semver.org/spec/v2.

## Version 0.1.0 - 2021-04-01

### 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


Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Author

@akubik-splunk akubik-splunk Mar 30, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So theses are different aspects that I see

  1. Released functionality maturity (distro level): - no change -SemVer 2.0 + OTel compatible maturity model
  2. Component maturity - same as above - no change - also out of scope for this PR
  3. Release lifecycle - this is what is proposed here as an extension not replacement of existing rules
  4. 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

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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

### General

- This release marks the first release of the repository.
Expand Down
30 changes: 30 additions & 0 deletions specification/versioning.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,3 +77,33 @@ 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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 snapshot of components
and features delivered to the users. If release is also distributed via other
distribution channels (e.g. CDN, Registries, AppStores) it `MUST` be described
according to following rules by any means available in the given software
distribution solution.
akubik-splunk marked this conversation as resolved.
Show resolved Hide resolved

Each release `MUST` clearly state the life cycle
status and described as: Active, Latest, Deprecated, End of Support.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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".

Copy link
Author

@akubik-splunk akubik-splunk Mar 30, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Author

@akubik-splunk akubik-splunk Apr 4, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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.

Copy link
Contributor

@pellared pellared Apr 6, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like this idea 👍 Still I think it would be easier if we move the requirements for releases to a separate document.

pellared marked this conversation as resolved.
Show resolved Hide resolved
pellared marked this conversation as resolved.
Show resolved Hide resolved
At minimum the required information should be included in [CHAANGELOG.md](https://github.com/signalfx/gdi-specification/blob/main/specification/templates/CHANGELOG.md)
akubik-splunk marked this conversation as resolved.
Show resolved Hide resolved
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 **Latest** indicating that this is
version recommended to new and existing users
pellared marked this conversation as resolved.
Show resolved Hide resolved
- If applicable latest release of previous `MAJOR` line that is still under
active development `MUST` be marked as **Active** 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
latest or active version respectively before date given.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this concern only major versions? Or are we supposed to add EOS dates to minor releases?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor and Major:

  1. Major version can be used and live for more than 12M
  2. In some cases Major releases may be rare

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mateuszrzeszutek any additional comment, feedback, recommendations?

- 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 version.
pellared marked this conversation as resolved.
Show resolved Hide resolved