Submitting Patches
==================
-- `Basic guidelines <#guidelines>`__
-- `Patch formatting <#formatting>`__
-- `Testing Patches <#testing>`__
-- `Submitting Patches <#submit>`__
-- `Reviewing Patches <#reviewing>`__
-- `Nominating a commit for a stable branch <#nominations>`__
-- `Criteria for accepting patches to the stable branch <#criteria>`__
-- `Sending backports for the stable branch <#backports>`__
-- `Git tips <#gittips>`__
-
.. _guidelines:
Basic guidelines
- Patches should not mix code changes with code formatting changes
(except, perhaps, in very trivial cases.)
-- Code patches should follow Mesa `coding
- conventions <codingstyle.html>`__.
+- Code patches should follow Mesa :doc:`coding
+ conventions <codingstyle>`.
- Whenever possible, patches should only affect individual Mesa/Gallium
components.
- Patches should never introduce build breaks and should be bisectable
(see ``git bisect``.)
-- Patches should be properly `formatted <#formatting>`__.
-- Patches should be sufficiently `tested <#testing>`__ before
+- Patches should be properly :ref:`formatted <formatting>`.
+- Patches should be sufficiently :ref:`tested <testing>` before
submitting.
-- Patches should be `submitted <#submit>`__ via a merge request for
- `review <#reviewing>`__.
+- Patches should be :ref:`submitted <submit>` via a merge request for
+ :ref:`review <reviewing>`.
.. _formatting:
Prefer the full url to just ``Closes: #1``, since the url makes it
easier to get to the bug page from ``git log``
- **Do not use the Fixes: tag for this!** Mesa already uses Fixes for
- something else.
-
-- If a patch addresses a issue introduced with earlier commit, that
- should be noted in the patch comment. For example:
-
- ::
-
- Fixes: d7b3707c612 "util/disk_cache: use stat() to check if entry is a directory"
-
-- You can produce those fixes lines by running
-
- ::
-
- git config --global alias.fixes "show -s --pretty='format:Fixes: %h (\"%s\")'"
-
- once and then using
-
- ::
-
- git fixes <sha1>
+ **Do not use the ``Fixes:`` tag for this!** Mesa already uses
+ ``Fixes:`` for something else.
+ See :ref:`below <fixes>`.
- If there have been several revisions to a patch during the review
process, they should be noted such as in this example:
Reviewed-by: Joe Hacker <jhacker@foo.com>
Acked-by: Joe Hacker <jhacker@foo.com>
-- If sending later revision of a patch, add all the tags - ack, r-b,
- Cc: mesa-stable and/or other. This provides reviewers with quick
- feedback if the patch has already been reviewed.
+- When updating a merge request add all the tags (``Acked-by:``, ``Reviewed-by:``,
+ ``Fixes:``, ``Cc: mesa-stable`` and/or other) to the commit messages.
+ This provides reviewers with quick feedback if the patch has already
+ been reviewed.
+
+.. _fixes:
+
+The ``Fixes:`` tag
+------------------
+
+If a patch addresses a issue introduced with earlier commit, that
+should be noted in the commit message. For example::
+
+ Fixes: d7b3707c612 ("util/disk_cache: use stat() to check if entry is a directory")
+
+You can produce those fixes lines by running this command once::
+
+ git config --global alias.fixes "show -s --pretty='format:Fixes: %h (\"%s\")'"
+
+After that, using ``git fixes <sha1>`` will print the full line for you.
+
+The stable tag
+~~~~~~~~~~~~~~
+
+If you want a commit to be applied to a stable branch, you should add an
+appropriate note to the commit message.
+
+Using a ``Fixes:`` tag as described in :ref:`Patch formatting <formatting>`
+is the preferred way to nominate a commit that should be backported.
+There are scripts that will figure out which releases to apply the patch
+to automatically, so you don't need to figure it out.
+
+Alternatively, you may use a "CC:" tag. Here are some examples of such a
+note::
+
+ Cc: mesa-stable
+ Cc: 20.0 <mesa-stable>
+ CC: 20.0 19.3 <mesa-stable>
+
+Using the CC tag **should** include the stable branches you want to
+nominate the patch to. If you do not provide any version it is nominated
+to all active stable branches.
.. _testing:
appropriate amount of review feedback from people who also understand
the code before merging their patches.
-.. _nominations:
-
Nominating a commit for a stable branch
---------------------------------------
-There are three ways to nominate a patch for inclusion in the stable
-branch and release.
+There are several ways to nominate a patch for inclusion in the stable
+branch and release. In order or preference:
-- By adding the Cc: mesa-stable@ tag as described below.
-- By adding the fixes: tag as described below.
-- By submitting a merge request against the "staging/year.quarter"
- branch on gitlab.
+- By adding the ``Fixes:`` tag in the commit message as described above, if you are fixing
+ a specific commit.
+- By adding the ``Cc: mesa-stable`` tag in the commit message as described above.
+- By submitting a merge request against the ``staging/year.quarter``
+ branch on gitlab.
Please **DO NOT** send patches to mesa-stable@lists.freedesktop.org, it
is not monitored actively and is a historical artifact.
If you are not the author of the original patch, please Cc: them in your
nomination request.
-The current patch status can be observed in the `staging
-branch <releasing.html#stagingbranch>`__.
-
-.. _thetag:
-
-The stable tag
-~~~~~~~~~~~~~~
-
-If you want a commit to be applied to a stable branch, you should add an
-appropriate note to the commit message.
-
-Using a "fixes tag" as described in `Patch formatting <#formatting>`__
-is the preferred way to nominate a commit that you know ahead of time
-should be backported. There are scripts that will figure out which
-releases to apply the patch to automatically, so you don't need to
-figure it out.
-
-Alternatively, you may use a "CC:" tag. Here are some examples of such a
-note:
-
-::
-
- CC: 20.0 19.3 <mesa-stable@lists.freedesktop.org>
-
-Using the CC tag **should** include the stable branches you want to
-nominate the patch to. If you do not provide any version it is nominated
-to all active stable branches.
+The current patch status can be observed in the :ref:`staging
+branch <stagingbranch>`.
.. _criteria:
accepted and which are not. The stable-release manager is also given
broad discretion in rejecting patches that have been nominated.
-- Patch must conform with the `Basic guidelines <#guidelines>`__
+- Patch must conform with the :ref:`Basic guidelines <guidelines>`
- Patch must have landed in master first. In case where the original
patch is too large and/or otherwise contradicts with the rules set
within, a backport is appropriate.
- It must not introduce a regression - be that build or runtime wise.
- Note: If the regression is due to faulty piglit/dEQP/CTS/other test
- the latter must be fixed first. A reference to the offending test(s)
- and respective fix(es) should be provided in the nominated patch.
+
+ .. note::
+ If the regression is due to faulty piglit/dEQP/CTS/other test
+ the latter must be fixed first. A reference to the offending test(s)
+ and respective fix(es) should be provided in the nominated patch.
+
- Patch cannot be larger than 100 lines.
- Patches that move code around with no functional change should be
rejected.
-- Patch must be a bug fix and not a new feature. Note: An exception to
- this rule, are hardware-enabling "features". For example,
- `backports <#backports>`__ of new code to support a newly-developed
- hardware product can be accepted if they can be reasonably determined
- not to have effects on other hardware.
+- Patch must be a bug fix and not a new feature.
+
+ .. note::
+ An exception to this rule, are hardware-enabling "features". For
+ example, :ref:`backports <backports>` of new code to support a
+ newly-developed hardware product can be accepted if they can be
+ reasonably determined not to have effects on other hardware.
+
- Patch must be reviewed, For example, the commit message has
Reviewed-by, Signed-off-by, or Tested-by tags from someone but the
author.
numbers to represent your measurements.
If the patch complies with the rules it will be
-`cherry-picked <releasing.html#pickntest>`__. Alternatively the release
+:ref:`cherry-picked <pickntest>`. Alternatively the release
manager will reply to the patch in question stating why the patch has
been rejected or would request a backport. The stable-release manager
may at times need to force-push changes to the stable branches, for
stable branch policy. Assigning the MR to release maintainer for said
branch or mentioning them is helpful, but not required.
-.. _gittips:
-
Git tips
--------
- ``git rebase -i ...`` is your friend. Don't be afraid to use it.
- Apply a fixup to commit FOO.
- ::
+ .. code-block:: console
git add ...
git commit --fixup=FOO
- Test for build breakage between patches e.g last 8 commits.
- ::
+ .. code-block:: console
git rebase -i --exec="ninja -C build/" HEAD~8
-
-- Sets the default mailing address for your repo.
-
- ::
-
- git config --local sendemail.to mesa-dev@lists.freedesktop.org
-
-- Add version to subject line of patch series in this case for the last
- 8 commits before sending.
-
- ::
-
- git send-email --subject-prefix="PATCH v4" HEAD~8
- git send-email -v4 @~8 # shorter version, inherited from git format-patch