Skip to content

Adopt TRG 1-03 and 2-03 concerning already in use practices to fulfill the intention #1414

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

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

Adopt TRG 1-03 and 2-03 concerning already in use practices to fulfill the intention #1414

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
16cf7ec
Adapt TRG 1-03 to support also GitHub release mechanism for change docu
lgblaumeiser Dec 22, 2025
9e1cdf6
Adapt TRG 2-03 to prevent inconsistent redundancies to TRG 7-01
lgblaumeiser Dec 22, 2025
89aa8a4
Improve formulation in TRG 1-03 concerning overall release notes
lgblaumeiser Dec 22, 2025
818c44f
Small formatting imprvement
lgblaumeiser Jan 6, 2026
52726e9
Apply suggestions from code review
lgblaumeiser Jan 6, 2026
dc684fc
Enhance documentation on release change logging
lgblaumeiser Jan 6, 2026
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
63 changes: 58 additions & 5 deletions docs/release/trg-1/trg-1-03.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ title: TRG 1.03 - CHANGELOG.md

| Status | Created | Post-History |
|--------|--------------|------------------------------------------|
| Update | 22-Dec-2025 | add best practice GitHub release |
| Update | 11-Jan-2024 | add best practices and example changelog |
| Active | 20-Feb-2023 | reference keep a changelog as format |
| Draft | 14-Sept-2022 | n/a |
Expand All @@ -16,14 +17,66 @@ This helps people who are using the product, to understand which version to choo

## Description

All notable changes in the product repositories **have to** be added to a `CHANGELOG.md` file.
Also, a link to the [Eclipse Tractus-X Changelog](https://github.com/eclipse-tractusx/tractus-x-release/blob/main/CHANGELOG.md) **has to** be added there.
All notable changes of a new release in the product repositories **MUST** be documented. There are two ways to document:

The versioning of the product releases **has to** follow [semantic versioning](https://semver.org/).
- Recommended: Use the GitHub release notes mechanism to document changes in the Release item in GitHub.
Be aware, that this mechanism uses the title lines of PRs merged in the release period, so this requires some discipline in this regard.
It is possible, to adapt the generated text to get rid of PR issues and to generally improve user experience.
- Alternative: Document all releases with their changes in a `CHANGELOG.md` file at the root level in the repository.
A `CHANGELOG.md` file **SHOULD** follow the format as described in [Keep A Changelog](https://keepachangelog.com/en/1.1.0/).

The product `CHANGELOG.md` file **should** follow the format as described in [Keep A Changelog](https://keepachangelog.com/en/1.1.0/).
In addition, a link to the change documentation **MUST** be added to the [Eclipse Tractus-X Changelog](https://github.com/eclipse-tractusx/tractus-x-release/blob/main/CHANGELOG.md).

## Best Practices and Example
The versioning of the product releases **MUST** follow [semantic versioning](https://semver.org/).

## Best Practices and Example for GitHub Release item

- As the release notes mechanism basically gathers merged pull requests in the relevant period, some hygienic activities support the automation process.
- Separate the changes into adequate categories (e.g., features, bugfixes, documentation, infrastructure, dependencies).
- Use [conventional commits](https://www.conventionalcommits.org) to support the release notes mechanism in doing a pre-sorting of changes into categories.
- Cleanup the list to provide a better user experience to adoptors of the version.

### Example GitHub Release item

```markdown

## What's Changed

### Main Features
<!-- Manually generated list of main features added -->

| Feature | Note | Documentation |
|----------------------------------|--------------------------------|-------------------------------|
| Link to feature issue | Short summary of the feature | Link to feature documentation |
| [Title of the issue](issue link) | Integration of DSP Version ... | [Migration Guide](docu link) |

### Breaking changes
* feat(constraint): add validation for framework constraint by `a contributor` in `link to pr`
* Any other PR that requires an adoptor to check its current software for compatibility

### Bugfixes
* fix: ProxyHttp datasource response header with single Content-Type by `a contributor` in `link to pr`
* Any other PR that qualifies as a bugfix

### New Features & Improvements
* feat: non finite provider push by `a contributor` in `link to pr`
* Any other PR that qualifies as new functionality provided

### Documentation
* docs: non-finite-provider-push in management api walkthrough by `a contributor` in `link to pr`
* Any other PR that qualifies as an improvement of documentation

### Other Changes
* chore: Update k8s versions for deployment test by `a contributor` in `link to pr`
* Any other PR that does not qualify to any of the above categories, e.g., infrastructure topics or config changes

## New Contributors
* A list of people who did their first contribution in the corresponding release cycle

**Full Changelog**: https://github.com/eclipse-tractusx/some-repo/compare/1.0.0...1.1.0
```

## Best Practices and Example for `CHANGELOG.md`

- latest released version should be on top
- each released version should have a separate block entry and each version should be linked to the corresponding tag
Expand Down
32 changes: 8 additions & 24 deletions docs/release/trg-2/trg-2-03.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ title: TRG 2.03 - Repo structure

| Status | Created | Post-History |
|--------|-------------|-----------------------------------------------|
| Update | 22-Dec-2025 | Remove redundancy to TRG 7-01 |
| Active | 06-Dec-2023 | reword Why section + highlight optional files |
| | 25-Nov-2022 | adjustments to DEPENDENCY, LICENSE, NOTICE |
| | 24-Nov-2022 | add FOSS/Eclipse related basic files |
Expand All @@ -15,57 +16,40 @@ In order to foster consistency, collaboration and ease of navigation, adhereing

## Description

All repositories **must** contain the following files and folders:
All repositories **MUST** contain the following files and folders:

```shell
/docs
/charts
CODE_OF_CONDUCT.md
CONTRIBUTING.md
DEPENDENCIES
LICENSE
NOTICE.md
Comment on lines -23 to -27
Copy link
Member

@stephanbcbauer stephanbcbauer Jan 6, 2026

Choose a reason for hiding this comment

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

Did we decide that these files are NOT a must? Do we have, somewhere else documented, what kind of structure we expect? Just thinking loud, because we also check these files in the automatic release checks https://eclipse-tractusx.github.io/sig-release/

Copy link
Contributor Author

@lgblaumeiser lgblaumeiser Jan 6, 2026

Choose a reason for hiding this comment

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

You find that in the description of the PR, the point is, that these files are mentioned with a reason in TRG 7.01, there was already a mismatch between the two TRGs, so my proposal is, to get rid of the redundancy and require these files in the TRG that motivates them.

Copy link
Member

@stephanbcbauer stephanbcbauer Jan 6, 2026

Choose a reason for hiding this comment

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

thx. Wer lesen kann ist klar im Vorteil :)

README.md
SECURITY.md
```

All repositories **MUST** contain files required due to legal needs as defined in [TRG 7.01](../trg-7/trg-7-01)

Recommended but optional:

```shell
AUTHORS.md
INSTALL.md
```

### Directories

#### /docs

The `/docs` directory **must** contain detailed product related documentation for the Tractus-X product. Folder structure
The `/docs` directory **MUST** contain detailed product related documentation for the Tractus-X product. Folder structure
inside this directory is the responsibility of the repository owner/product team.

#### /charts

The `/charts` directory **must** contain the Helm chart for the Tractus-X product IF available. For more information about Helm
The `/charts` directory **MUST** contain the Helm chart for the Tractus-X product IF available. For more information about Helm
Chart structure, refer to [TRG 5.01 - Helm Chart requirements](../trg-5/trg-5-01).

### Files

#### README.md

Your repository **must** contain a `README.md` file. See [TRG 1.01 - README.md](../trg-1/trg-1-01).
Your repository **MUST** contain a `README.md` file. See [TRG 1.01 - README.md](../trg-1/trg-1-01).

#### INSTALL.md

Your repository **should** contain a `INSTALL.md` file. See[TRG 1.02 - INSTALL.md](../trg-1/trg-1-02).

#### Legal documentation

For the following files, see [TRG 7.01](../trg-7/trg-7-01)

- AUTHORS.md (optional)
- CODE_OF_CONDUCT.md
- CONTRIBUTING.md
- DEPENDENCIES
- LICENSE
- NOTICE.md
- SECURITY.md
Your repository **SHOULD** contain a `INSTALL.md` file. See [TRG 1.02 - INSTALL.md](../trg-1/trg-1-02).