summaryrefslogtreecommitdiffstats
path: root/docs/contributing/committing_rules_and_responsibilities.rst
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--docs/contributing/committing_rules_and_responsibilities.rst198
1 files changed, 198 insertions, 0 deletions
diff --git a/docs/contributing/committing_rules_and_responsibilities.rst b/docs/contributing/committing_rules_and_responsibilities.rst
new file mode 100644
index 0000000000..c3edcba79f
--- /dev/null
+++ b/docs/contributing/committing_rules_and_responsibilities.rst
@@ -0,0 +1,198 @@
+Committing rules and responsibilities
+=====================================
+
++--------------------------------------------------------------------+
+| This page is an import from MDN and the contents might be outdated |
++--------------------------------------------------------------------+
+
+Preparation
+-----------
+
+There are things you need to be sure of before you even attempt to check
+in:
+
+- Your code must
+ :ref:`compile <Building Firefox On Linux>` and `pass all the automated tests <https://developer.mozilla.org/docs/Mozilla/QA/Automated_testing>`__
+ before you consider pushing changes. If you are at all unsure, verify
+ your changes with the
+ `mozilla-central <https://wiki.mozilla.org/Build:TryServer>`__.
+ try server, as appropriate.
+- You need :ref:`code review <Code Review FAQ>`.
+- Depending on the stage of the development process, you may need
+ `approval <https://wiki.mozilla.org/Tree_Rules>`__. Commits to trees
+ where approval is required must have "a=" in the commit message
+ followed by the name of the approver.
+- Code should be factored in such a way such that we can disable
+ features which cause regressions, either by backout or via a kill
+ switch/preference. Be especially careful when landing features which
+ depend on other new features which may be disabled. Ask
+ mozilla.dev.planning for assistance if there are any questions.
+
+Checkin comment
+---------------
+
+The checkin comment for the change you push should include the bug
+number, the names of the reviewers, and a clear explanation of the fix.
+Please say what changes are made, not what problem was fixed, e.g.:
+
+Good: "Bug 123456 - Null-check presentation shell so we don't crash when a
+button removes itself during its own onclick handler. r=paul, a=ringo."
+
+Bad: "Bug 123456 - crash clicking button on www.example.com"
+
+If you are not the author of the code, use ``hg commit -u`` to specify
+the actual author in the Mercurial changeset:
+
+::
+
+ hg commit -u "Pat Chauthor <pat@chauthor.com>"
+
+Commit message restrictions
+---------------------------
+
+The purpose of these new restrictions, implemented via a mercurial hook,
+is to prevent commit messages that do not have a bug number. We will
+still allow a small set of special commits lacking bugs numbers, like
+merges and backouts.
+
+This hook will be enabled on mozilla-central and every major branch that
+directly merges into it, such as autoland or integration
+branches, team branches, or established project branches.
+
+An example for a passing commit message would be,
+
+::
+
+ Bug 577872 - Create WebM versions of Ogg reftests. r=kinetik
+
+Note the *Bug ####*, you at least need that. You also can't commit
+bustage-fixes without a bug number anymore. This is intentional to keep
+track of the bug which caused it.
+
+Allowed are:
+
+- Commit messages containing "bug" or "b=" followed by a bug number
+- Commit messages containing "no bug" (please use this sparingly)
+- Commit message indicating backout of a given 12+ digit changeset ID,
+ starting with (back out|backing out|backed out|backout)( of)?
+ (rev|changeset|cset)s? [0-9a-f]{12}
+- Commit messages that start with "merge" or "merging" and are actually
+ for a merge changeset.
+
+Special exceptions:
+
+- Commits by the special users "ffxbld", "seabld", "tbirdbld", or
+ "cltbld".
+- When the commit is older then some date shortly after the hook has
+ been enabled, to allow merges from other branches. This exception
+ will be lifted after a short period of time (probably a few months)
+ after the hooks is enabled.
+- You can also specify "IGNORE BAD COMMIT MESSAGES" in the tip (latest)
+ commit message to override all the restrictions. This is an extreme
+ measure, so you should only do this if you have a very good reason.
+
+Explicitly disallowed:
+
+- Commit messages containing "try: " to avoid unintentional commits
+ that were meant for the try server.
+
+All tests for allowed or excluded messages are case-insensitive. The
+hook,
+`commit-message.py <https://hg.mozilla.org/hgcustom/version-control-tools/file/tip/hghooks/mozhghooks/commit-message.py>`__,
+was added in `bug 506949 <https://bugzilla.mozilla.org/show_bug.cgi?id=506949>`__.
+
+
+Check the tree
+--------------
+
+TaskCluster is a continuous build system that builds and tests every change
+checked into autoland/mozilla-central and related source trees.
+`Treeherder <https://treeherder.mozilla.org/>`__ displays the progress
+and results of all the build and test jobs for a given tree. For a
+particular job, green means all is well, orange means tests have failed,
+and red means the build itself broke. Purple means that a test was
+interrupted, possibly by a problem with the build system or the
+network. Blue means that a test was interrupted in a known way and will
+be automatically restarted. You can click on the "Help" link in the top
+right corner of Treeherder for a legend to help you decode all the other
+colors and letters.
+
+If the tree is green, it is okay to check in. If some builds are orange
+or red, you can either wait, or make sure all the failures are
+classified with annotations/comments that reference bug numbers or
+fixes.
+
+If the tree is marked as "closed", or if you have questions about any
+oranges or reds, you should contact the sheriff before checking in.
+
+
+Failures and backouts
+---------------------
+
+Patches which cause unit test failures (on :ref:`tier 1
+platforms <Supported Build Hosts and Targets>`) will be backed out.
+Regressions on tier-2 platforms and in performance are not cause for a
+direct backout, but you will be expected to help fix them if quickly.
+
+*Note: Performance regressions require future data points to ensure a
+sustained regression and can take anywhere from 3 hours to 30 hours
+depending on the volume of the tree and build frequency. All regression
+alerts do get briefly investigated and bugs are filed if necessary.*
+
+
+Dealing with test failures
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If a build or a test job fails, you can click on the red or orange or
+purple symbol for the job on Treeherder to display more information.
+The information will appear in the footer, including a summary of any
+error messages, a "+" icon to re-trigger the job (schedule it to run
+again), and links to the log files and to possibly-related bugs.
+
+Here are some steps you can follow to figure out what is causing most
+failures, `and "star" them
+appropriately <http://ehsanakhgari.org/blog/2010-04-09/assisted-starring-oranges>`__:
+
+#. Click on the failing job to see a list of suggested bugs. If the
+ failure clearly matches a known bug, **click on the star** next to
+ that bug and then click "Add a comment" and then submit the comment.
+ This is referred to as "starring the build;" you'll see this phrase
+ or ones like it in IRC a lot.
+#. If the failure might match a known bug but you are not sure, click
+ the bug number to open the Bugzilla report, and click the failing job
+ to open its log. If the log and the bug do match, add a comment as
+ in step 1 (above).
+#. If the summary does not seem to match any suggested bugs, search
+ Bugzilla for the name of the failing test or the error message. If
+ you find a matching bug, add a comment in the bug in Bugzilla, and
+ another to the job in Treeherder.
+#. If you can't figure out whether a known bug exists (for example,
+ because you can't figure out what part of the log you should search
+ for), look on Treeherder to see if there are other similar failures
+ nearby, or ask on #developers to see if anyone recognizes it as a
+ known failure. For example, many Android tests fail frequently in
+ ways that do not produce useful log messages. You can often find the
+ appropriate bug just by looking at other Android failures that are
+ already starred.
+#. If there is no matching bug, you can back out the change (if you
+ suspect the failure was caused by your changeset) or re-trigger the
+ job (if you suspect it's an unrelated intermittent failure). After
+ more test runs it should become clear whether it is a new regression
+ or just an unknown intermittent failure.
+#. If it turns out to be an unknown intermittent failure, file a new bug
+ with "intermittent-failure" in the keywords. Include the name of the
+ test file and an one-line summary of the log messages in the Summary
+ field. In the description, include an excerpt of the error messages
+ from the log, and a link to the log file itself.
+
+At any point if you are not sure or can't figure out what to do, ask for
+advice or help in `#developers <https://chat.mozilla.org>`__.
+If a large number of jobs are failing and you suspect an infrastructure problem, you can also ask
+about it in `#releng <https://chat.mozilla.org>`__.
+
+
+Dealing with performance regressions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Under some circumstances, if your patch causes a performance regression
+that is not acceptable, it will get backed out.