README.adoc in git-lint-1.3.0 vs README.adoc in git-lint-1.4.0
- old
+ new
@@ -913,18 +913,23 @@
follow, make sure to explain that.
** Include links to dependent projects, stories, etc. if available.
* Use small, atomic commits:
** Easier to review and provide feedback.
** Easier to review implementation and corresponding tests.
-** Easier to document with detailed subject messages (especially when grouped together in a pull
- request).
+** Easier to document with detailed subjects (especially when grouped together in a pull request).
** Easier to reword, edit, squash, fix, or drop when interactively rebasing.
** Easier to combine together versus tearing apart a larger commit into smaller commits.
* Use logically ordered commits:
** Each commit should tell a story and be a logical building block to the next commit.
+** Each commit should, ideally, be the implementation plus corresponding test. Avoid committing
+ changes that are a jumble of mixed ideas as they are hard to decipher and a huge insult not only
+ to the reviewer but your future self.
** Each commit, when reviewed in order, should be able to explain _how_ the feature or bug fix was
completed and implemented properly.
+* Keep refactored code separate from behavioral changes. This makes the review process easier
+ because you don't have to sift through all the line and format changes to figure out what is new
+ or changed.
=== Branches
* Use feature branches for new work.
* Maintain branches by rebasing upon `master` on a regular basis.
@@ -954,28 +959,40 @@
like editors or other tools one choose to do their work. For team consistency, use a continuous
integration build server instead.
=== Code Reviews
-There are two objectives each code review should achieve:
+There are three main objectives each code review should achieve:
+. *Joy* - The experience of working with you, receiving feedback, giving feedback, and demonstrating
+ a level of care influences others and encourages a collaborative environment that is fun to work
+ in. Use this time to build and reinforce trust amongst your fellow colleagues.
. *Quality*: Ensures changes are of highest quality that adhere to team standards while enhancing
the customer experience and not disrupting their workflow.
. *Education*: Provides a chance for everyone on the team to learn more about the architecture,
product/service, and how each member of the team implements a solution. This is your chance to
ask questions and learn how to be a better engineer so take advantage of it.
In addition to the objectives above, the following guidelines are worth following:
* Keep code reviews short and easy to review:
+** Review your own code first before submitting to others. By ensuring your are confident in the
+ overall implementation and the commits in terms of commit messages and implementation details,
+ you'll encourage higher quality feedback and show appreciation for the reviewer's time.
** Provide a high level overview that answers _why_ the code review is necessary.
-** Provide a link to the issue/task that prompted the code review (if any).
+** Provide a link to the issue that prompted the code review (if any) and any additional details
+ worth highlighting to guide the reviewer through the process.
** Provide screenshots/screencasts if possible.
-** Ensure commits within the code review are related to the purpose of the code review.
-** Prefer code reviews at about 250 lines in order to keep the quality of the code review and defect
- detection high.
-** Avoid working on a large issue without getting feedback first in order to not overwhelm/surprise
+** Provide any ancillary notes or points of interest worth highlighting for the reviewer.
+** Ensure commits within the code review are related to the purpose of the code review and avoid
+ mixing in changes that are ancillary to the primary objective of the code view. If you do have
+ changes outside of the scope of the current code review, open those changes up as a separate code
+ review instead.
+** Prefer code reviews at about 300 lines in order to keep the quality of the code review and defect
+ detection high. This also shows you value the reviewers time and attention away from their own
+ work.
+** Avoid working on a large issues without first getting feedback in order to not overwhelm/surprise
the maintainers. More discussion up front will help ensure your work has a faster chance of
acceptance.
* Review and rebase code reviews quickly:
** Maintain a consistent but reasonable pace -- Review morning, noon, and night.
** Avoid letting code reviews linger more than a day. Otherwise, you risk hampering moral and
@@ -1011,12 +1028,17 @@
good idea to address and resolve the feedback.
** 🙇 (`:bow:`) - Indicates thankfulness of the feedback received. This is _non-blocking_ and
always meant as a response to helpful feedback.
** ✅ (`:white_check_mark:`) - Signifies code review approval. The author can
rebase onto `master` and delete the feature branch at this point.
+* Use all feedback as a chance to learn, teach, strenghen the bond of trust between you and your
+ fellow colleagues, and avoid being cut by
+ link:https://fs.blog/2017/04/mental-model-hanlons-razor[Hanlon's Razor].
+* Use automation to ensure code reviews are consistent, of high quality, and swift to resolve. Each
+ code review can be an opportunity to identify and automate the process further.
* Use face-to-face communication if a code review's written discussion gets lengthy/noisy.
-* Create new tasks/actions if additional features are discovered during a code review to avoid
- delaying code review acceptance. Return to the code review once tasks have been logged.
+* Create follow-up actions if additional features are discovered during a code review to avoid
+ delaying code review acceptance. Return to the code review once the new actions have been logged.
* The author, not the reviewer, should rebase the feature branch onto `master` upon approval.
* Avoid reviewing your own code review before rebasing onto `master`. Have another pair of eyes
review your code first.
* Ensure the following criteria is met before rebasing your feature branch to `master`:
** Ensure all `fixup!` and `squash!` commits are interactively rebased. _Avoid rebasing these onto