Skip to main content

TRG 1.03 - CHANGELOG.md

StatusCreatedPost-History
Update22-Dec-2025add best practice GitHub release
Update11-Jan-2024add best practices and example changelog
Active20-Feb-2023reference keep a changelog as format
Draft14-Sept-2022n/a

Why​

Tracking changes in Open Source is critical to have a way of knowing which new features have been introduced, which bugs have been fixed, which security CVEs have been mitigated.

This helps people who are using the product, to understand which version to choose or when to upgrade.

Description​

All notable changes of a new release in the product repositories MUST be documented. There are two ways to document:

  • 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 MUST follow the format as described in Keep A Changelog.

In addition, a link to the change documentation MUST be added to the Eclipse Tractus-X Changelog.

The versioning of the product releases MUST follow semantic versioning.

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 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.
  • Use a workflow to automate the changelog creation (see example in sig-release with release please)

Example GitHub Release item​


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

## Screenshots
* Pictures from the running system and the features in this release.

## 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
  • use the "unreleased section" to track updates to features or functions of upcoming releases
  • same kinds of changes should be grouped (e.g. changed, fixed, removed, etc.) and each change should be linked to the corresponding issue or pull request

Example CHANGELOG.md​


All notable changes to this project will be documented in this file see also the overarching [`CHANGELOG.md`](https://eclipse-tractusx.github.io/changelog) for Tractus-X releases.

## [Unreleased]

- add API reference documentation (#issue, #pull-request)

## [v2.0.1](https://github.com/eclipse-tractusx/digital-product-pass/releases/tag/v2.0.1)  (your currently released semantic version)

### Added

- support for SSI (#issue, #pull-request)

### Changed

- bump Java version (#issue, #pull-request)

...

### Security

- fix security CVE <number> (#issue, #pull-request)

A full example can be found on Keep A Changelog.