Solve CHANGELOG.md merge conflicts

[wojciechczerniak]

Description

Changelog.md was a great improvement to our workflow. Making PR author responsible for describing the change it introduced for future Release Notes adheres to their quality, truthfulness, and integrity.

There is only one flaw to it, it's a single file, each developer, in each PR modifies, creating a "merge hell". Every single PR merged to develop branch automatically creates a conflict for all other PRs.

This document is an attempt to solve this problem.

Solution

TL;DR; We've discussed various approaches and the best solution is to make sure that the developers are working on different files.

Structure

We will create a hidden .changelog[s] directory that will keep an unversioned directory for our current develop work, and a directory for each version we release.

+ .changelogs
  + unversioned
  + v8.0.0
  + v8.1.0
  + v8.2.0
  + README.md

Code Freeze workflow will have to be extended by one step, to

Note: Add README.md, the file should explain the purpose and workflow for this directory. As quick documentation and a reminder for all contributors.

File names

Can be anything. As long as it's in the right directory and has the correct format, we're good. Although we want to propose a convention, should start with an issue number or a PR number. Since we work "issue first" we will have a quick reference to finding more details and it should sort nicely.

Should we add a short description? i.e. 7239-fix-copy-paste.yml

File format

YAML or JSON file.

---
title: "Change[log]s"
issue: 7239
type: added
framework: "Vue"

The fields title, type, and issue are mandatory. Issue or PR, for GitHub it does not matter that much. Field framework is optional if the changes should be marked for a particular wrapper.

Optional: We can add the author field to mark external contributions.

Release Date

Each release in a generated file should have a release date. The proposed structure does not answer where we should read those values. Another meta file? For each version or a single top-level one?

PR review

Idea is to add Ania as a Code Owner for .changelog/**/* directory. This way each PR will have to be approved by her before the merge and the develop branch will be always ready for a release, as it should be.

We should set up a repo so the code change won't dismiss this approval or should be done after the CR.

Automatic PR check

It will be possible to add an automatic check if the PR contains a new file in .changelog directory. It is also possible to verify if the added file has all the required fields. And framework or type field values are one of the supported ones.

Note: Sometimes we may need to make some changes and omit them in RN. We can introduce a commit message tag [ignore-changelog] to skip this check. We may also skip if changes are limited to /docs directory etc.

Creating CHANGELOG.md file

We need a script that will use template and changelogs from .changelogs directory that will compile final CHANGELOG.md for master branch and

Note: We want to make it quick, so we should only update the current CHANGELOG.md file with new version entries. Build should be incremental.

Updating CHANGELOG.md file

From time to time we have to update RNs, either we made a mistake or found an issue that was fixed by the older version and want to mark it correctly. In such a case, we may simply move the corresponding file (or create a new one) to the correct version directory and regenerate the whole CHANGELOG.md file.

Note: We need a command to regenerate the whole file.

Tooling

Should we have a script that will create an empty YAML file with the correct fields? We can go a lot further with this, maybe a generator for those files.

See https://docs.gitlab.com/ee/development/changelog.html for inspiration.

Caveats

It may not be possible to keep [Unversioned] live changelog in the main CHANGELOG.md file. That was a nice addition and an overview of our current progress. We could add GitHub Action to update it for us, but that may bring back the original problem.

Or we may just assume that the current progress overview can be found in .changelog/unversioned

CHANGELOG.md template

I like the idea of a note with a link to developer instructions.

Note: This file is automatically generated. Please see the developer 
documentation for instructions on adding your own entry.

Then we should follow our current format. Without ## [Unreleased] section.

# Handsontable changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

## [8.2.0] - 2020-11-12
Added
- Added new type of Index Map named LinkedPhysicalIndexToValueMap #7276
- Added an external dependency, DOMPurify, to add HTML sanitization what should minimize the risk of inserting insecure code using Handsontable built-in functionalities. #7292

Fixed
- Fixed an issue the container not being updated after trimming rows. #7241
- Fixed an issue with a htmlToGridSettings helper if passed <table> had no rows. #7311
- Fixed an issue where sorting indicator moved incorrectly when column was added. #6397
- Fixed a bug, where untrimming previously trimmed rows would sometimes result in the table instance not refreshing its height, leaving the row headers not properly rendered. #6276
- Fixes a bug, where tables' viewport was scrolled if a user opened editor when some columns on the left side of that cell were hidden. #7322
- Fix a problem when event.target's parent in the mouseover event was not defined, the table threw an error when hovering over row/column headers. #6926
- Fixed an issue, where calling the validation-triggering methods on a hiddenColumns-enabled Handsontable instance rendered the validated cells improperly. #7301
- Fixed an issue, where adding 0 rows to the table ended with doubled entries in indexMappers' collections. #7326
- Fix a problem with the inconsistent behavior of the Context Menu's "Clear column" disabled status. #7003
- Fix a bug with parsing multiline cells on pasting text/html mime-type. #7369

Other

A good developer guide should follow! For our Handbook

Proposed TOC:

• Short introduction
• Which changes should have a changelog entry
• How to write a good changelog entry
• Tools (if we will have one)
• Extended explanation why we've introduced this

Links

https://about.gitlab.com/blog/2018/07/03/solving-gitlabs-changelog-conflict-crisis/
https://docs.gitlab.com/ee/development/changelog.html
https://gitlab.com/gitlab-org/gitlab/blob/master/CHANGELOG.md
https://gitlab.com/gitlab-org/gitlab/-/tree/master/changelogs/unreleased

[mrpiotr-dev]

I ran through the description and have some questions and remarks:

1. What about custom descriptions on top of changelogs we had previously? https://github.com/handsontable/handsontable/releases/tag/8.0.0 or https://github.com/handsontable/handsontable/releases/tag/8.0.0-beta.2
   Did we resign to use them or maybe we'd like to add a custom type for them?

2. Maybe it would be good to define a complete list of possible types?
   Currently, we use:

   • Breaking changes
   • Added
   • Changed
   • Deprecated
   • Removed
   • Fixed

3. What about issues where we add only tests? Do we want to track these changes in the changelog or not?

4. Filenames

   Should we add a short description? i.e. 7239-fix-copy-paste.yml

   In my opinion, the issue's ID would be enough.

5. File format
   I think it would be good to define changelog-file schema. There we could define required and optional fields.

6. Release Date
   We modify hot.config.js file each time we prepare a release. There are release date and version.
   Maybe metadata file in each release-directory could contain additional description I mentioned in point 1) 🤔

7. Tooling
   With YAML files we need an additional dependency to parse this kind of files. Maybe JSON files would be enough (simple usage of the built-in JSON.parse)?

8. Caveats
   "unversioned" changes at the top of the changelog are something that end-developers looking for?

9. CHANGELOG.md template
   Would "framework" field have its separated indicator or category?****

[wojciechczerniak]

I ran through the description and have some questions and remarks:

1. What about custom descriptions on top of changelogs we had previously? https://github.com/handsontable/handsontable/releases/tag/8.0.0 or https://github.com/handsontable/handsontable/releases/tag/8.0.0-beta.2
   Did we resign to use them or maybe we'd like to add a custom type for them?

Changelog does not have them. Should it? I see changelog as a list of issues/tasks. Highlights are added to the Release Notes and Blog Posts.

2. Maybe it would be good to define a complete list of possible types?
   Currently, we use:

   • Breaking changes
   • Added
   • Changed
   • Deprecated
   • Removed
   • Fixed

Those are from the https://keepachangelog.com/en/1.0.0/ I would keep them. Unless you see something to add/change?

3. What about issues where we add only tests? Do we want to track these changes in the changelog or not?

I don't have an opinion on that.

4. Filenames

   Should we add a short description? i.e. 7239-fix-copy-paste.yml

   In my opinion, the issue's ID would be enough.

👍 Agree

5. File format
   I think it would be good to define changelog-file schema. There we could define required and optional fields.

👍

6. Release Date
   We modify hot.config.js file each time we prepare a release. There are release date and version.
   Maybe metadata file in each release-directory could contain additional description I mentioned in point 1) 🤔

Then we won't be able to regenerate the changelog later, hot.config.js have only the latest release date.

7. Tooling
   With YAML files we need an additional dependency to parse this kind of files. Maybe JSON files would be enough (simple usage of the built-in JSON.parse)?

True 👍

8. Caveats
   "unversioned" changes at the top of the changelog are something that end-developers looking for?

I'm using it to see what's coming in the next release. But I would say no.

9. CHANGELOG.md template
   Would "framework" field have its separated indicator or category?****

I was thinking about a prefix, maybe with an additional formatting. IMO categories mentioned above are enough and frameworks would have to follow the same scheme which would create a very long and confusing list in the end.

- **React**: Added ....

[rsify]

Closed in #7448