From 33f104c4548685db542bca0c0388f73e2de6a645 Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Wed, 24 Feb 2021 17:29:02 -0500 Subject: [PATCH] docs: oep-0051: include more commentary --- oeps/oep-0051-bp-conventional-commits.rst | 99 +++++++++++++---------- 1 file changed, 55 insertions(+), 44 deletions(-) diff --git a/oeps/oep-0051-bp-conventional-commits.rst b/oeps/oep-0051-bp-conventional-commits.rst index ccb7561e8..5fd5fa25d 100644 --- a/oeps/oep-0051-bp-conventional-commits.rst +++ b/oeps/oep-0051-bp-conventional-commits.rst @@ -28,11 +28,6 @@ OEP-0051: Conventional Commits * - References - TK -.. todo: - what type for: - - commit that removes a depr'd thing - - commit that updates a pinned package to get new features? - Abstract ======== @@ -44,15 +39,22 @@ This is part of our Change Transparency initiative. Motivation ========== +Developers should describe the changes they make. This information is valuable to many audiences: deployers, integrators, end-users, operators, and so on. Developers are in the best position to accurately describe their work and its implications. + +The nearer to the change that information is captured, the easier it will be to write, and the more accurate it will be. Changes made by developers are consumed by many people, from the pull request reviewer to the final user of the product. The more the developer can explain the change, the more easily the change will be understood and used, and the more efficient the overall development process will be. + +Commit messages are the closest text to the change itself. The more +information-rich we can make commit messages, the more useful they will be. + Specfication ============ We are adopting the `Conventional Commits`_ spec, with our own adjustments. -.. note:: Many people are familiar with the `Angular commit message format`_, which uses conventional commits and inspired the Conventional Commits spec. We are not adopting the Angular rules. +.. note:: Many people are familiar with the `Angular commit message format`_, which uses conventional commits and inspired the Conventional Commits spec. We are **not** adopting the Angular rules. -Commit messages have these parts:: +Git commit messages have these parts:: : @@ -66,26 +68,35 @@ Type We use these commit types: * **build**: anything to do with building or releasing the repo: Makefile, tox.ini, Travis, Jenkins, GitHub actions, and so on. -* **chore**: a repetitive task such as updating requirements or translations. -* **docs**: documentation-only changes. Documentation changes for other types of work can be included in those commits. + +* **chore**: a repetitive mechanical task such as updating requirements or translations. + +* **docs**: documentation-only changes. Documentation changes for other types of work should be included in those commits. + * **feat**: a new feature, or a change to an existing feature. Anything that changes the set of features. -* **fix**: bug fixes. + +* **fix**: bug fixes, including changes to the behavior of features, and changes that remove or mitigate security vulnerabilities. + * **perf**: performance improvement. -* **refactor**: code reorganization that doesn't change behavior. + +* **refactor**: code reorganization that doesn't change behavior from the repo consumer perspective. + * **revert**: undo a previous change. The previous commit message, including the type prefix, is included. + * **style**: improve the styling of the code. + * **test**: test-only changes. Adds missing tests or corrects existing tests. Tests accompanying other types of changes go into those commits. Breaking changes include an exclamation point as part of the type:: feat!: removed the ability to author courses -Ideally, commits don't mix these types together. If they do, use the most important type in the commit message. The priority order for the types is generally: revert, feat, fix, perf, docs, test, build, refactor, style, chore. +Ideally, a single commit won't mix these types together. If a commit does, use the most important type in the commit message. The priority order for the types is generally: revert, feat, fix, perf, docs, test, build, refactor, style, chore. Scope ----- -The `Conventional Commits`_ spec includes a parenthesized scope after the type. Open edX repos are large and varied, making standardization of scopes difficult. We won't use scopes. This could change in the future. +The `Conventional Commits`_ spec includes a parenthesized scope after the type. Open edX repos are large and varied, making standardization of scopes difficult. We won't use scopes for now. This could change in the future. Subject ------- @@ -97,57 +108,57 @@ Body The subject of the commit is rarely enough information to fully understand the commit. The body can contain as much information as you like. Be generous. Take a moment to think about what you would want to know if someone else had authored this commit. +The more information you can put in the body of the commit message, the better. It's not unreasonable to have two paragraphs of explanation in the body. + +Breaking changes especially should have detailed information about the implications and alternatives. + Footer ------ -We are not proposing any formalized footers in the commit message. +We are not requiring any formalized footers in the commit message, though the use of a ``BREAKING CHANGE:`` footer is encouraged as a way of providing more details about breaking changes. -Tooling -======= +Discussion +========== -One of the advantages of formalized commit messages is using them as input to tooling and conformance checkers. However, we are not proposing the use of these tools at the moment. +Conventional Commits asks us to categorize changes into a small number of categories. There will naturally be cases where it isn't obvious which commit type to use. +Choosing the commit type to use for a commit is important, but it's only the first step. If you have doubts about which commit type to use, choose the highest-priority type that could apply. Then write a detailed body explaining the full complexity of your change. -Rationale -========= +**feat vs fix**: some user-visible changes to features could be classified as "feat" or "fix". Choose "feat" if the change adds to the set of features. Choose "fix" if the change affects how a feature behaves. Yes, this is still subjective. -The rationale adds to the specification by describing the events or -requirements that led to the proposal, what influenced the design, and why -particular design decisions were made. The rationale could provide evidence -of consensus within the community and discuss important objections or -concerns raised during discussion. It could identify any related work, -for example, how the feature is supported in other systems. +**breaking changes to features**: changing how a feature works is not a breaking change. For example, users are sent to a new experience instead of the old experience. This is not a breaking change. It should get a "feat" label, but not a "feat!" label. -Backward Compatibility -====================== +**DEPR**: removing deprecated code likely is a breaking change. -This statement identifies whether the proposed change is backward compatible. -An OEP that introduces backward incompatibilities must describe the -incompatibilities, with their severity and an explanation of how you propose to -address these incompatibilities. +**pinned dependencies**: updating the version of a pinned dependency seems like just a chore, but consider the repo consumer's perspective. If an updated dependency adds a feature, then the one-line commit to update the pinned version should be marked "feat". -Reference Implementation -======================== +If you are interested to see other discussion about these sorts of questions, the `Conventional Commits repo issues`__ have a number of threads. -The reference implementation must be completed before any OEP is given "Final" -status, but it need not be completed before the OEP is "Accepted". While there is -merit to the approach of reaching consensus on the specification and rationale -before writing code, the principle of "rough consensus and running code" is -still useful when it comes to resolving many discussions. +__ https://github.com/conventional-commits/conventionalcommits.org/issues + + +Tooling +======= -Rejected Alternatives -===================== +One of the advantages of formalized commit messages is using them as input to tooling and conformance checkers. We will investgate tooling in the future, and are making no recommendations now. + + +Rationale +========= + +The existing Conventional Commits standard is a familiar and widely adopted standard. It's a good place to start our own guidelines. It builds on our recently adopted pull request template to help focus developers on providing helpful information about their changes. + +We've adapted the guidelines to our own projects, and started small. -This statement describes any alternative designs or implementations that were -considered and rejected, and why they were not chosen. Change History ============== -A list of dated sections that describes a brief summary of each revision of the -OEP. +2021-02-25: Converted to OEP-0051. + +2021-02-01: A draft for review. .. _Conventional Commits: https://www.conventionalcommits.org