docs: add initial release process description skeleton #519
Conversation
| @@ -0,0 +1,18 @@ | |||
| # Product Release | |||
There was a problem hiding this comment.
Maybe it's worth mentioning that products have their release processes and to refer to the according product specific repositories for information about those.
|
|
||
| - Defined in TRGs | ||
| - Responsibility of every contributor | ||
| - (Additonally verified in quality gate process. TBD, if kept after consortia) |
There was a problem hiding this comment.
Typo in Additonally but mainly I'd not mention consortia, may just:
Currently still verified in a Quality Gate process. TBD if this process will continue.
|
|
||
| <!-- How are products (considered to be) integrated in the Tractus-X release --> | ||
| - Prior to release, a Tractus-X umbrella Chart release candidate branch is created | ||
| - Producs issue PRs with their release candidate |
There was a problem hiding this comment.
This should be the future process, right? currently that's not happening and maybe that should be mentioned.
There was a problem hiding this comment.
Yes exactly, that's why I opened this draft PR. Jumpstarting this discussion is highly needed in my opinion.
Since this process will rely heavily on committers to support it, we need to come to a basic agreement.
The two bullet points are just a first idea, that could also make it easy for committers to support that process, since it's a more opt-in focused one.
Right now, I don't really find the time to continue working on the draft
| we encourage every component team to break these issues down to their component repositories/projects. | ||
| When doing so, make sure you link to the overarching issue in your component issue description. | ||
|
|
||
| ## Release Management Acceptance Criteria |
There was a problem hiding this comment.
IMHO everything from here on is not confirmed yet
| ## Artifacts | ||
|
|
||
| - Container images | ||
| - Helm Chart |
There was a problem hiding this comment.
shall we call these "Product Helm Chart" => to differentiate from "Umbrella HC" in TX-Release?
There was a problem hiding this comment.
Product Helm Chart with Dependencies
There was a problem hiding this comment.
Would "Helm Chart (referred to as product Chart)" be fine?.
Both, the Tractus-X Chart, as well as single product Charts do have dependencies.
Some do only include a Database dependency, but some also provide frontend and backend as separate Charts, that are then referenced in a product umbrella Chart
docs/product_release.md
Outdated
| - Defined in TRGs | ||
| - Responsibility of every contributor | ||
| - (Additonally verified in quality gate process. TBD, if kept after consortia) | ||
|
|
There was a problem hiding this comment.
process abstract
Once planning activities for a certain iteration are completed: all contributors follow their state-of-the-art feature work on all issues in status work in progress. The vehicle of product helm charts shall be used to integration-test any dependencies. All valid TRGs shall be followed, as those are crosschecked by committers upon merging any pull request - leading into a flawless GitHub release per product.
There was a problem hiding this comment.
Not quite sure, but AFAIK, only overarching features on the dataspace level are planned in sig-release and therefore are handled on a board with work in progress status.
Product features, that support the dataspace feature, could (and IMO should) be planned on product repository level. So far, we do not define rules for how products need to handle issues and boards
There was a problem hiding this comment.
update @stephanbcbauer & @RolaH1t 21-Mar:
Once planning activities for a certain iteration are completed: all contributors follow their state-of-the-art feature work on all issues in status work in progress. The vehicle of product helm charts shall be used to integration-test any dependencies. All valid TRGs must be followed, as those are crosschecked by committers upon merging any pull request - leading into a flawless GitHub release per component. This is specifically identified by a version tag.
There was a problem hiding this comment.
"state-of-the-art feature work" sounds a bit bloated, don't you think? What does that even mean 😁?
There was a problem hiding this comment.
@RolaH1t and @stephanbcbauer,
I took your input and did elaborate an change wording. What do you think of the description in this commit
c33fcc8?
| <!-- How are products (considered to be) integrated in the Tractus-X release --> | ||
| - Prior to release, a Tractus-X umbrella Chart release candidate branch is created | ||
| - Producs issue PRs with their release candidate | ||
|
|
There was a problem hiding this comment.
abstract
Once feature work on product level is initiated, the quality assurance runs in parallel. The vehicle of Umbrella helm charts is used to continuously test pre-defined product bundles.
?pre-definition: how & who?
?reference onion rings?
Example for cxOS: A configured umbrella helm chart starts-up all relevant components (environment-less!) - no matter if carry-over versions of a previous TX release or evolutions of the current iteration. User Journey tests (e2e) are automatically performed - customized for the respective bundle of components and within given boundary conditions.
!there is work to be done!
Any findings ale looped back to the product development teams.
?how?
Product teams are obliged to fix any defects which prevent successful testing of the bundle (see product release process).
A bundle is ready for TX release, once product feature work is completed for all components and e2e-testing was successful without critical findings.
?definition?
Additional, manual e2e tests may apply.
!wip!
There was a problem hiding this comment.
Good input. I'll see if I can form that to specific sections once I finally find some time for it again. I will try to avoid some of the terms you used though. Some are not (yet) known in Eclipse Tractus-X and would need too much explanation. I.e.:
cxOS -> If there is nothing provided by the association that we can reference, we we would need to re-specify, which is error prone and might diverge from their definiition.
onion rings -> meaning? relevance?
carry-over versions -> not sure what is meant with that
boundary conditions for bundles -> what are these conditions, who defines them, where can I read about it?
There was a problem hiding this comment.
cxOS may not yet be fully specified-out, but is mentioned and described by the association in the following zwo (maybe more) documents. So referencing without re-specification should be ok.
https://catena-x.net/fileadmin/_online_media_/231006_Whitepaper_Tractus-X.pdf (https://catena-x.net/fileadmin/_online_media_/231006_Whitepaper_Tractus-X.pdf)
https://catena-x.net/fileadmin/_online_media_/231006_Whitepaper_LifeCycleManagement.pdf (https://catena-x.net/fileadmin/_online_media_/231006_Whitepaper_LifeCycleManagement.pdf)
There was a problem hiding this comment.
the pictogram of "onion rings" shall be published near term, also via association, with regards to test management. will add the link here as soon as available. @danielmiehle any additional info?
There was a problem hiding this comment.
carry-over: in every quarterly TX release, we shall expect evolutions (new versions) of some cxOS components,
but also some other components may NOT face a change/up-revision in the given iteration. Nevertheless those components are still essential parts of the bundle.
This is what I meant with "carry over versions"
There was a problem hiding this comment.
text suggestion @stephanbcbauer & @RolaH1t 21-Mar:
Once feature work on product level is initiated, the quality assurance of the foreseen release package runs in parallel. The vehicle of Umbrella helm charts is used to continuously test pre-defined product bundles. Automatically and environment-less.
Reference onion rings: (add URL)
Note: In every quarterly TX release, we shall expect evolutions (new versions) of some components (see "product_release.md"). But also some other components may NOT face a change/up-revision in the given iteration. Nevertheless those components are still essential parts of the bundle.
Example for cxOS (https://catena-x.net/fileadmin/_online_media_/231006_Whitepaper_Tractus-X.pdf (https://catena-x.net/fileadmin/_online_media_/231006_Whitepaper_Tractus-X.pdf):
A configured umbrella helm chart starts-up all relevant components. No matter if carry-over versions of a previous TX release or evolutions of the current iteration. User Journey tests (e2e) are automatically performed - customized for the respective bundle of components and within given boundary conditions.
Any findings ale looped back to the product development teams.
Product teams are obliged to fix any defects which prevent successful testing of the bundle.
A bundle is ready for Tractus-X release, once product feature work is completed for all components and e2e-testing was successful without critical findings.
Additionally, manual e2e tests may apply. Environment and execution tbd.
There was a problem hiding this comment.
I get the idea of this description, but to me it almost seems like this is talking a different language, than I would expect from this process definition.
In commit c33fcc8 I started a process definition, that I think could make sense. It is not finished though and is also just a proposal, that we must discuss in the comitter round.
As general suggestion for wording, I would avoid terms, that are unknown, undefined or not commonly used.
I.e. carry-over, evolution, up-revision.
I would also avoid the "what is NOT happening" statements. Instead of "maybe there are no changes, but we still need it", I would just state, that we are testing all components in the version, that is planned to be included in the release
| - __Done:__ All relevant parts have been implemented and released | ||
|
|
||
| ### Issue process | ||
|
|
There was a problem hiding this comment.
This is done by every team individually.
Point out that this is a base, but see the product specific descriptions if they exist.
There was a problem hiding this comment.
Definitely good point, but the planning.md file is actuall just a move of some already existing README.md content.
If the current wording is misleading, we should fix that in a separate PR, that can be finished sooner than the Release Process discussion.
| @@ -0,0 +1,21 @@ | |||
| # Tractus-X Release | |||
|
|
|||
There was a problem hiding this comment.
suggestion: ##Intro
As mentioned in [planning.md] a Tractus-X release is scheduled quarterly. The Tractus-X project has an overarching qualification process that all official quarterly Tractus-X releases adhere to. This process applies E2E activities for testing and security (relevant release candidates in compound) that stakeholders can build on. Each component can/shall be released on demand on a higher cadence, see [product_release.md].
There was a problem hiding this comment.
From my point of view, the E2E and Security part need to be clarified.
To the best of my knowledge, the Tractus-X project does not have any running and persistent infrastructure, that is necessary to support the E2E and Security activities, that are currently mainly driven by the Catena-X consortia.
Also, the automated e2e-testing activities are still far from making the manual steps unnecessary.
So in my opinion, we need to find some middle ground for what is actually supported by Tractus-X and what is a Process driven by other players, like the Catena-X association or others, that is maybe to a certain extend supported by Tractus-X contributors and committers
There was a problem hiding this comment.
correct - but what we try to describe here is future target condition (to give guidance).
For sure, exceptions can be formulated afterwards or in addition - for example for May and Aug 2024.
| While every repository in the [eclipse-tractusx](https://github.com/eclipse-tractusx) GitHub organization | ||
| has its own issue management, the [Release Planning Board](https://github.com/orgs/eclipse-tractusx/projects/26) | ||
| is used to align the overarching Tractus-X releases. | ||
|
|
There was a problem hiding this comment.
I suggest adding in a new paragraph:
Release Cycle - major vs. minor release
Tractus-X operates on a quarterly release cycle. Each quarter, a new Tractus-X release tractus-x-release.md following CalVer is released. Each Tractus-X release contains multiple products product_release.md Once per year, Tractus-X releases a major release, making the remaining three releases minor releases. A major release may contain critical breaking changes that have a major impact on data space participants,
such as changes to enablement services. A minor release contains backward compatible functionality. In addition, patch versions provide backward compatible bug and security fixes.
There was a problem hiding this comment.
Hi @HFocken,
I also heard that, but actually never saw that in a tangible way.
At least "major" and "minor" is not directly visible in CalVer numbers as it would be in SemVer. Is it always the last release of a year, that will contain breaking changes?
How is this ensured in the planning process? Do issues from open planning also contain something that makes that transparent?
There was a problem hiding this comment.
Never heard of this too. Definitly something we should highlight more in our Release Notes @RolaH1t
There was a problem hiding this comment.
use text here AND on github.io page to initially introduce users to process.
add picture of phases.
|
Hi @evegufy, @RolaH1t, @HFocken and @jzbmw Thanks a lot for your feedback so far. Unfortunately I do not have enough time right now to fully work on enhancing this PR. |
|
|
||
| - __Labels:__ We use them to indicate the involved teams (kit or foss component). A label for each involved component is added to an issue | ||
| - __Issue Type:__ To separate between bugs, feature requests and release criteria, we use a custom field `Issue Type` | ||
| - __Milestone:__ Every Tractus-X release is represented by a `Milestone`. You can use this field to get a rough idea about the ETA |
| ### Issue process | ||
|
|
||
| Every new feature proposal or bug report will be handled as issue in status `Inbox` initially. The alignment meetings are used to discuss the purpose and impact of the current issues. | ||
| While in `Inbox` status, the involved components are discovered and respective `Labels` are added. If already possible, a desired `Milestone` can be set. |
| While in `Inbox` status, the involved components are discovered and respective `Labels` are added. If already possible, a desired `Milestone` can be set. | ||
| Additionally, an `Assignee` is selected, who will coordinate efforts to solve the issue. | ||
|
|
||
| After these details are clarified, an issue is moved to `Backlog` to open it for detailed timeline planning. In this status, discussions about a fitting `Iteration` is held. |
There was a problem hiding this comment.
The fully refined status "backlog" is the entry point for our "open planning" ceremony.
During "open planning" a milestone is set for each feature. This represents a comittment, given by the open source community to finalize the feature in due time.
| As soon as actual work is started in the selected iteration, the issue is set to `Work in Progress`. This is especially helpful on our project milestone views to get an overview of the release progress. | ||
|
|
||
| The final status `Done` is set, as soon as all relevant implementations are done, tested and released. This has to be achieved for every change in every involved component. | ||
|
|
There was a problem hiding this comment.
add new section:
###Issue hierarchy
@stephanbcbauer to formulate details => detailled features are planned and executed within the repositories of the respective component. Summary features are planned and managed on "SIG release" level...
| # Product Release | ||
|
|
||
| Tractus-X products do follow their own release process. Please check the leading product repositories for details. | ||
| Independent of the technical details of product release processes, the released artifacts and minimum level of quality ensurance |
| Independent of the technical details of product release processes, the released artifacts and minimum level of quality ensurance | ||
| is the same across all of them. | ||
|
|
||
| The release contents for individual products are are planned in the [open refinement and planning](./open-refinement-and-planning.md) sessions. |
| is the same across all of them. | ||
|
|
||
| The release contents for individual products are are planned in the [open refinement and planning](./open-refinement-and-planning.md) sessions. | ||
| These sessions define the scope for all dataspace components, but therefore paint a clear picture of enhancements necessary for every single product. |
|
|
||
| The release contents for individual products are are planned in the [open refinement and planning](./open-refinement-and-planning.md) sessions. | ||
| These sessions define the scope for all dataspace components, but therefore paint a clear picture of enhancements necessary for every single product. | ||
| The product teams themselfes are then responsible to define fine-grained task breakdowns as suiting their own needs. |
| Once planning activities for a certain iteration are completed, the implementation phase is starting and product teams can coordinate, where necessary | ||
| through our [communication channels](https://eclipse-tractusx.github.io/docs/oss/getting-started#communication-channels). | ||
|
|
||
| Integration tests are performed by maintaining an umbrella Chart, that deploys all relevant dataspace components to spin up an artificial dataspace based on Tractus-X components. |
There was a problem hiding this comment.
is "Product Umbrella Chart" now the best term based on conversation below?
it would be separated from " Tractus-X Umbrella Chart", right?
| Integration tests are performed by maintaining an umbrella Chart, that deploys all relevant dataspace components to spin up an artificial dataspace based on Tractus-X components. | ||
| There is a dedicated repository [eclipse-tractusx/tractus-x-umbrella](https://github.com/eclipse-tractusx/tractus-x-umbrella), that is maintained collectively to reflect the latest product release versions. | ||
|
|
||
| Additional to the integration- and unit-test suites the teams maintain, every product also needs to adhere to the [Tractus-X release guidelines (TRGs)](https://eclipse-tractusx.github.io/docs/release). |
There was a problem hiding this comment.
Proposal for line 21: Every product needs to adhere...
Proposal to insert between 24 & 25: this is in addition to...
| > __HINT:__ | ||
| > Take special care about legal requirements defined in TRG 7. They __must__ be adhered to on every PR. | ||
|
|
||
| Product releases are done by creating a GitHub release. Every release is following the [semantic versioning](https://semver.org/) pattern and marked in the git history via tag. |
|
Please be aware that we created a new PR #662 |
Description
This PR is an initial effort to formally describe our release process.
Due to the nature of Tractus-X, the release process documentation is split in a "product-" and a "Tractus-X" release documentation.