Add CHANGELOG.md to repository

[Korablev77]

Now workflow with changelog is following:

1. Author of patch is responsible for providing changelog entry while one is preparing patch. It is attached to patch-set (in covering letter) when it is sent to the mailing list.
2. When commiter pushes patch to the master and other release branches, one should manually find that changelog entry in mailing list and copy it to corresponding release pages on github.
   This method has following drawbacks:

• Collaborators often forget to attach changelog to the covering letter;
• Commiters have to find through mailing list corresponding changelog;
• Commiters have to copy changelog entry to several release pages;
• Changelog from last releases is lost;
• It is easy for commiter to forget to update one (or all) of release pages.
  The only drawback of using CHANGELOG.md is possible merge conflicts while backporting patch to older versions. However, taking into account append-only structure of CHANGELOG.md it shouldn't be really a problem.

[Korablev77]

@kyukhin Waiting for your approve, patch is on mailing list.

[Totktonada]

I wrote the proposal as part of our internal developers guideline (SOP), but it seems it worth to share it here too.

---

Changelogs (proposal)

Usual process

Let's consider the example: a patchset contains several internal changes (some refactoring) and one user visible change (bugfix, new feature, behaviour change, new supported OS and so on). The commit that contains the user visible change should add a file of this kind:

$ cat changelogs/unreleased/bitset-index-varbinary.md
## bugfix/core

* Bitset index now supports the varbinary type (gh-5392).

The first part of the header is bugfix or feature (let's consider any use visible change that is not a bugfix as a feature). In an exceptional case a new type may be added (however now it is explicitly forbidden by the release notes generation script).

The second part may be core, memtx, vinyl, replication, swim, raft, luajit, lua, sql, build, misc and so on. Please, prefer one of those categories, but if a change does not fit into them and more changes of this kind are expected, feel free to add a new one.

Add a subcategory

## feature/lua/http client

Detailed description

You may use full power of the GitHub Flavored Markdown syntax, but, please, keep the source readable for humans.

Example of a detailed description:

$ cat changelogs/unreleased/upstream-uri-password.md
## bugfix/replication

* Use empty password when a URI in `box.cfg{replication = <...>}` is like
  `login@host:port`. gh-4605. The behaviour matches the net.box's one now.
  Explicit `login:@host:port` was necessary before, otherwise a replica
  displayed the following error:

  > Missing mandatory field 'tuple' in request

Leave a note to a release manager

A valuable feature or a deliberate compatibility breakage may require an extra notice for a maintainer who will squash changelog entries into a a changelog file. Let's look on examples:

$ cat changelogs/unreleased/stored-decimals.md
## feature/core

* Decimals can now be stored in spaces. The corresponding field type is
  introduced: `decimal`. Decimal values are also allowed in the `scalar`,
  `any`, and `number` fields. Decimal values can be indexed. gh-4333

  <..details here..>

----

Notable change: stored and indexed decimals (and new 'decimal' field type).

$ cat changelogs/unreleased/session-settings.md
## feature/sql

* **[Breaking change]** Introduce _session_settings service space as replacement
  for PRAGMA keyword. gh-4511

  <..details here..>

----

Breaking change: sql: PRAGMA keyword is replaced with _session_settings system
space.

Generate changelog file

This section is for a release manager. We should prepare a changelog file for a release before the release will be tagged.

Let's do the following steps:

1. $ ./tools/gen-release-notes > changelogs/2.7.1.md.
2. Edit the resulting file. Comments to a release manager will be placed at start: usually they direct the release manager to list some changes in Overview or Compatibility section.
3. $ rm changelogs/unreleased/*.md
4. Send the changes for review (if necessary) and commit them.
5. Repeat the same for all branches to be released.

Reasoning

We want to provide description of changes that a release offers for our users. Not just git log output or a list of closed issues, but a document that is readable and useful for developers, who use tarantool in projects. The idea is just the same as described on the Keep a Changelog website.

We started with semi-automated process that crawls closed issues and requires a lot of manual work of a release manager to make the result useful for end users.

So we decided to give more responsibility to developers and start to place the changelog entries in cover letters. A maintainer is responsible for placing the entry into a draft of a future release notes on GitHub's releases page. A release manager (together with maintainers and the documentation team) proof-reads the release notes before publishing a release.

As a side result of this process, the changelog entries becomes a subject for review and so the experience about writing such documents is shared across the team.

The situation becomes better, however this process have several annoying downsides:

• A developer should remember about the changelog entry just before sending a patch and as result it is often get out of the mind.
• GitHub drafts are not tracked with git, accessible only through a web browser, poorly resolves conflicts (when several persons made changes) and have no protection against accidental publishing (instead of saving a draft).
• The changelog entries for upcoming releases are not available publicly prior to publishing the release.

So we start to look how to better store the changelogs right within the git repository. The idea appears several times, but the stopper was that if we'll keep the changelog within a file (just one file or one file per release, including an upcoming release), we'll get a conflict at almost any cherry-pick: as from a developer branch to master as well as from master to a release branch.

The solution was suggested by the GitLab folks: just split changelog entries across files and squash them before a release.

We follow the spirit of the Keep a Changelog idea, but we does not follow the proposed format precisely. It brings us ability to structurize the release notes in a way that better fit our wishes and hopefully will be most convenient for our users.

[Totktonada]

To be honest I found fields type and category hard to remember and I would change the proposed format a bit.

Before:

$ cat changelogs/unreleased/bitset-index-varbinary.md
type: bugfix
category: core
----

* Bitset index now supports the varbinary type (gh-5392).

After:

$ cat changelogs/unreleased/bitset-index-varbinary.md
## bugfix/core

* Bitset index now supports the varbinary type (gh-5392).

I'll edit the proposal and the SOP document.

[Totktonada]

The first implementation is here: #5791

It seems, it is in a quite good shape. At least, I have no idea what else to add or what requires a change.

[Totktonada]

Now PR #5791 is pushed and changelogs are stored in the repository.

[Totktonada]

Alternative (changelog in a commit message): rpm-software-management/librepo@9e08de4

[Totktonada]

Added it to the document itself into the new 'Alternatives' section in #6411.