Repository: mesos Updated Branches: refs/heads/master e46e16a4b -> aac1217ae
Added markdown formatting to the committer's guide. Project: http://git-wip-us.apache.org/repos/asf/mesos/repo Commit: http://git-wip-us.apache.org/repos/asf/mesos/commit/aac1217a Tree: http://git-wip-us.apache.org/repos/asf/mesos/tree/aac1217a Diff: http://git-wip-us.apache.org/repos/asf/mesos/diff/aac1217a Branch: refs/heads/master Commit: aac1217ae7044016b625a06aa9a51921fcf0e055 Parents: e46e16a Author: Benjamin Mahler <[email protected]> Authored: Fri Oct 10 12:19:10 2014 -0700 Committer: Benjamin Mahler <[email protected]> Committed: Fri Oct 10 12:19:10 2014 -0700 ---------------------------------------------------------------------- docs/committers-guide.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/mesos/blob/aac1217a/docs/committers-guide.md ---------------------------------------------------------------------- diff --git a/docs/committers-guide.md b/docs/committers-guide.md index 821aae7..c016ee9 100644 --- a/docs/committers-guide.md +++ b/docs/committers-guide.md @@ -1,4 +1,4 @@ -Committer's Guide +# Committer's Guide This is an attempt to capture the "etiquette" that we've informally used with Review Board and committing. A lot of this is obvious and @@ -7,7 +7,7 @@ comprehensive and pedantic. ------------------------------------------------------------------ -(1) Wait for a 'ship it'. We often use the original developer or +**(1)** **Wait for a 'ship it'**. We often use the original developer or current "custodian" of some particular code to be the reviewer and add others to get more feedback or as an FYI. Feel free to explicitly call out that you're adding some people just as an FYI in the @@ -16,7 +16,7 @@ to one another about a particular change/feature before we even start coding. A little context goes a long way to streamlining the review process. -(2) Resolve issues before committing. We tend to give a 'ship it' even +**(2)** **Resolve issues before committing**. We tend to give a 'ship it' even when we think there are some issues that need correcting. Sometimes a particular issue will require more discussion and sometimes we take that discussion to IM or IRC or emails to expedite the process. It's @@ -25,22 +25,22 @@ collaborations/discussions that happened in those means. Making the discussion public also helps involve others that would have liked to get involved but weren't invited. -If the reviewer and reviewee are having problems resolving a +**(2.1)** If the reviewer and reviewee are having problems resolving a particular "confrontational" issue then both parties should consider asking another reviewer to participate. We're all here to build the highest quality code possible, and we should leverage one another to do so. -(2.1) When an issue is "Dropped" by the reviewee, the expectation is +**(2.2)** When an issue is "Dropped" by the reviewee, the expectation is that there is a reply to the issue indicating why it was dropped. A silent "Drop" is very ambiguous. -(2.2) If an issue is marked as "Resolved", the expectation is that the +**(2.3)** If an issue is marked as "Resolved", the expectation is that the diff has been updated in accordance (more or less) with the reviewer's comment. If there are significant changes, a reply to the issue with a comment is greatly appreciated. -(3) Be patient, thoughtful, and respectful when providing (a) feedback +**(3)** **Be patient, thoughtful, and respectful** when providing (a) feedback on reviews and (b) commenting on feedback. This is not meant to be a sparring match. A prerequisite to being a good reviewee is acknowledging that 'writing is hard'! The reviewee should give the @@ -54,13 +54,13 @@ for giving hasty feedback. The reviewer should invest time and energy trying to explain their concerns clearly and carefully. It's a two-way street! -(4) Be explicit about asking for more feedback. Feel free to update +**(4)** **Be explicit about asking for more feedback.** Feel free to update reviews as often as you like but recognize that in many cases it's ambiguous for reviewers when a review is back into a "ready" state so the reviewee should feel free to ping the reviewers via email when they're ready. -(5) Follow the format of commit messages. The three important bits are +**(5)** **Follow the format of commit messages.** The three important bits are (a) be clear and explicit in the commit message and (b) include the link to the review and (c) use 72 character columns. See support/apply-review.sh for committing someone else's code (it will @@ -70,10 +70,10 @@ which can be omitted). Note that we don't always have a 50 character or less summary because that restriction tends to cause people to write poorly. -(6) Never ever commit a merge. Rebase as appropriate. Likewise, never +**(6)** **Never ever commit a merge.** Rebase as appropriate. Likewise, never 'force push'. -(7) Don't break the build. People use Linux and Mac OS X, be +**(7)** **Don't break the build.** People use Linux and Mac OS X, be thoughtful about doing a 'make check' on both before committing your code. In the future we hope to have Jenkins running builds of our reviews as well as our commits and not allowing code to be committed
