What would it take for engineers to maintain curated customer-perspective changelogs in each repo?

Problem statement

Once an engineer is done writing code, people will try to use it. Those people would like a summary of what has changed in the code, described in a way that is appropriate for them. Changelogs provide that information.

Some of the people who use our repos:

• Other edX engineers, when upgrading dependencies.

• edX devops, when understanding how to help deploying code.

• Open edX operators, when upgrading their installations and re-applying their own patches.

• People writing release notes for course teams on edx.org

• People writing documentation or support guidance for learners/educators/administrators using the edx.org site, or other Open edX sites.

What makes a good changelog?

• It should be written for the users of the repo, from their perspective.

• It should be relevant, not cluttered with useless noise.

• It should be available where users will find it.

Why not XYZ?

People often have suggestions of things that might work for this.

We could decide to use one of these sources of information, but the flaws in them would need to be addressed to do so.

Why not git commit messages?

Git commit messages are too brief, and too engineer-focused. They are also usually too noisy: not every commit should be mentioned in a changelog.

Why not GitHub releases?

Perhaps I don’t know the full behavior of GitHub releases, but they usually are collections of pull request titles. They link to the pull request, but usually pull requests don’t have the information repo-users are looking for.

GitHub release information is only available on GitHub, not in the cloned repo itself.