3

We record our release notes during development in an .md document. This document contains explanations on features, migration notes and more. When merging feature branches, we often have the problem that conflicts arise within this file, even though usually only content is added.
In particular, it is very annoying that after each completed mergerequest, the already running mergerequests can no longer be merged automatically, since conflicts now occur again in the release notes.

We have considered different solution options. However, we would like to avoid either outsourcing the release notes to a separate repo or creating a separate file for each feature, which then has to be merged at release.

Since we are certainly not the only ones who have this problem, we hope that we can get some valuable tips on how to avoid manual merging of the release notes.

I made a sketch of the problem. Green changes can be merged automatically, while red changes need human attention. Our problem: We need to merge master into every other featurebranch just because of the relesenotes.

Edit in response to the comment by Lasse Vågsæther Karlsen:

In fact, our release notes do look like this:

# Release 5.23.23

## Highlights

### Feature0
A simple explaination in few words targeting non-tec-reader
### Feature1
Another simple explaination in few words targeting non-tec-reader

## New Features
### Feature0
A more detailed explaination targeting other developers. We explain how to use the feature with a small snippet.
### Feature1
Another more detailed explaination targeting other developers. We explain how to use the feature with a small snippet.

## API Changes
### Deprecation of Method `Service#foo`
Feature0 intoduces a better API. `Service#foo` is deprecated as of now and will be removed in a future version
### New Method `QualityService#bar`
This Method replaces `Service#foo` and is way better because of some reason.

As you can see, each feature is mentioned in multiple sections. We already thought about building our own tooling to merge multiple well-formatted files into one document during release - but before putting any effort into this we wanted to be sure there is no better solution.

samjaf
  • 1,033
  • 1
  • 9
  • 19
  • Actually, it is more common that people find a way to split up files that *everybody has to edit all the time* or find a completely different solution to this. Why can't this file be built using your project management tool instead? – Lasse V. Karlsen Nov 05 '18 at 07:27
  • 2
    Or have you considered just letting everybody write their release notes into separate files, and then use a small tool/script to concatenate them into one big file for release? – Lasse V. Karlsen Nov 05 '18 at 07:39
  • Usually answer is a custom merge driver, but I'm not sure how to make it work at a github/gitlab/bitbucket server – max630 Nov 05 '18 at 14:52

1 Answers1

1

An alternative way to generate a changelog can be seen in the Git repository itself

Each feature branch has a merge commit (like this one) describing what the feature branch is about.

The release note is then automatically updated on the master branch (like this example)

That avoid having a common file updated on multiple branches, with complex merge to manage.

VonC
  • 1,262,500
  • 529
  • 4,410
  • 5,250