From 290328785c71b270a27b412ebdd97f0fd081e88b Mon Sep 17 00:00:00 2001 From: Jesse Squires Date: Sun, 19 Jan 2020 16:31:09 -0800 Subject: [PATCH] Update CONTRIBUTING.md --- CONTRIBUTING.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 62 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d34cfd1..bffbe78 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,6 +10,8 @@ - [Feature Requests](#love_letter-feature-requests) - [Triaging Issues](#mag-triaging-issues) - [Submitting Pull Requests](#repeat-submitting-pull-requests) +- [Writing Commit Messages](#memo-writing-commit-messages) +- [Code Review](#white_check_mark-code-review) - [Certificate of Origin](#medal_sports-certificate-of-origin) - [Credits](#pray-credits) @@ -71,6 +73,8 @@ For most contributions, after your pull request is accepted and merged, you will - **Coordinate bigger changes.** For large and non-trivial changes, open an issue to discuss a strategy with the maintainers. Otherwise, you risk doing a lot of work for nothing! +- **Prioritize understanding over cleverness.** Write code clearly and concisely. Remember that source code usually gets written once and read often. Ensure the code is clear to the reader. The purpose and logic should be obvious to a reasonably skilled developer, otherwise you should add a comment that explains it. + - **Follow existing coding style and conventions.** Keep your code consistent with the style, formatting, and conventions in the rest of the code base. When possible, these will be enforced with a linter. Consistency makes it easier to review and modify in the future. - **Include test coverage.** Add unit tests or UI tests when possible. Follow existing patterns for implementing tests. @@ -85,12 +89,68 @@ For most contributions, after your pull request is accepted and merged, you will - **[Resovle any merge conflicts](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/resolving-a-merge-conflict-on-github)** that occur. +- **Promptly address any CI failures**. If your pull request fails to build or pass tests, please push another commit to fix it. + - When writing comments, use properly constructed sentences, including punctuation. -- Remember that source code usually gets written once and read often. Ensure the code is clear to the reader. The purpose and logic be obvious to a reasonably skilled developr, or you should add a comment that explains it. - - Use spaces, not tabs. +## :memo: Writing Commit Messages + +Please [write a great commit message](https://chris.beams.io/posts/git-commit/#seven-rules). + +1. Separate subject from body with a blank line +1. Limit the subject line to 50 characters +1. Capitalize the subject line +1. Do not end the subject line with a period +1. Use the imperative mood in the subject line (example: "Fix networking issue") +1. Wrap the body at about 72 characters +1. Use the body to explain **why**, *not what and how* (the code shows that!) +1. If applicable, prefix the title with the relevant component name. (examples: "[Docs] Fix typo", "[Profile] Fix missing avatar") + +``` +[TAG] Short summary of changes in 50 chars or less + +Add a more detailed explanation here, if necessary. Possibly give +some background about the issue being fixed, etc. The body of the +commit message can be several paragraphs. Further paragraphs come +after blank lines and please do proper word-wrap. + +Wrap it to about 72 characters or so. In some contexts, +the first line is treated as the subject of the commit and the +rest of the text as the body. The blank line separating the summary +from the body is critical (unless you omit the body entirely); +various tools like `log`, `shortlog` and `rebase` can get confused +if you run the two together. + +Explain the problem that this commit is solving. Focus on why you +are making this change as opposed to how or what. The code explains +how or what. Reviewers and your future self can read the patch, +but might not understand why a particular solution was implemented. +Are there side effects or other unintuitive consequences of this +change? Here's the place to explain them. + + - Bullet points are okay, too + + - A hyphen or asterisk should be used for the bullet, preceded + by a single space, with blank lines in between + +Note the fixed or relevant GitHub issues at the end: + +Resolves: #123 +See also: #456, #789 +``` + +## :white_check_mark: Code Review + +- **Review the code, not the author.** Look for and suggest improvements without disparging or insulting the author. Provide actionable feedback and explain your reasoning. + +- **You are not your code.** When your code is critiqued, questioned, or constructively criticized, remember that you are not your code. Do not take code review personally. + +- **Always do your best.** No one writes bugs on purpose. Do your best, and learn from your mistakes. + +- Kindly note any violations to the guidelines specified in this document. + ## :medal_sports: Certificate of Origin *Developer's Certificate of Origin 1.1*