docs: migrate to scriv to manage changelog

[regisb]

Changelog management was starting to be a hassle:

• there were conflicts every time a PR was merged
• there were conflicts every time we merged the nightly branch in the new release branch, or vice versa.

Now, all changelog entries are stored as separate files in changelog.d, including nightly. Nightly entries will be collected for every major release.

[regisb]

And of course I'm tagging @nedbat here ;)

[regisb]

@overhangio/tutor-maintainers FYI I suggest that we migrate to scriv for managing changelogs. I expect that we will start maintaining changelogs in plugins as well very soon (I will be working on a PR if we agree on this).

[ghassanmas]

Sounds good to me, following this the scriv document here is how I imagine the follow would be:

• Create a new branch to resolve a bug, add new feature...etc
• Make changes to code files as needed
• Before commiting run scriv create
• Edit the new created file accordingly
• Commit the changes togather: 'Code + Changelog'

In case it's a big change i.e. there are multiple commits in the log, then is it expected to create a dedicated commit for the cahngelog?.

Lastly what is mapping between git commit message, and the changelog. Do we give low priority for commit message description that we have changelog, do we use duplicate content, summary...etc

[arbrandes]

One suggestion, one reaction, and one question. Approved. 👍🏼

[regisb]

In case it's a big change i.e. there are multiple commits in the log, then is it expected to create a dedicated commit for the changelog?.
Lastly what is mapping between git commit message, and the changelog. Do we give low priority for commit message description that we have changelog, do we use duplicate content, summary...etc

The roles of commits/changelog entries will not change after this PR. I have always considered commits and changelog entries to be two very different things. Commits are read by developers. Changelogs are read by Tutor users. Commit titles are meant to be short and sweet, while changelog entries should explain, for instance, how to handle breaking changes. Commit texts should describe the thought process that went into fixing issues, while changelogs should focus on the result for end users.

So to answer your question @ghassanmas:

In case it's a big change i.e. there are multiple commits in the log, then is it expected to create a dedicated commit for the changelog?

There is no general answer to that. It really depends.

Lastly what is mapping between git commit message, and the changelog. Do we give low priority for commit message description that we have changelog, do we use duplicate content, summary...etc

There is no mapping at all. If some information must be duplicated, then so be it. We must not expect that people who read changelogs also read commit messages. The reverse is true, in most cases. Again, I don't have an answer that will apply to all cases. In general, I'd say: write as many words as possible. It's more work, but it's almost always best for the readers, whether they are developers or users.

[ghassanmas]

Thank you @regisb for the detailed explanation, that exacly what I was looking for. And I do agree with your conclusion 👍🏾

[kdmccormick]

I didn't have a chance to review, but this looks great. If using scriv with Tutor goes well, this will help us sell the idea of using it in Open edX too.