Reminder: Mark your BREAKING CHANGE with an exclamation point!

Back in 2021 we adopted Conventional Commits to standardize how Open edX developers communicate their code changes to various audiences (other developers, API users, end users, etc.). One particularly important part of the OEP is about marking :boom: breaking changes :boom: in the commit summary line and explaining them in the commit body:

Breaking changes include an exclamation point as part of the type label.

Breaking changes especially should have detailed information about the implications and alternatives, including a BREAKING CHANGE footer.

As a silly example:

feat!: remove the ability to author courses

Resolves: https://github.com/openedx/edx-platform/issues/666666

BREAKING CHANGE: This removes all pages of Studio. Course authors must
now write their courses in XML and submit them to the course import API.

Why does this help? Many of us are interested to know how the Open edX platform is changing from day to day, including those of us who distribute it (e.g., build-test-release WG, Tutor maintainers, and Devstack maintainers) as well as operators who run it off of main, clients of its HTTP APIs, and users of its packages. But the Open edX project receives dozens and dozens of commits every day… it would be ridiculous for anyone to pay attention to all of them! By highlighting which commits are breaking, you can help the community filter through the noise and react to the specific changes that require their attention.

What is a breaking change? A “breaking change” is something that changes how a repository works to some external stakeholders such that they’ll have to actively react, otherwise their code or processes may stop working. Examples include removal of user-facing pages, removal of API endpoints, changing the names of a package’s public Python or JS functions, schema changes that require non-standard migration operations, and dropping support for an old system dependency version.

What ISN’T a breaking change? Changes that only affect developers of the same repository, such as a internal refactorings, are not breaking. Non-distruptive changes to APIs or user interfaces aren’t breaking either. Marking something as deprecated isn’t breaking, but removing a deprecated feature is. Lastly, typical Django migrations aren’t breaking, because they run automatically.

Please try to follow this guideline, and when you’re reviewing a PR, don’t be shy in asking the author to do the same. Thanks in advance for your help! :pray:

6 Likes

One more quick tip: if bash yells at you when you use !:, like this:

$ git commit -m "fix!: break everything"
bash:  : unrecognized history modifier

then try single quotes instead:

$ git commit -m 'fix!: break everything'
[kdmccormick/breaking aac9137822] fix!: break everything
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 test.txt
1 Like