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>`__.
+ conventions <codingstyle.rst>`__.
- Whenever possible, patches should only affect individual Mesa/Gallium
components.
- Patches should never introduce build breaks and should be bisectable
something else.
- If a patch addresses a issue introduced with earlier commit, that
- should be noted in the patch comment. For example:
+ should be noted in the commit message. For 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.
.. _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 below.
+- 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.
nomination request.
The current patch status can be observed in the `staging
-branch <releasing.html#stagingbranch>`__.
-
-.. _thetag:
+branch <releasing.rst#stagingbranch>`__.
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.
+Using a ``Fixes:`` tag as described in `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: 20.0 19.3 <mesa-stable@lists.freedesktop.org>
+ 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
numbers to represent your measurements.
If the patch complies with the rules it will be
-`cherry-picked <releasing.html#pickntest>`__. Alternatively the release
+`cherry-picked <releasing.rst#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
projects / mesa.git / blobdiff