egl: always compile surfaceless

[mesa.git] / docs / submittingpatches.rst

diff --git a/docs/submittingpatches.rst b/docs/submittingpatches.rst
index 56149ac5bcb9f81986fd05896d58c4a5c3447533..98398d972ab63d74a53ef82798446d90abe747d7 100644 (file)
--- a/docs/submittingpatches.rst
+++ b/docs/submittingpatches.rst
@@ -1,22 +1,24 @@
 Submitting Patches
 ==================
 
 Submitting Patches
 ==================
 

+.. _guidelines:
+

 Basic guidelines
 ----------------
 
 -  Patches should not mix code changes with code formatting changes
    (except, perhaps, in very trivial cases.)
 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``.)
 -  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.
    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:
 
 
 .. _formatting:
 


@@ -60,27 +62,9 @@ Patch formatting
    Prefer the full url to just ``Closes: #1``, since the url makes it
    easier to get to the bug page from ``git log``
 
    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:
 
 -  If there have been several revisions to a patch during the review
    process, they should be noted such as in this example:


@@ -115,9 +99,46 @@ Patch formatting
       Reviewed-by: Joe Hacker <jhacker@foo.com>
       Acked-by: Joe Hacker <jhacker@foo.com>
 
       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: 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:
 
 
 .. _testing:
 


@@ -250,13 +271,14 @@ the code before merging their patches.
 Nominating a commit for a stable branch
 ---------------------------------------
 
 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.
 
 Please **DO NOT** send patches to mesa-stable@lists.freedesktop.org, it
 is not monitored actively and is a historical artifact.


@@ -264,31 +286,8 @@ 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.
 
 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>`__.
-
-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:
 
 
 .. _criteria:
 


@@ -302,7 +301,7 @@ mechanism described above. The following rules define which patches are
 accepted and which are not. The stable-release manager is also given
 broad discretion in rejecting patches that have been nominated.
 
 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.
 -  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.


@@ -320,7 +319,7 @@ broad discretion in rejecting patches that have been nominated.
 
    .. note::
       An exception to this rule, are hardware-enabling "features". For
 
    .. note::
       An exception to this rule, are hardware-enabling "features". For

-      example, `backports <#backports>`__ of new code to support a
+      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.
 
       newly-developed hardware product can be accepted if they can be
       reasonably determined not to have effects on other hardware.
 


@@ -332,7 +331,7 @@ broad discretion in rejecting patches that have been nominated.
    numbers to represent your measurements.
 
 If the patch complies with the rules it will be
    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
 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


@@ -376,17 +375,3 @@ Git tips
    .. code-block:: console
 
       git rebase -i --exec="ninja -C build/" HEAD~8
    .. code-block:: console
 
       git rebase -i --exec="ninja -C build/" HEAD~8

-
--  Sets the default mailing address for your repo.
-
-   .. code-block:: console
-
-      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.
-
-   .. code-block:: console
-
-      git send-email --subject-prefix="PATCH v4" HEAD~8
-      git send-email -v4 @~8 # shorter version, inherited from git format-patch