Proposal to improve GrimoireLab release notes

[sduenas]

Rationale

I think we should improve the release notes we generate in GrimoireLab. Right now they are not really useful for someone that wants to understand the latest features, changes or fixed bugs in the project. Release notes are only generated using the git log messages. That is unhelful for someone non-technical or not involved in the project.

A better idea would be to have release notes like in Perceval) for all the components. But the main problem is it requires some manually work. Looking for solutions I found interesting what GitLab project does.

For each merge requests (GitLab pull request) developers include a new file - one for each merge request - that contains basic information about the changes in the code. The information should explain the change to a reader who has zero context about the change. The file is a YAM file that looks like this:

---
title: Move add license button to project buttons
merge_request: 19370
author:
type: changed

These files are stored in a folder called unreleased. Once a new release is ready to be generated, the automated scripts read these files and create a changelog file. The folder will be cleaned for the new release. The generated file looks like this :

12.4.2
Fixed (10 changes)
    Increase timeout for FetchInternalRemote RPC call. !18908
    Clean up duplicate indexes on ci_trigger_requests. !19053
    Fix project imports not working with serialized data. !19124
    Fixed welcome screen icons not showing. !19148
    Disable protected path throttling by default. !19185
    Fix Prometheus duplicate metrics. !19327
    Fix ref switcher not working on Microsoft Edge. !19335
    Extend gRPC timeouts for Rake tasks. !19461
    Disable upload HTTP caching to fix case when object storage is enabled and proxy_download is disabled. !19494
    Removes arrow icons for old collapsible sections.

Changed (2 changes)
    Increased deactivation threshold to 180 days. !18902
    Add extra sentence about registry to AutoDevOps popup. !19092

Proposal

My proposal is to replicate the same workflow in GrimoireLab and in all its components. Each PR that matches all these cases will have to include a file explaining the changes. When a new component is released, a new changelog entry will be generated using the contents of all these files . For GrimoireLab releases the changelog will contain an aggregated version of those new entries.

My proposal includes the creation of the needed tools (because GitLab ones are very specific) for developing and releasing following this workflow.

References

Brainstorming to fix the Changelog problem Documentation of the workflow GitLab CHANGELOG Release tools in GitLab/changelog

[GeorgLink]

+1 to better release notes.

I'll leave the technical details to others. The GitLab guidelines for good change log entries is great.

[canasdiaz]

@sduenas how does the script distinguish between new features and fixes?

[sduenas]

@sduenas how does the script distinguish between new features and fixes?

Each entry stores the category of the change. See https://docs.gitlab.com/ee/development/changelog.html#how-to-generate-a-changelog-entry.

[canasdiaz]

I understand then that PRs with more than 1 commit will be welcome then. Am I right? I mean, if they are related, several commits can be published in the same PRs with a single YAML file with the description. Is this right?

[sduenas]

I understand then that PRs with more than 1 commit will be welcome then. Am I right? I mean, if they are related, several commits can be published in the same PRs with a single YAML file with the description. Is this right?

Yes, that's the idea.

[canasdiaz]

LGTM. :+1:

[valeriocos]

LGTM!

[jgbarah]

I like the idea very much!

[sduenas]

I created a new repository in Bitergia where I'm going to create these tools: https://github.com/Bitergia/release-tools. Not sure if makes sense to move this repository to CHAOSS/GrimoireLab now or if we should wait until this is more stable.

I created a new PR with a script to help developers to create the entries mentioned above: https://github.com/Bitergia/release-tools/pull/1

[jgbarah]

I think it makes sense to have it in chaoss, so it is more apparent to any contributor. Maybe this repo is the right one for it, under /utils.

[sduenas]

After some months working on this, I created today the release 0.2.0 of my proposal for the release tools. I think we can move the repository to grimoirelab and start with a pilot so we can evaluate if this is useful or not.

https://github.com/Bitergia/release-tools/

The release of the tools was generated with theshelves.

https://github.com/Bitergia/release-tools/releases

I suggest we can start using it in Perceval and ELK. My idea is to generate their release notes with these tools as I explained in this proposal.

What do you think?

[GeorgLink]

Release notes look good and are understandable.

[sduenas]

This was already done. Release notes are now created with every release.