From 1e06f43b1d473993f5342445c880a02875b6f03d Mon Sep 17 00:00:00 2001 From: Sebastian Bezold Date: Fri, 3 May 2024 09:22:55 +0200 Subject: [PATCH 1/9] docs(trg): improve section hints in template --- docs/release/trg-0/trg-0-template.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/release/trg-0/trg-0-template.md b/docs/release/trg-0/trg-0-template.md index 5c49e903f58..578f72bf970 100644 --- a/docs/release/trg-0/trg-0-template.md +++ b/docs/release/trg-0/trg-0-template.md @@ -16,8 +16,15 @@ Proposed release date: "mandatory after": 19th of May 2023 ## Why -Describe in this section why the TRG exist. For example because it's a legal requirement or it makes it much easier for others to use or it's an industry standard. +Provide reasoning behind the release guideline. Why does Eclipse Tractus-X align on this quality criteria. +The reasons can range from legal requirements to industry standards or simple alignments, that we did as Tractus-X project. ## Description -Describe the TRG on how to do the TRG. Provide a golden path: In best case with code example or/and step by step guide. +Provide guidance on how to comply with the release guideline. If there is configuration or workflows, that could be used +as golden path, consider adding it to the TRG description, or link to proper documentation. +In best case, anyone, who is working on compliance with your TRG can follow a step-by-step guide. + +## Best Practices and Examples + +Consider providing best practices, that are related to your TRG, even though it is not necessarily needed for compliance. From da8438e66180d23e9d458d19257b0d3b87400cd6 Mon Sep 17 00:00:00 2001 From: Sebastian Bezold Date: Fri, 3 May 2024 10:24:57 +0200 Subject: [PATCH 2/9] docs(trg): update TRG process with committer meeting feedback --- docs/release.md | 78 ++++++++++++++++++++++++------------- docs/release/trg-0/trg-0.md | 6 +++ 2 files changed, 56 insertions(+), 28 deletions(-) diff --git a/docs/release.md b/docs/release.md index 2d3b8f7a32c..6f46e02d919 100644 --- a/docs/release.md +++ b/docs/release.md @@ -1,43 +1,65 @@ # Release Guidelines -## Introduction +Welcome to Eclipse Tractus-X Release Guidelines, known as TRGs. With Release Guidelines, we are defining quality +criteria for our repositories, products and artifacts in general. TRGs are numbered and grouped into sections, to +provide an easy-to-use overview. The git history of the TRGs can be use to browse changes made throughout the project +history. You can also conduct the [TRG Changelog](release/trg-0) to see when new TRGs have been added. -Welcome to Tractus-X Release Guidelines, known as TRGs. TRG numbers are assigned by the TRG -editors, and once assigned never changed. The version control history of the TRG texts represent their historical -record. The TRGs are indexed by topic for specialist subjects. +## Process -You find the overarching Changelog [here](release/trg-0) to see when new TRGs have been added. +The process of introducing or altering a TRG is straight-forward. It consists of the following phases and events: -## Process +1. A proposal is created. +2. The proposal is improved by providing feedback +3. The committer group is deciding to accept or deny the proposed changes + +More details in the following sections + +### Proposal + +A new TRG, or a change to an existing one is proposed by raising a PR. This can be done by any contributor or committer. +The PR is raised against the `main` branch +of [eclipse-tractusx/eclipse-tractusx.github.io](https://github.com/eclipse-tractusx/eclipse-tractusx.github.io/). +Changes can be done by directly updating the existing Markdown files. New TRGs should already be put to a matching +section. In case a new TRG does not fit do an existing section, a new section can be proposed or asked for by reviewers. + +As soon as a proposal is ready for committer review, it has to be announced +via [Tractus-X mailing list](https://accounts.eclipse.org/mailing-list/tractusx-dev). Additionally, the committer group +is mentioned directly on the PR by tagging `@automotive-tractusx-committers`. + +### Review -This TRG process is open for all and has the main goal of providing reasonable defaults for workflows and requirements on being able to easily contribute, maintain and run products/components across Eclipse Tractus-X. +Feedback to announced proposals is welcome by everybody. It should be provided by using the review functionality of +GitHub. Reviews are especially needed from Tractus-X committers, since they are the ones who are accepting or dropping +proposals. -### Create new draft +During review, the following things could be paid special attention to: -- Create a draft version under release/trg-0 - - Reserve the TRG number already -- Create a pull request for merging the draft version (IF it helps to visualize / present the draft on the website) and get an approval -- Announce the new Draft TRG on developer mailinglist +- Does the TRG focus on a single topic? If not, consider splitting to multiple TRGs +- Is it clear, how to comply with the TRG, or is there a lot of room for interpretation? +- Would it be a lot of effort to comply with the TRG. Consider introducing a "mandatory from" date. -#### Release fast or slow +### Accept / Drop -If you now have a small change, like a typo or updating description you do a fast release. If you create a new and big TRG (which takes time to do) you do a slow release. +A new TRG, or changes to an existing TRG are __accepted__, if all the following is true: -- **Fast** - - Create new Pull Request for moving the draft version to its final location - - Address all issues in the PR and merge - - Announce the new TRG on the developer mailinglist -- **Slow** - - Create new Pull Request for moving the draft version as a PRERELEASE version in its final location - - Add a hint on when the TRG becomes mandatory - - Address all issues in the PR and merge - - Announce the new TRG on the developer mailinglist - - When the TRG mandatory date is due, remove the hint and move it from PRERELEASE to normal (as all other TRGs) +- at least 7 committers did approve the change +- the proposal PR is open for at least 2 weeks, to give everyone a fair amount of time to provide feedback or request + changes +- All requested changes are addressed. Not necessarily every requested change has to be implemented, if there is a + consensus in the committer round, that the original proposal is good enough. -### Update existing TRG +If the mentioned criteria is met, the PR is merged and the release guideline is mandatory for all Tractus-X products and +repositories. There might be cases, where complying with a new or changed release guideline takes considerable effort, +so that proper planning should be done. In these cases, a "mandatory from" date should be discussed in the review phase +and the actual date highlighted at the beginning of the TRG. -The critical difference is that you do the same thing with slow and fast release of new draft but instead of creating a new draft, you copy and paste the existing TRG (the TRG to change) into the draft folder. +A release guideline proposal is __dropped__, if there are too many changes requested and a consensus cannot be found +across the committer group on how to alter the proposal to an acceptable state. Dropped, or rejected release guideline +proposals are documented by listing the PR and a short description of the proposed change +in [Changelog & Drafts](release/trg-0/trg-0.md). -### Deprecated existing TRG +### Deprecating TRGs -Create a new PR which already deprecates the TRG without a draft state. Deprecation means updating the post history and marking as much as possible with strikethrough markdown. +Proposals to deprecate existing TRGs are also introduced via PR. To keep the list of TRGs small and easy to read, +deprecating TRGs is done by simply deleting it and mention the deleting in [Changelog & Drafts](release/trg-0/trg-0.md). diff --git a/docs/release/trg-0/trg-0.md b/docs/release/trg-0/trg-0.md index ef839df465f..f86b6a87460 100644 --- a/docs/release/trg-0/trg-0.md +++ b/docs/release/trg-0/trg-0.md @@ -23,6 +23,12 @@ title: TRG 0 - Changelog & Drafts | 23-Feb-2023 | Add draft "Helm Action" | | 13-Sept-2022 | Initial contribution | +## Dropped / Rejected Release Guideline proposals + +| PR | Proposal description | +|-----|----------------------| +| | | + ## Index by Category ```mdx-code-block From 7d6ff6da7be814a0d723389b4531267d675ce54b Mon Sep 17 00:00:00 2001 From: Sebastian Bezold Date: Mon, 6 May 2024 09:03:15 +0200 Subject: [PATCH 3/9] docs(trg): add reason for dropping column in history --- docs/release/trg-0/trg-0.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/release/trg-0/trg-0.md b/docs/release/trg-0/trg-0.md index f86b6a87460..1b836100d8a 100644 --- a/docs/release/trg-0/trg-0.md +++ b/docs/release/trg-0/trg-0.md @@ -25,9 +25,9 @@ title: TRG 0 - Changelog & Drafts ## Dropped / Rejected Release Guideline proposals -| PR | Proposal description | -|-----|----------------------| -| | | +| PR | Proposal description | Reason for dropping | +|-----|----------------------|---------------------| +| | | | ## Index by Category From 46c3bea55e19dc1f4dabb2012c7042bdd493f428 Mon Sep 17 00:00:00 2001 From: Sebastian Bezold Date: Mon, 6 May 2024 09:10:08 +0200 Subject: [PATCH 4/9] docs(trg): improve wording of why section in TRG template --- docs/release/trg-0/trg-0-template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/release/trg-0/trg-0-template.md b/docs/release/trg-0/trg-0-template.md index 578f72bf970..ebe81ff7b03 100644 --- a/docs/release/trg-0/trg-0-template.md +++ b/docs/release/trg-0/trg-0-template.md @@ -16,7 +16,7 @@ Proposed release date: "mandatory after": 19th of May 2023 ## Why -Provide reasoning behind the release guideline. Why does Eclipse Tractus-X align on this quality criteria. +This section must provide insights and reason behind the release guideline and a description why Eclipse Tractus-X has to align on this quality criteria. The reasons can range from legal requirements to industry standards or simple alignments, that we did as Tractus-X project. ## Description From 59be4dd8067a7776c42a55f2d8555b6008219490 Mon Sep 17 00:00:00 2001 From: Sebastian Bezold Date: Mon, 6 May 2024 09:37:29 +0200 Subject: [PATCH 5/9] docs(trg): fix mention tag of committer group --- docs/release.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/release.md b/docs/release.md index 6f46e02d919..fc128468376 100644 --- a/docs/release.md +++ b/docs/release.md @@ -25,7 +25,7 @@ section. In case a new TRG does not fit do an existing section, a new section ca As soon as a proposal is ready for committer review, it has to be announced via [Tractus-X mailing list](https://accounts.eclipse.org/mailing-list/tractusx-dev). Additionally, the committer group -is mentioned directly on the PR by tagging `@automotive-tractusx-committers`. +is mentioned directly on the PR by tagging `@eclipse-tractusx/automotive-tractusx-committers`. ### Review From c21e5c88f059418e7dd7cfa3fcedcc4fbfc79514 Mon Sep 17 00:00:00 2001 From: Sebastian Bezold Date: Wed, 8 May 2024 08:56:59 +0200 Subject: [PATCH 6/9] docs(trg): fix punctuation in release description --- docs/release.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/release.md b/docs/release.md index fc128468376..3406a8837c2 100644 --- a/docs/release.md +++ b/docs/release.md @@ -35,9 +35,9 @@ proposals. During review, the following things could be paid special attention to: -- Does the TRG focus on a single topic? If not, consider splitting to multiple TRGs -- Is it clear, how to comply with the TRG, or is there a lot of room for interpretation? -- Would it be a lot of effort to comply with the TRG. Consider introducing a "mandatory from" date. +- Does the TRG focus on a single topic? If not, consider splitting to multiple TRGs. +- Is it clear, how to comply with the TRG? Avoid room for interpretation, where possible. +- Would it be a lot of effort to comply with the TRG? Consider introducing a "mandatory from" date. ### Accept / Drop From 7632dba036160282c9455be557dc103ef7019e79 Mon Sep 17 00:00:00 2001 From: Sebastian Bezold Date: Wed, 8 May 2024 09:04:33 +0200 Subject: [PATCH 7/9] docs(trg): rephrase release guideline intro --- docs/release.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/release.md b/docs/release.md index 3406a8837c2..bc689f216b5 100644 --- a/docs/release.md +++ b/docs/release.md @@ -3,7 +3,8 @@ Welcome to Eclipse Tractus-X Release Guidelines, known as TRGs. With Release Guidelines, we are defining quality criteria for our repositories, products and artifacts in general. TRGs are numbered and grouped into sections, to provide an easy-to-use overview. The git history of the TRGs can be use to browse changes made throughout the project -history. You can also conduct the [TRG Changelog](release/trg-0) to see when new TRGs have been added. +history. You can also check the [TRG Changelog](release/trg-0) to get a better view on the history of +new/changed/deprecated TRGs. ## Process From e3846b3d7de63e648243da845c6de3eb67934f3d Mon Sep 17 00:00:00 2001 From: Sebastian Bezold Date: Wed, 8 May 2024 09:06:16 +0200 Subject: [PATCH 8/9] docs(trg): fix typo Co-authored-by: Tomasz Barwicki --- docs/release.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/release.md b/docs/release.md index bc689f216b5..d33c4ba6746 100644 --- a/docs/release.md +++ b/docs/release.md @@ -2,7 +2,7 @@ Welcome to Eclipse Tractus-X Release Guidelines, known as TRGs. With Release Guidelines, we are defining quality criteria for our repositories, products and artifacts in general. TRGs are numbered and grouped into sections, to -provide an easy-to-use overview. The git history of the TRGs can be use to browse changes made throughout the project +provide an easy-to-use overview. The git history of the TRGs can be used to browse changes made throughout the project history. You can also check the [TRG Changelog](release/trg-0) to get a better view on the history of new/changed/deprecated TRGs. From d5fcef5b284b43a5902d914586024321cfe2fe4d Mon Sep 17 00:00:00 2001 From: Sebastian Bezold Date: Wed, 8 May 2024 15:53:00 +0200 Subject: [PATCH 9/9] docs(trg): remove dots from bullet points --- docs/release.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/release.md b/docs/release.md index d33c4ba6746..238d786b8f4 100644 --- a/docs/release.md +++ b/docs/release.md @@ -10,7 +10,7 @@ new/changed/deprecated TRGs. The process of introducing or altering a TRG is straight-forward. It consists of the following phases and events: -1. A proposal is created. +1. A proposal is created 2. The proposal is improved by providing feedback 3. The committer group is deciding to accept or deny the proposed changes @@ -36,9 +36,9 @@ proposals. During review, the following things could be paid special attention to: -- Does the TRG focus on a single topic? If not, consider splitting to multiple TRGs. -- Is it clear, how to comply with the TRG? Avoid room for interpretation, where possible. -- Would it be a lot of effort to comply with the TRG? Consider introducing a "mandatory from" date. +- Does the TRG focus on a single topic? If not, consider splitting to multiple TRGs +- Is it clear, how to comply with the TRG? Avoid room for interpretation, where possible +- Would it be a lot of effort to comply with the TRG? Consider introducing a "mandatory from" date ### Accept / Drop