diff options
| -rw-r--r-- | CONTRIBUTING.md | 165 |
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). |