Please provide more descriptive messages for BOM commits

Development
1

Before I share the issue I want to thank everyone who contribute here and made this great product. I think the edx-platform maintains a very high quality commit and engineering standards. I’ve personally was able to improve my own engineering work quality just by contributing and getting feedback from different collaborators.

Lack of commit titles of some BOM commits

I noticed a recent trend of which some commits and Pull Requests are pretty much substandard and comes with only a Jira issue ID i.e. BOM-5721. Ideally a commit should give a clue about its content without having to read the detailed description.

Most of those commits do come with a description, but lacks a commit title.

There are 260 of those commits so far and can be found by doing a grep:

$ cd edx-platform
$ git log --no-merges | grep -B4 -A2 -e '^[ ]*BOM-[0-9 ]*$'

Suggested solution

Please follow OEP-0051 - Conventional Commits #189. It’s a great guide.

2 Likes
2

Aye to that! Improving BOM commits should be part of a more global effort of improving commit titles and messages across Open edX. Here are a few guidelines:

  • Use conventional commit titles
  • In the title, describe why you are making the change, not what change you are making. For instance, write:

fix: “TypeError” when loading the courseware

and not:

fix: catch exceptions in xblock method

  • Write commit messages below commit titles. 90-95% of commits should include a detailed, extensive commit message. Describe the technical choices you made (“what”) and how they solve the issues (“why”).
2 Likes