CONTRIBUTING.md: Rewrite

This file hadn't kept up with reality, and needs updating for Gitlab.
Take the opportunity to rewrite it.

Much of the text here was taken from Wayland's contributing guide
(thanks to Ander Conselvan de Oliveira, Bryce Harrington,
Eric Engestrom, Pekka Paalanen and Daniel Stone).

Signed-off-by: Simon McVittie <smcv@collabora.com>

1 files changed, 116 insertions, 49 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index bebc685..a8bd21a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,80 +1,147 @@
-The mainline git tree for this code is at
-git://anongit.freedesktop.org/git/dbus/dbus-glib.
+# Contributing to dbus-glib
 
-= Creating changes =
+The short version is "don't". Please contribute to (and use) a better
+project instead, for example GDBus in GLib's GIO module.
 
-Be sure to match the existing code style (Emacs: "gnu").
+However, if you are really sure that dbus-glib is the project to which
+you want to be contributing, read on.
 
-If you are making major changes which you wish to be incorporated upstream,
-please do as small commits to your local git tree, so there is a good
-history of your changes.
+## Source code repository and issue tracking
 
-When you consider changes ready for merging to mainline, use 
-"git-format-patch" or otherwise generate unified diffs.  Post those diffs
-to a new bug at http://bugs.freedesktop.org, project DBus, component GLib.
+dbus-glib is hosted by freedesktop.org. The source code repository,
+issue tracking and merge requests are provided by freedesktop.org's
+Gitlab installation: <https://gitlab.freedesktop.org/dbus/dbus-glib>
 
-For nontrivial changes *please* try to extend the test suite to cover it.  The
-test infrastructure is in test/core/. If possible, use a GTester-style test
-like registrations.c; or if necessary, add things to the giant catch-all
-test, test-dbus-glib.c.
+## Making changes
 
-Run "make check" to run the test suite.
+If you are making changes that you wish to be incorporated upstream,
+please do as small commits to your local git tree that are individually
+correct, so there is a good history of your changes.
 
-= dbus-gmain =
+The first line of the commit message should be a single sentence that
+describes the change, optionally with a prefix that identifies the
+area of the code that is affected.
 
-dbus-gmain is maintained via `git subtree`. To update, assuming you have
-a checkout of the dbus-gmain branch of the dbus-glib repository in
-../dbus-gmain:
+The body of the commit message should describe what the patch changes
+and why, and also note any particular side effects. This shouldn't be
+empty on most of the cases. It shouldn't take a lot of effort to write a
+commit message for an obvious change, so an empty commit message body is
+only acceptable if the questions "What?" and "Why?" are already answered
+on the one-line summary.
 
-    git subtree pull -P dbus-gmain ../dbus-gmain HEAD
+The lines of the commit message should have at most 76 characters,
+to cope with the way git log presents them.
 
-= Committing =
+See [notes on commit messages](https://who-t.blogspot.com/2009/12/on-commit-messages.html),
+[A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
+or [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
+for recommended reading on writing high-quality commit messages.
 
-If applying a patch from someone else that created them via 
-"git-format-patch", you can use "git-am -s" to apply.  Otherwise
-apply the patch and then use "git commit --author ..."
+Your patches should also include a Signed-off-by line with your name and
+email address, indicating that your contribution follows the [Developer's
+Certificate of Origin](https://developercertificate.org/). 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 consider changes ready for merging to mainline:
+
+* create a personal fork of <https://gitlab.freedesktop.org/dbus/dbus-glib>
+  on freedesktop.org Gitlab
+* push your changes to your personal fork as a branch
+* create a merge request at
+  <https://gitlab.freedesktop.org/dbus/dbus-glib/merge_requests>
+
+## Automated tests
+
+For nontrivial changes please try to extend the test suite to cover it.  The
+test infrastructure is in `test/core/`. If possible, use a GTester-style test
+like `registrations.c`; or if necessary, add things to the giant catch-all
+test, `test-dbus-glib.c`.
+
+Run `make check` to run the test suite.
+
+## Coding style
+
+Please match the existing code style (Emacs: "gnu").
+
+## Licensing
+
+Please match the existing licensing (a dual-license: AFL-2.1 or GPL-2+,
+recipient's choice). Entirely new modules can be placed under a more
+permissive license: to avoid license proliferation, our preferred
+permissive license is the variant of the MIT/X11 license used by the
+Expat XML library (for example see the top of tools/ci-build.sh).
+
+## Conduct
 
-Regardless:
+As a freedesktop.org project, dbus follows the Contributor Covenant,
+found at: <https://www.freedesktop.org/wiki/CodeOfConduct>
 
-== Nontrivial changes ==
-Nontrivial patches should always go through Bugzilla for peer review, so
-you should have a bug number.  The commit should be of the form:
+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.
 
-Bug XXXXXX: Single line summary here
+## Versioning
 
-	* dbus/filename.c: Why I changed this.
-	* dbus/otherfile.c: Why I changed this.
+Version 0.N, where *N* is even (divisible by 2), is a real release.
 
-== Trivial changes ==
+Point releases can be versioned 0.N.M where *N* is even and *M* is
+any number greater than zero.
 
-Just use a single line summary, like:
+Version 0.(N+1), where *N* is even (divisible by 2), identifies a
+development snapshot leading to version 0.(N+2). Odd-numbered versions
+should never be used as releases.
 
-Fix typo in NEWS
+## Information for maintainers
 
-= Making a release =
+This section is not directly relevant to infrequent contributors.
 
-DBus-Glib now uses an even-stable odd-development release numbering
-system.  The current number in configure.ac should be odd.
+### dbus-gmain
+
+dbus-gmain is maintained via `git subtree`. To update, assuming you have
+a checkout of the dbus-gmain branch of the dbus-glib repository in
+../dbus-gmain:
+
+    git subtree pull -P dbus-gmain ../dbus-gmain HEAD
+
+### Committing other people's patches
+
+If applying a patch from someone else that created them via
+"git-format-patch", you can use "git-am -s" to apply.  Otherwise
+apply the patch and then use "git commit --author ..."
+
+Nontrivial patches should always go through Gitlab for peer review,
+so you should have an issue number or a merge request ID to refer to.
+
+### Making a release
+
+dbus-glib uses an even-stable odd-development release numbering
+system. The current number in configure.ac should be odd, except
+when releasing.
 
 To make a release (please replace use of 0.76 with the new version)
 
 * make
 * make distcheck
 * edit configure.ac, change version to even (e.g. 0.75 -> 0.76)
-* also in configure.ac, update LT_CURRENT, LT_REVISION and LT_AGE
+* also in configure.ac, update `LT_CURRENT`, `LT_REVISION` and `LT_AGE`
 * edit NEWS, summarize notable changes since the last release
-* ./autogen.sh
-* make
-* make distcheck
-* sign the tarball (or use: make dbus-glib-0.76.tar.gz.asc)
-* make maintainer-upload-release
-* git commit -m "Release"
-* git tag -a dbus-glib_0.76
+* `./autogen.sh`
+* `make`
+* `make distcheck`
+* sign the tarball (or use: `make dbus-glib-0.76.tar.gz.asc`)
+* `make maintainer-upload-release`
+* `git commit -m "Release"`
+* `git tag -a dbus-glib_0.76`
 * edit configure.ac, change version to odd (e.g. 0.76 -> 0.77)
-* git commit -m "Bump version for development"
+* `git commit -m "Bump version for development"`
 * Update the wiki: http://www.freedesktop.org/wiki/Software/DBusBindings
 * Announce the release on the mailing list, quoting the notable changes
   from NEWS.
-
-NEWS is now maintained again (Simon finds it easier this way, and he
-does most of the releases).