docs/contributing/committing_rules_and_responsibilities.rst

   1 Committing rules and responsibilities
   2 =====================================
   3
   4 +--------------------------------------------------------------------+
   5 | This page is an import from MDN and the contents might be outdated |
   6 +--------------------------------------------------------------------+
   7
   8 Preparation
   9 -----------
  10
  11 There are things you need to be sure of before you even attempt to check
  12 in:
  13
  14 -  Your code must
  15    :ref:`compile <Building Firefox On Linux>` and `pass all the automated tests <https://developer.mozilla.org/docs/Mozilla/QA/Automated_testing>`__
  16    before you consider pushing changes. If you are at all unsure, verify
  17    your changes with the
  18    `mozilla-central <https://wiki.mozilla.org/Build:TryServer>`__.
  19    try server, as appropriate.
  20 -  You need :ref:`code review <Code Review FAQ>`.
  21 -  Depending on the stage of the development process, you may need
  22    `approval <https://wiki.mozilla.org/Tree_Rules>`__. Commits to trees
  23    where approval is required must have "a=" in the commit message
  24    followed by the name of the approver.
  25 -  Code should be factored in such a way such that we can disable
  26    features which cause regressions, either by backout or via a kill
  27    switch/preference. Be especially careful when landing features which
  28    depend on other new features which may be disabled. Ask
  29    mozilla.dev.planning for assistance if there are any questions.
  30
  31 Checkin comment
  32 ---------------
  33
  34 The checkin comment for the change you push should include the bug
  35 number, the names of the reviewers, and a clear explanation of the fix.
  36 Please say what changes are made, not what problem was fixed, e.g.:
  37
  38 Good: "Bug 123456 - Null-check presentation shell so we don't crash when a
  39 button removes itself during its own onclick handler. r=paul, a=ringo."
  40
  41 Bad: "Bug 123456 - crash clicking button on www.example.com"
  42
  43 If you are not the author of the code, use ``hg commit -u`` to specify
  44 the actual author in the Mercurial changeset:
  45
  46 ::
  47
  48    hg commit -u "Pat Chauthor <pat@chauthor.com>"
  49
  50 Commit message restrictions
  51 ---------------------------
  52
  53 The purpose of these new restrictions, implemented via a mercurial hook,
  54 is to prevent commit messages that do not have a bug number. We will
  55 still allow a small set of special commits lacking bugs numbers, like
  56 merges and backouts.
  57
  58 This hook will be enabled on mozilla-central and every major branch that
  59 directly merges into it, such as autoland or integration
  60 branches, team branches, or established project branches.
  61
  62 An example for a passing commit message would be,
  63
  64 ::
  65
  66    Bug 577872 - Create WebM versions of Ogg reftests. r=kinetik
  67
  68 Note the *Bug ####*, you at least need that. You also can't commit
  69 bustage-fixes without a bug number anymore. This is intentional to keep
  70 track of the bug which caused it.
  71
  72 Allowed are:
  73
  74 -  Commit messages containing "bug" or "b=" followed by a bug number
  75 -  Commit messages containing "no bug" (please use this sparingly)
  76 -  Commit message indicating backout of a given 12+ digit changeset ID,
  77    starting with (back out|backing out|backed out|backout)( of)?
  78    (rev|changeset|cset)s? [0-9a-f]{12}
  79 -  Commit messages that start with "merge" or "merging" and are actually
  80    for a merge changeset.
  81
  82 Special exceptions:
  83
  84 -  Commits by the special users "ffxbld", "seabld", "tbirdbld", or
  85    "cltbld".
  86 -  When the commit is older then some date shortly after the hook has
  87    been enabled, to allow merges from other branches. This exception
  88    will be lifted after a short period of time (probably a few months)
  89    after the hooks is enabled.
  90 -  You can also specify "IGNORE BAD COMMIT MESSAGES" in the tip (latest)
  91    commit message to override all the restrictions. This is an extreme
  92    measure, so you should only do this if you have a very good reason.
  93
  94 Explicitly disallowed:
  95
  96 -  Commit messages containing "try: " to avoid unintentional commits
  97    that were meant for the try server.
  98
  99 All tests for allowed or excluded messages are case-insensitive. The
 100 hook,
 101 `commit-message.py <https://hg.mozilla.org/hgcustom/version-control-tools/file/tip/hghooks/mozhghooks/commit-message.py>`__,
 102 was added in `bug 506949 <https://bugzilla.mozilla.org/show_bug.cgi?id=506949>`__.
 103
 104
 105 Check the tree
 106 --------------
 107
 108 TaskCluster is a continuous build system that builds and tests every change
 109 checked into autoland/mozilla-central and related source trees.
 110 `Treeherder <https://treeherder.mozilla.org/>`__ displays the progress
 111 and results of all the build and test jobs for a given tree. For a
 112 particular job, green means all is well, orange means tests have failed,
 113 and red means the build itself broke. Purple means that a test was
 114 interrupted, possibly by a problem with the build system or the
 115 network. Blue means that a test was interrupted in a known way and will
 116 be automatically restarted. You can click on the "Help" link in the top
 117 right corner of Treeherder for a legend to help you decode all the other
 118 colors and letters.
 119
 120 If the tree is green, it is okay to check in. If some builds are orange
 121 or red, you can either wait, or make sure all the failures are
 122 classified with annotations/comments that reference bug numbers or
 123 fixes.
 124
 125 If the tree is marked as "closed", or if you have questions about any
 126 oranges or reds, you should contact the sheriff before checking in.
 127
 128
 129 Failures and backouts
 130 ---------------------
 131
 132 Patches which cause unit test failures (on :ref:`tier 1
 133 platforms <Supported Build Hosts and Targets>`) will be backed out.
 134 Regressions on tier-2 platforms and in performance are not cause for a
 135 direct backout, but you will be expected to help fix them if quickly.
 136
 137 *Note: Performance regressions require future data points to ensure a
 138 sustained regression and can take anywhere from 3 hours to 30 hours
 139 depending on the volume of the tree and build frequency. All regression
 140 alerts do get briefly investigated and bugs are filed if necessary.*
 141
 142
 143 Dealing with test failures
 144 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 145
 146 If a build or a test job fails, you can click on the red or orange or
 147 purple symbol for the job on Treeherder to display more information.
 148 The information will appear in the footer, including a summary of any
 149 error messages, a "+" icon to re-trigger the job (schedule it to run
 150 again), and links to the log files and to possibly-related bugs.
 151
 152 Here are some steps you can follow to figure out what is causing most
 153 failures, `and "star" them
 154 appropriately <http://ehsanakhgari.org/blog/2010-04-09/assisted-starring-oranges>`__:
 155
 156 #. Click on the failing job to see a list of suggested bugs. If the
 157    failure clearly matches a known bug, **click on the star** next to
 158    that bug and then click "Add a comment" and then submit the comment.
 159    This is referred to as "starring the build;" you'll see this phrase
 160    or ones like it in IRC a lot.
 161 #. If the failure might match a known bug but you are not sure, click
 162    the bug number to open the Bugzilla report, and click the failing job
 163    to open its log. If the log and the bug do match, add a comment as
 164    in step 1 (above).
 165 #. If the summary does not seem to match any suggested bugs, search
 166    Bugzilla for the name of the failing test or the error message. If
 167    you find a matching bug, add a comment in the bug in Bugzilla, and
 168    another to the job in Treeherder.
 169 #. If you can't figure out whether a known bug exists (for example,
 170    because you can't figure out what part of the log you should search
 171    for), look on Treeherder to see if there are other similar failures
 172    nearby, or ask on #developers to see if anyone recognizes it as a
 173    known failure. For example, many Android tests fail frequently in
 174    ways that do not produce useful log messages. You can often find the
 175    appropriate bug just by looking at other Android failures that are
 176    already starred.
 177 #. If there is no matching bug, you can back out the change (if you
 178    suspect the failure was caused by your changeset) or re-trigger the
 179    job (if you suspect it's an unrelated intermittent failure). After
 180    more test runs it should become clear whether it is a new regression
 181    or just an unknown intermittent failure.
 182 #. If it turns out to be an unknown intermittent failure, file a new bug
 183    with "intermittent-failure" in the keywords. Include the name of the
 184    test file and an one-line summary of the log messages in the Summary
 185    field. In the description, include an excerpt of the error messages
 186    from the log, and a link to the log file itself.
 187
 188 At any point if you are not sure or can't figure out what to do, ask for
 189 advice or help in `#developers <https://chat.mozilla.org>`__.
 190 If a large number of jobs are failing and you suspect an infrastructure problem, you can also ask
 191 about it in `#releng <https://chat.mozilla.org>`__.
 192
 193
 194 Dealing with performance regressions
 195 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 196
 197 Under some circumstances, if your patch causes a performance regression
 198 that is not acceptable, it will get backed out.