Editorial: Documentation for COMMITTING.md

COMMITTING.md

@@ -0,0 +1,77 @@
+# WHATWG committer guidelines
+
+
+## General
+
+Each change needs to result in a single commit on the master branch, with no merge commits. The green squash and merge button is OK to use, but be sure to tidy up the commit message per the below guidelines. In particular, if you use the squash functionality, delete the parenthetical pull request number that GitHub adds.
+
+## Commit messages
+
+_(Derived from the [erlang/otp wiki](https://github.com/erlang/otp/wiki/Writing-good-commit-messages).)_
+
+### Purpose
+
+Great commit messages serve at least three important purposes:
+
+* To help pull requests reviewers understand what is being changed.
+* To make it easy and pleasant to review the history of the repository.
+* To help future maintainers find out why a particular change was made.
+
+As such, you should write a commit message that will allow your future self to understand the intent of change without looking at the diff. This will not only benefit reviewers, but also other maintainers. Your commit message should express intent without delving into implementation details.
+
+For more on this topic, see ["On commit messages"](http://who-t.blogspot.com/2009/12/on-commit-messages.html).
+
+### Structure and conventions
+
+Commit messages consist of a single title line, a blank line, and then a more detailed change description. The description (and preceding blank line) may be omitted for simple fixes.
+
+All lines should be at most 72 characters, to make them easier to view in GitHub and other tools. Some sources recommend restricting the title line to 50 characters, but we do not enforce this.
+
+The title must be written in imperative mode, as if commanding someone. This means using verb conjugations such as "fix"/"add"/"change" instead of "fixed"/"added"/"changed" or "fixing"/"adding"/"changing". We are less consistent with the description, but often use present tense (i.e. "This change adds…").
+
+Title lines must not end in a period; they are titles, not sentences.
+
+Be sure to reference related GitHub issues within pull requests so they are appropriately cross-linked by GitHub. Use "closes" or "fixes" as appropriate to [automatically close issues](https://help.github.com/articles/closing-issues-using-keywords/).
+
+Avoid using Markdown-style code markup (i.e. backticks) unless necessary for disambiguation.
+
+### Title prefixes
+
+Prefix the title line with **"Editorial: "** if the change is just to fix formatting, typos, or is a refactoring that does not change how the standard is understood. Note that bug fixes or clarifications are not editorial, even if they only affect non-normative text.
+
+Prefix the title line with **"Meta: "** for changes that do not directly affect the text of the standard, but instead the ecosystem around it, such as spec tooling or contributor documentation.
+
+In general, most commits do not have a prefix.
+
+### Example
+
+From [whatwg/html@54585](https://github.com/whatwg/html/commit/5458513792ab00d58e6c91ba48faaa611d034a2e):
+
+```
+Editorial: move base URL from "module script" to "script"
+
+This propagates an appropriate base URL for all instances of creating a
+classic script. This has no effect by itself (and indeed looks kind of
+pointless as of this commit), but it sets the stage for making import()
+use this base URL (#2315).
+```
+
+## Branches
+
+Branches are transient and their names should be detailed enough to avoid confusion. Choose short and descriptive names. Using hyphens to separate words is encouraged.
+
+```bash
+# good
+$ git checkout -b modernize-template-header
+```
+
+```bash
+# bad: too vague and malformatted
+$ git checkout -b fix_paragraph-header
+```
+
+Identifiers from corresponding Github issues are great candidates for use in branch names. For example, when working on an issue:
+
+```bash
+$ git checkout -b issue-15
+```

CONTRIBUTING.md

@@ -2,6 +2,10 @@
 
 These are the general guidelines for contributing to WHATWG standards.
 
+## Committing
+
+See [COMMITTING.md](COMMITTING.md) for further details.
+
 ## Pull requests
 
 Leave the **Allow edits from maintainers** option enabled to allow reviewers to fix trivial issues directly on your branch rather than needing to write review comments asking you make the edits.  For more details, see [Improving collaboration with forks](https://github.com/blog/2247-improving-collaboration-with-forks) in the GitHub Blog.

TEAM.md

@@ -4,11 +4,7 @@ These are the general guidelines for maintaining WHATWG standards. Mostly boring
 
 ## Handling pull requests
 
-Each change needs to result in a single commit on the master branch, with no merge commits. The green squash and merge button is OK to use, but be sure to tidy up the commit message per [guidelines for writing good commit messages](https://github.com/erlang/otp/wiki/Writing-good-commit-messages).
-
-Prefix the summary line with "Editorial: " if the change is just to fix formatting, typos, or is a refactoring that does not change how the standard is understood. Note that bug fixes or clarifications are not editorial, even if they only affect non-normative text.
-
-Prefix the summary line with "Meta: " for changes that do not directly affect the text of the standard, but instead the ecosystem around it, such as spec tooling or contributor documentation.
+Rules for title/message must be satisfied before pull request is reviewed. See [COMMITTING.md](COMMITTING.md) for further details.
 
 For normative changes, ask for a [web-platform-tests](https://github.com/w3c/web-platform-tests) PR if testing is practical and not overly burdensome. Aim to merge both PRs at the same time. If one PR is approved but the other needs more work, add the `do not merge yet` label or, in web-platform-tests, the `status:needs-spec-decision` label.