commits that are big enough to add value to the project, and small enough to read, review and revert. There is no hard and fast rule for determining what adds value to the project, or what is small enough: use common sense.
However, it's common sense that common sense the least common of the senses.
A commit should implement one (and only one) thing. If commit A renders the project in an inconsistent state, and it has to be followed by another commit B, which tidies up A, it follows that A+B is a logically atomic commit, since neither A nor B stand by themselves.
Examples (in chronological order)
First feat: implement a feature with some bug then fix: fix the bug in the feature. The initial implementation of the feature should not include such a bug.
First build: remove foo dependency then refactor: refactor code not to use foo (removing a dependency does not stand by itself, the project cannot be built until the refactor has been applied)
First refactor: refactor code not to use foo then build: remove foo dependency (unless it's an incremental refactoring that gradually removes foo up to the point where foo can be safely removed, it seems that the second commit is an immediate consequece of the first one, and none of them would stand by itself).
See also #1 and #12
Proposal: clarify that a logically atomic commit stands by itself
- These guidelines encourage logically atomic commits, i.e. commits that
+ These guidelines encourage logically atomic commits, i.e. commits that stand by themselves,
are big enough to add value to the project, and small enough to read, review and revert.
1.0.0-rc.3 defines logically atomic commits as
However, it's common sense that common sense the least common of the senses.
A commit should implement one (and only one) thing. If commit A renders the project in an inconsistent state, and it has to be followed by another commit B, which tidies up A, it follows that A+B is a logically atomic commit, since neither A nor B stand by themselves.
Examples (in chronological order)
feat: implement a feature with some bug
thenfix: fix the bug in the feature
. The initial implementation of the feature should not include such a bug.build: remove foo dependency
thenrefactor: refactor code not to use foo
(removing a dependency does not stand by itself, the project cannot be built until the refactor has been applied)refactor: refactor code not to use foo
thenbuild: remove foo dependency
(unless it's an incremental refactoring that gradually removes foo up to the point where foo can be safely removed, it seems that the second commit is an immediate consequece of the first one, and none of them would stand by itself).See also #1 and #12
Proposal: clarify that a logically atomic commit stands by itself