From 081f91469246d0be05a32167bc5773cdd104acfe Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Wed, 3 Feb 2021 14:50:23 +1000 Subject: [PATCH] doc/user: expand the explanations on how to submit a merge request I keep answering this in bug reports, much easier to just have a link to copy/paste. Signed-off-by: Peter Hutterer --- doc/user/contributing.rst | 57 ++++++++++++++++++++++++++++++++++----- 1 file changed, 51 insertions(+), 6 deletions(-) diff --git a/doc/user/contributing.rst b/doc/user/contributing.rst index 3d44a07e..0c4a5c0d 100644 --- a/doc/user/contributing.rst +++ b/doc/user/contributing.rst @@ -149,33 +149,76 @@ Any patches should be sent via a Merge Request (see the `GitLab docs in the `libinput GitLab instance hosted by freedesktop.org `_. -To submit a merge request, you need to +Below are the steps required to submit a merge request. They do not +replace `learning git `__ but they should be +sufficient to make some of the more confusing steps obvious. - `Register an account `_ in the freedesktop.org GitLab instance. - `Fork libinput `_ into your username's namespace -- Get libinput's main repository: :: +- Get libinput's main repository. git will call this repository ``origin``. :: git clone https://gitlab.freedesktop.org/libinput/libinput.git - Add the forked git repository to your remotes (replace ``USERNAME`` - with your username): :: + with your username). git will call this repository ``gitlab``. :: cd /path/to/libinput.git git remote add gitlab git@gitlab.freedesktop.org:USERNAME/libinput.git git fetch gitlab -- Push your changes to your fork: :: +- Create a new branch and commit your changes to that branch. :: - git push gitlab BRANCHNAME + git switch -C mynewbranch + # edit files, make changes + git add file1 file2 + git commit -s + # edit commit message in the editor -- Submit a merge request. The URL for a merge request is: :: + Replace ``mynewbranch`` (here and in the commands below) with a meaningful + name. See :ref:`contributing_commit_messages` for details on the commit + message format. + +- Push your changes to your fork and submit a merge request :: + + git push gitlab mynewbranch + + This command will print the URL to file a merge request, you then only + have to click through. Alternatively you can go to: https://gitlab.freedesktop.org/USERNAME/libinput/merge_requests Select your branch name to merge and ``libinput/libinput`` ``master`` as target branch. +- Verify that the CI completes successfully by visiting the merge request + page. A successful pipeline shows only green ticks, failure is indicated + by a red cross or a yellow exclamation mark (see + the `GitLab Docs + `__). For + details about the failures, click on the failed jobs in the pipelines + and/or click the ``Expand`` button in the box for the test summaries. + + A merge request without a successful pipeline may never be looked at by a + maintainer. + +- If changes are requested by the maintainers, please **amend** the + commit(s) and **force-push** the updated branch. :: + + # edits in file foo.c + git add foo.c + git commit --amend + git push -f gitlab mynewbranch + + A force-push will re-trigger the CI and notify the merge request that new + changes are available. + + If the branch contains more than one commit, please look at + `git interactive rebases + `__ + to learn how to change multiple commits, or squash new changes into older + commits. + ------------------------------------------------------------------------------ Commit History ------------------------------------------------------------------------------ @@ -215,6 +258,8 @@ describes the change. For example: :: If in doubt what prefix to use, look at other commits that change the same file(s) as the patch being sent. +.. _contributing_commit_messages: + ------------------------------------------------------------------------------ Commit Messages ------------------------------------------------------------------------------