For Koa, I would like to start making improvements to how we communicate changes in our software. This is a top request from the community.

Teams should have flexibility to design a solution that works for them. I’ll lay out the general problem, and also propose some light-weight solutions.

tl;dr: If you want to know what to do

Create a CHANGELOG.rst file in your repo, or a “Change Log” section in your README.
When changes are made to the repo, describe the change in terms your repo’s audience can understand. Include implications if they are important.
- Note this means that not every change needs to be in the changelog: internal refactoring, adding tests, updating requirements, and so on are example of things only interesting to the repo developers.
Make a new section in the changelog for each release, with the date and the version number.

The Problem

We make software for a set of people; let’s call them customers, whether they pay us or not. As the software changes, we should be clear about what has changed, in terms appropriate for the customers, in places useful to the customers.

Customers can’t use our software effectively if we don’t clearly tell them how it has changed.

Some of our customers:

Course teams.
Other edX engineers, when upgrading dependencies.
Other edX engineers, when trying to understand the history of a component.
edX SRE, when understanding how to help deploying code.
Open edX operators, when upgrading their installations, re-applying their own patches, or developing their own deployment systems.
Open edX developers, when learning how to update their use of a component.
People writing documentation or support guidance for learners/educators/administrators using the edx.org site, or other Open edX sites.

For Juniper, we wrote release notes after the release was made. This had problems:

The notes were delayed,
It was labor-intensive,
We probably missed details that should have been included,
It skewed toward feature-level notes rather than operator or developer notes.

Juniper was an unusually long release (17+ months), but even in a six-month release, collecting change information as the code is changed will produce better results more effectively.

Information Needed

As mentioned above, there are different audiences for change information. These are some of the details people need:

What features have been implemented? How do they work? What older feature do they replace? What should we be aware of when using the feature? Is there configuration needed to make enable the feature?
What features have been removed? Is there a replacement?
What API endpoints have been added, changed, or removed?
What settings have been added, changed, or removed?
What new steps are needed when operating an Open edX site, or when developing for Open edX?

Phases

The problem is complex enough that we need to divide up "communicate changes" into smaller phases:

Writing: someone writes about what is changing.
Filtering: what changes are important to describe, and which are not?
Collecting: periodically the change descriptions need to be collected together.
Publishing: the collected descriptions need to be made available for people to read.

The phases can and will be handled differently in different repos, by different teams and even for different changes within a team.

We shouldn’t design a one-size-fits-all process. Better is a flexible process that lets teams find the best way to get this done for their situation.

Writing

Someone (engineering or product) needs to write about what is changing. Where these words are written is less important than that they get written. It could be Jira issues, pull request descriptions, commit messages, changelog files, wiki pages, and probably other places.

Each team should have a clear plan for how change descriptions will be written.

Who will write up the changes?
Where will they be written?
What audiences need to be considered?

Filtering

Not every change to every line of code needs to be recorded. Teams will need to decide based on their audiences what kinds of changes are important to record, and which can be skipped.

Usually, filtering will be an implicit part of the writing phase: changes which don’t need to be reported won’t be described in the first place. But some projects may have multiple audiences, with a different set of change descriptions going to different audiences.

Collecting

Periodically the change descriptions need to be collected together. The natural point is when the software is released, but for some repos, it might make sense to be on a different cadence.

Publishing

The change descriptions need to be put where the audience can make use of them. For developer-focused libraries, a changelog file in the repo is fine. For end-user feature descriptions, they’ll need to be published on Read The Docs or the partner portal.

Recommendations

Choose one of the following two processes:

Product-written feature notes

The product owner writes change descriptions in the existing Jira tickets for feature work. The team can review and contribute to these descriptions.
When an Open edX release happens, the product owner collects the descriptions and provides them in raw form to the Open edX release manager.
The Open edX release manager edits the information and publishes it on Read The Docs.

Engineer-written changelogs

Engineers write entries into repos' CHANGELOG files. Tools exist to make this easier to avoid merge conflicts. For customers who are comfortable with it, the entries can be read directly in the repo.
When an Open edX release happens, the release manager collects the information, edits it, and publishes it on Read The Docs.

Architecture and Engineering

Changelogs