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

Update TRG proposal and approval process #871

Open
wants to merge 9 commits into
base: main
Choose a base branch
from
Open

Update TRG proposal and approval process #871

Show file tree
Hide file tree
Changes from 8 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
1e06f43
docs(trg): improve section hints in template
SebastianBezold May 3, 2024
da8438e
docs(trg): update TRG process with committer meeting feedback
SebastianBezold May 3, 2024
7d6ff6d
docs(trg): add reason for dropping column in history
SebastianBezold May 6, 2024
46c3bea
docs(trg): improve wording of why section in TRG template
SebastianBezold May 6, 2024
59be4dd
docs(trg): fix mention tag of committer group
SebastianBezold May 6, 2024
c21e5c8
docs(trg): fix punctuation in release description
SebastianBezold May 8, 2024
7632dba
docs(trg): rephrase release guideline intro
SebastianBezold May 8, 2024
e3846b3
docs(trg): fix typo
SebastianBezold May 8, 2024
d5fcef5
docs(trg): remove dots from bullet points
SebastianBezold May 8, 2024
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
79 changes: 51 additions & 28 deletions docs/release.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,43 +1,66 @@
# 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 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.

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.
SebastianBezold marked this conversation as resolved.
Show resolved Hide resolved
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.
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
section. In case a new TRG does not fit do an existing section, a new section can be proposed or asked for by reviewers.
section. In case a new TRG does not fit into 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 `@eclipse-tractusx/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? Avoid room for interpretation, where possible.
- 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
Copy link
Contributor

Choose a reason for hiding this comment

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

The case which interests me is when the TRG PR doesn't get much attention from committers and doesn't get enouch approvals within 2 weeks, as per listed requirements does that get dropped? I think it might be a useful to keep traction, reminder of open TRG PRs in the Committers meeting.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Yes that is definitely an interesting case and unfortunately the most common one, at least on the recent TRGs.
I was not yet sure, how to state that in our process.
You could say, that dropping is actually the right thing to do, since there does not seem to be a lot of interest across the committer group to align on such a topic.
We could also think about "reminders", that it is a committer duty to vote on project rules, just like it is for committer elections. Just not sure, what we should do, if colleagues are constantly skipping the vote.

Copy link
Contributor

Choose a reason for hiding this comment

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

As shortly discussed in our sync today:

I think it should be feasable for the project leads to still allow a TRG if there is no Veto. It should also be later on the responsible of the project lead to inform/warn committers that they have a duty and remove them later on if they don't react/act on TRGs or other things in the community.

Nonetheless if there is no real veto a TRG with small activty should be allowed as there are often enough approaches which need to be aligned

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I would like to hear more opinions on that. From my point of view, the rules are still made and discussed by the committer group. Low activity should result in a reminder to the committer group of their duties instead of "just waving through" as PL.
Taking this to the committer office hour

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
Copy link
Contributor

Choose a reason for hiding this comment

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

Actually I'd simplify that step and put "mandatory from" for each new TRG with a default period (1 month?) , that would save time for discussing what "considerable effort" means in specific proposed implementation, and allow time incorporating into development planning. Also would be a kind of highlight that it's something new..

Copy link
Contributor

Choose a reason for hiding this comment

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

I don't agree with a default period of 1 month. In such cases, it needs to be possible to plan and prioritize the implementation of the TRG in the next open planning (open plannings occur 4 time/year). If a product increment is already planned out, it's simply not possible to take up such additional effort. Therefore, the TRG needs to be brought to the next open planning, to be implemented then in the next product increment.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Hi @evegufy and @tomaszbarwicki!
Given both your feedback, I'm not sure if the changes I made are good enough, or if we should elaborate on that. There is also a short bullet point with a guiding question in the "Review" section, that is already mentioning the "mandatory from" date

Would it be a lot of effort to comply with the TRG? Consider introducing a "mandatory from" date.

Copy link
Contributor

@evegufy evegufy May 8, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

Hi @SebastianBezold I think if it remains at it's currently is written, it's fine.

Copy link
Contributor

Choose a reason for hiding this comment

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

@evegufy my proposal was to set a default period for each new TRG, 1 month was just example, can be 3 months as well if that helps with open planning schedule. The point was to cut sometimes unneccessary long lasting discussions on the complexity.

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).
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
deprecating TRGs is done by simply deleting it and mention the deleting in [Changelog & Drafts](release/trg-0/trg-0.md).
deprecating TRGs is done by simply deleting them and mentioning the deletion in [Changelog & Drafts](release/trg-0/trg-0.md).

11 changes: 9 additions & 2 deletions docs/release/trg-0/trg-0-template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
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

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.
6 changes: 6 additions & 0 deletions docs/release/trg-0/trg-0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
FaGru3n marked this conversation as resolved.
Show resolved Hide resolved

| PR | Proposal description | Reason for dropping |
|-----|----------------------|---------------------|
| | | |

## Index by Category

```mdx-code-block
Expand Down
Loading