diff options
Diffstat (limited to 'docs/submittingpatches.rst')
| -rw-r--r-- | docs/submittingpatches.rst | 80 |
1 files changed, 66 insertions, 14 deletions
diff --git a/docs/submittingpatches.rst b/docs/submittingpatches.rst index 9dd3150295e..3e227270c6f 100644 --- a/docs/submittingpatches.rst +++ b/docs/submittingpatches.rst @@ -100,7 +100,7 @@ Patch formatting Acked-by: Joe Hacker <jhacker@foo.com> - When updating a merge request add all the tags (``Acked-by:``, ``Reviewed-by:``, - ``Fixes:``, ``Cc: mesa-stable`` and/or other) to the commit messages. + ``Fixes:``, ``Backport-to:`` and/or other) to the commit messages. This provides reviewers with quick feedback if the patch has already been reviewed. @@ -131,8 +131,17 @@ 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:: +Alternatively, you may use the ``Backport-to:`` tag, as presented in the +following example:: + + Backport-to: 21.0 + +Multiple ``Backport-to:`` lines are allowed. + +The last option is deprecated and mostly here for historical reasons +dating back to when patch submision was done via emails: using a ``Cc:`` +tag. Support for this tag will be removed at some point. +Here are some examples of such a note:: Cc: mesa-stable Cc: 20.0 <mesa-stable> @@ -165,7 +174,7 @@ to test this is to make use of the \`git rebase\` command, to run your tests on each commit. Assuming your branch is based off ``origin/main``, you can run: -.. code-block:: console +.. code-block:: sh $ git rebase --interactive --exec "meson test -C build/" origin/main @@ -182,8 +191,8 @@ Patches are submitted to the Mesa project via a Add labels to your MR to help reviewers find it. For example: - Mesa changes affecting all drivers: mesa -- Hardware vendor specific code: amd, intel, nvidia, ... -- Driver specific code: anvil, freedreno, i965, iris, radeonsi, radv, +- Hardware vendor specific code: AMD common, intel, ... +- Driver specific code: ANV, freedreno, i965, iris, radeonsi, RADV, vc4, ... - Other tag examples: gallium, util @@ -270,6 +279,34 @@ project. The submitter is expected to evaluate whether they have an appropriate amount of review feedback from people who also understand the code before merging their patches. +.. _merging: + +Merging merge requests +---------------------- + +Once a merge request has been appropriately reviewed, its author can decide to +merge it. + +.. warning:: + Pushing (``git push``) directly to ``main`` is forbidden. This bypasses all + the CI checks and is likely to cause issues for everyone else. + +.. warning:: + Do not use the "Merge"/"Merge when pipeline succeeds"/"Set to auto-merge" + buttons. + +We use a `custom script <https://gitlab.com/marge-org/marge-bot>`__ to manage +this, triggered by **assigning the MR** to the pseudo-user `@marge-bot +<https://gitlab.freedesktop.org/marge-bot>`__. + +Authors who do not have ``Developer`` access (or above) should ask on the +merge request for someone else to do it for them, or reach on +:doc:`other channels <lists>` if the MR reviewers don't have access themselves. + +Do not merge someone else's MR unless you are sure they don't have a new +version that they are testing locally for instance. +**When in doubt, ask**, for instance by leaving a comment on that MR. + Nominating a commit for a stable branch --------------------------------------- @@ -280,7 +317,7 @@ branch and release. In order or preference: 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. + branch on GitLab. Refer to the :ref:`instructions below <backports>`. Please **DO NOT** send patches to mesa-stable@lists.freedesktop.org, it is not monitored actively and is a historical artifact. @@ -310,7 +347,7 @@ broad discretion in rejecting patches that have been nominated. - 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 + 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. @@ -350,15 +387,21 @@ Sending backports for the stable branch By default merge conflicts are resolved by the stable-release manager. The release maintainer should resolve trivial conflicts, but for complex conflicts they should ask the original author to provide a backport or -de-nominate the patch. +denominate the patch. For patches that either need to be nominated after they've landed in main, or that are known ahead of time to not not apply cleanly to a stable branch (such as due to a rename), using a GitLab MR is most appropriate. The MR should be based on and target the -staging/year.quarter branch, not on the year.quarter branch, per the -stable branch policy. Assigning the MR to release maintainer for said -branch or mentioning them is helpful, but not required. +``staging/year.quarter`` branch, not on the ``year.quarter`` branch, +per the stable branch policy. Assigning the MR to release maintainer for +said branch or mentioning them is helpful, but not required. + +Make sure to use ``git cherry-pick -x`` when cherry-picking the commits +from the main branch. This adds the "cherry picked from commit ..." line +to the commit message, to allow the release maintainters to mark those +as backported, which in turn allows the tools to correctly report any +future ``Fixes:`` affecting the commits you backported. Documentation patches --------------------- @@ -366,6 +409,15 @@ Documentation patches Our documentation is written as `reStructuredText`_ files in the :file:`docs` folder, and built using `Sphinx`_. +.. code-block:: sh + + # Install dependencies (adapt for your distro) + apk add coreutils graphviz py3-clang clang-dev musl-dev linux-headers + pip3 install sphinx===5.1.1 mako===1.2.3 hawkmoth===0.16.0 + + # Build docs + sphinx-build -W -b html docs docs-html/ + The preferred language of the documentation is US English. This doesn't mean that everyone is expected to pay close attention to the different English variants, but it does mean someone might @@ -381,7 +433,7 @@ Git tips - ``git rebase -i ...`` is your friend. Don't be afraid to use it. - Apply a fixup to commit FOO. - .. code-block:: console + .. code-block:: sh git add ... git commit --fixup=FOO @@ -389,6 +441,6 @@ Git tips - Test for build breakage between patches e.g last 8 commits. - .. code-block:: console + .. code-block:: sh git rebase -i --exec="ninja -C build/" HEAD~8 |