[PATCH libinput] doc/user: expand the Contributing document

Fri Aug 10 05:33:42 UTC 2018

This is mostly taken from the Weston Contributing.md document.

Main changes from there are:
- more detailed step-by-step on how to create a MR
- commit history/messages in two sections
- s/Weston/libinput/

I skipped the Review/Commit Rights sections for now until there's some demand
for it. Same with the Licensing/Stabilising for releases sections.

Cc: Daniel Stone <daniels at collabora.com>,
Cc: Pekka Paalanen <pekka.paalanen at collabora.co.uk>,
Cc: Quentin Glidic <sardemff7+git at sardemff7.net>
Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
---
 doc/user/contributing.rst | 177 ++++++++++++++++++++++++++++++++++++--
 1 file changed, 168 insertions(+), 9 deletions(-)

diff --git a/doc/user/contributing.rst b/doc/user/contributing.rst
index 674275932..de34fb6f7 100644
--- a/doc/user/contributing.rst
+++ b/doc/user/contributing.rst
@@ -5,14 +5,173 @@
 Contributing to libinput
 ==============================================================================
 
-Contributions to libinput are always welcome. Any patches should be sent to
-the
-`wayland-devel <https://lists.freedesktop.org/mailman/listinfo/wayland-devel>`_
-email list with a subject prefix of ``[PATCH libinput]``. The easiest
-way to achieve that is to run the following command in the libinput
-repository: ::
+Contributions to libinput are always welcome. Please see the steps below for
+details on how to create merge requests, correct git formatting and other
+topics:
 
-	git config --add format.subjectprefix "PATCH libinput"
+.. contents::
+    :local:
 
-Likewise, any new features should also be discussed publicly on the
-wayland-devel list.
+Questions regarding this process can be asked on ``#wayland-devel`` on
+freenode or on the `wayland-devel at lists.freedesktop.org
+<https://lists.freedesktop.org/mailman/listinfo/wayland-devel>`_ mailing
+list.
+
+.. note:: The content of this document is largely taken from  `Weston's
+	  CONTRIBUTING.md <https://gitlab.freedesktop.org/wayland/weston/blob/master/CONTRIBUTING.md>`_,
+	  many thanks to the authors for their efforts.
+
+------------------------------------------------------------------------------
+Submitting Code
+------------------------------------------------------------------------------
+
+Any patches should be sent via a Merge Request (see the `GitLab docs
+<https://docs.gitlab.com/ce/gitlab-basics/add-merge-request.htm>`_)
+in the `libinput GitLab instance hosted by freedesktop.org
+<https://gitlab.freedesktop.org/libinput/libinput>`_.
+
+To submit a merge request, you need to
+
+- `Register an account <https://gitlab.freedesktop.org/users/sign_in>`_ in
+  the freedesktop.org GitLab instance.
+- `Fork libinput <https://gitlab.freedesktop.org/libinput/libinput/forks/new>`_
+  into your username's namespace
+- Get libinput's main repository: ::
+
+    git clone https://gitlab.freedesktop.org/libinput/libinput.git
+
+- Add the forked git repository to your remotes (replace ``USERNAME``
+  with your username): ::
+
+    cd /path/to/libinput.git
+    git remote add gitlab git at gitlab.freedesktop.org:USERNAME/libinput.git
+    git fetch gitlab
+
+- Push your changes to your fork: ::
+
+    git push gitlab BRANCHNAME
+
+- Submit a merge request. The URL for a merge request is: ::
+
+    https://gitlab.freedesktop.org/USERNAME/libinput/merge_requests
+
+  Select your branch name to merge and ``libinput/libinput`` ``master`` as target branch.
+
+------------------------------------------------------------------------------
+Commit History
+------------------------------------------------------------------------------
+
+libinput strives to have a
+`linear, 'recipe' style history <http://www.bitsnbites.eu/git-history-work-log-vs-recipe/>`_
+This means that every commit should be small, digestible, stand-alone, and
+functional. Rather than a purely chronological commit history like this: ::
+
+	doc: final docs for view transforms
+	fix tests when disabled, redo broken doc formatting
+	better transformed-view iteration (thanks Hannah!)
+	try to catch more cases in tests
+	tests: add new spline test
+	fix compilation on splines
+	doc: notes on reticulating splines
+	compositor: add spline reticulation for view transforms
+
+We aim to have a clean history which only reflects the final state, broken up
+into functional groupings: ::
+
+	compositor: add spline reticulation for view transforms
+	compositor: new iterator for view transforms
+	tests: add view-transform correctness tests
+	doc: fix Doxygen formatting for view transforms
+
+This ensures that the final patch series only contains the final state,
+without the changes and missteps taken along the development process.
+
+The first line of a commit message should contain a prefix indicating
+what part is affected by the patch followed by one sentence that
+describes the change. For example: ::
+
+	touchpad: add software button behavior
+	fallback: disable button debouncing on device foo
+
+If in doubt what prefix to use, look at other commits that change the
+same file(s) as the patch being sent.
+
+------------------------------------------------------------------------------
+Commit Messages
+------------------------------------------------------------------------------
+
+Read `on commit messages <http://who-t.blogspot.de/2009/12/on-commit-messages.html>`_
+as a general guideline on what commit messages should contain.
+
+Commit messages **should** contain a **Signed-off-by** line with your name
+and email address. If you're not the patch's original author, you should
+also gather S-o-b's by them (and/or whomever gave the patch to you.) The
+significance of this is that it certifies that you created the patch, that
+it was created under an appropriate open source license, or provided to you
+under those terms. This lets us indicate a chain of responsibility for the
+copyright status of the code.
+
+We won't reject patches that lack S-o-b, but it is strongly recommended.
+
+When you re-send patches, revised or not, it would be very good to document the
+changes compared to the previous revision in the commit message and/or the
+merge request. If you have already received Reviewed-by or Acked-by tags, you
+should evaluate whether they still apply and include them in the respective
+commit messages. Otherwise the tags may be lost, reviewers miss the credit they
+deserve, and the patches may cause redundant review effort.
+
+------------------------------------------------------------------------------
+Coding Style
+------------------------------------------------------------------------------
+
+Please see the `CODING_STYLE.md
+<https://gitlab.freedesktop.org/libinput/libinput/blob/master/CODING_STYLE.md>`_
+document in the source tree.
+
+------------------------------------------------------------------------------
+Tracking patches and follow-ups
+------------------------------------------------------------------------------
+
+Once submitted to GitLab, your patches will be reviewed by the libinput
+development team on GitLab. Review may be entirely positive and result in your
+code landing instantly, in which case, great! You're done. However, we may ask
+you to make some revisions: fixing some bugs we've noticed, working to a
+slightly different design, or adding documentation and tests.
+
+If you do get asked to revise the patches, please bear in mind the notes above.
+You should use ``git rebase -i`` to make revisions, so that your patches
+follow the clear linear split documented above. Following that split makes
+it easier for reviewers to understand your work, and to verify that the code
+you're submitting is correct.
+
+A common request is to split single large patch into multiple patches. This can
+happen, for example, if when adding a new feature you notice a bug in
+libinput's core which you need to fix to progress. Separating these changes
+into separate commits will allow us to verify and land the bugfix quickly,
+pushing part of your work for the good of everyone, whilst revision and
+discussion continues on the larger feature part. It also allows us to direct
+you towards reviewers who best understand the different areas you are
+working on.
+
+When you have made any requested changes, please rebase the commits, verify
+that they still individually look good, then force-push your new branch to
+GitLab. This will update the merge request and notify everyone subscribed to
+your merge request, so they can review it again.
+
+There are also many GitLab CLI clients, if you prefer to avoid the web
+interface. It may be difficult to follow review comments without using the
+web interface though, so we do recommend using this to go through the review
+process, even if you use other clients to track the list of available
+patches.
+
+------------------------------------------------------------------------------
+Code of Conduct
+------------------------------------------------------------------------------
+
+As a freedesktop.org project, libinput follows the `freedesktop.org
+Contributor Covenant <https://www.freedesktop.org/wiki/CodeOfConduct>`_.
+
+Please conduct yourself in a respectful and civilised manner when
+interacting with community members on mailing lists, IRC, or bug trackers.
+The community represents the project as a whole, and abusive or bullying
+behaviour is not tolerated by the project.
-- 
2.17.1

