From 99d9758d90a88b92fc8fcdb447aa7ab4abe1c1cb Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Wed, 3 Oct 2018 16:30:04 +0100 Subject: Use Markdown for documentation Signed-off-by: Simon McVittie --- CONTRIBUTING | 110 -------------------------------------------------------- CONTRIBUTING.md | 110 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Makefile.am | 4 +-- README | 49 ------------------------- README.md | 51 ++++++++++++++++++++++++++ 5 files changed, 163 insertions(+), 161 deletions(-) delete mode 100644 CONTRIBUTING create mode 100644 CONTRIBUTING.md delete mode 100644 README create mode 100644 README.md diff --git a/CONTRIBUTING b/CONTRIBUTING deleted file mode 100644 index 5bbcee1..0000000 --- a/CONTRIBUTING +++ /dev/null @@ -1,110 +0,0 @@ -# Contributing to dbus-gmain - -dbus-gmain is hosted by freedesktop.org. The source code repository, -issue tracking and merge requests are provided by freedesktop.org's -Gitlab installation, as a branch in the dbus-glib project: - - -## Making changes - -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. - -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. - -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. - -The lines of the commit message should have at most 76 characters, -to cope with the way git log presents them. - -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. - -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 - on freedesktop.org Gitlab -* push your changes to your personal fork as a branch -* create a merge request at - , - and remember to specify `dbus-gmain` as the target branch - -## Automated tests - -For nontrivial changes please try to extend the test suite to cover it. -dbus-gmain uses GLib's test framework; tests are in the `tests/` -directory. - -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 - -As a freedesktop.org project, dbus follows the Contributor Covenant, -found at: - -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. - -## (Lack of) versioning and releases - -dbus-gmain is currently set up to be a git subtree or git submodule, -so it does not have releases in its own right. It gets merged or -otherwise included in larger projects like dbus-glib and dbus-python -instead. - -## Information for maintainers - -This section is not directly relevant to infrequent contributors. - -### Updating the copies of dbus-gmain in dbus-glib and dbus-python - -dbus-gmain is maintained via `git subtree`. To update one of the dependent -projects, 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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..5bbcee1 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,110 @@ +# Contributing to dbus-gmain + +dbus-gmain is hosted by freedesktop.org. The source code repository, +issue tracking and merge requests are provided by freedesktop.org's +Gitlab installation, as a branch in the dbus-glib project: + + +## Making changes + +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. + +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. + +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. + +The lines of the commit message should have at most 76 characters, +to cope with the way git log presents them. + +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. + +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 + on freedesktop.org Gitlab +* push your changes to your personal fork as a branch +* create a merge request at + , + and remember to specify `dbus-gmain` as the target branch + +## Automated tests + +For nontrivial changes please try to extend the test suite to cover it. +dbus-gmain uses GLib's test framework; tests are in the `tests/` +directory. + +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 + +As a freedesktop.org project, dbus follows the Contributor Covenant, +found at: + +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. + +## (Lack of) versioning and releases + +dbus-gmain is currently set up to be a git subtree or git submodule, +so it does not have releases in its own right. It gets merged or +otherwise included in larger projects like dbus-glib and dbus-python +instead. + +## Information for maintainers + +This section is not directly relevant to infrequent contributors. + +### Updating the copies of dbus-gmain in dbus-glib and dbus-python + +dbus-gmain is maintained via `git subtree`. To update one of the dependent +projects, 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. diff --git a/Makefile.am b/Makefile.am index cc46f6e..3e60286 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,8 +1,8 @@ EXTRA_DIST = \ AUTHORS \ - CONTRIBUTING \ + CONTRIBUTING.md \ COPYING \ - README \ + README.md \ $(NULL) AM_CPPFLAGS = \ diff --git a/README b/README deleted file mode 100644 index ee14484..0000000 --- a/README +++ /dev/null @@ -1,49 +0,0 @@ -dbus-gmain - GLib main loop integration for libdbus -=================================================== - -This directory contains GLib main loop integration for libdbus, salvaged -from dbus-glib. At the moment it is designed to be bundled in other -projects using the `git subtree` or `git submodule` commands. - -Please do not use this module unless you really need it. The majority -of GLib-based D-Bus users would be better off using GDBus, part of GLib, -instead of the low-level APIs provided by libdbus. In particular, the -combination of dbus-gmain and libdbus is known to have thread-safety -issues. - -However, using this module is still better than using dbus-glib; the -rest of dbus-glib mostly consists of design flaws. - -Integrating dbus-gmain in a larger project ------------------------------------------- - -dbus-gmain requires libdbus >= 1.8. This can be reduced to some ancient -version if you don't build the tests. - -dbus-gmain requires GLib >= 2.40. This can be reduced to 2.32, or -probably older, if you don't build the tests. - -If you use the included Makefile.am (which requires building the tests), -you must check for libdbus via pkg-config using the prefix "DBUS", check -for GLib (and optionally gobject and gio) via pkg-config using the prefix -"GLIB", and check for DBUS_RUN_SESSION for the tests: - -PKG_CHECK_MODULES([DBUS], [dbus-1 >= 1.8]) -PKG_CHECK_MODULES([GLIB], [glib-2.0 >= 2.40]) -AC_ARG_VAR([DBUS_RUN_SESSION], - [The dbus-run-session tool from dbus 1.8 or later]) -AC_PATH_PROG([DBUS_RUN_SESSION], [dbus-run-session], [dbus-run-session]) - -Alternatively, you can include dbus-gmain.[ch] among the source files for -some executable or library. - -By default, dbus-gmain declares its functions in the dbus_gmain_* -namespace. To change this, define DBUS_GMAIN_FUNCTION_NAME(name) to -a suitably prefixed or suffixed version of name. The default is -"dbus_gmain_ ## name". - -By default, dbus-gmain declares its functions G_GNUC_INTERNAL, so they -will not be part of your library's ABI on supported compilers. To change -this (not recommended), define DBUS_GMAIN_FUNCTION(ret, name, ...) to -a form that includes suitable decorators. The default is -"G_GNUC_INTERNAL ret DBUS_GMAIN_FUNCTION_NAME (name) (__VA_ARGS__)". diff --git a/README.md b/README.md new file mode 100644 index 0000000..8f40161 --- /dev/null +++ b/README.md @@ -0,0 +1,51 @@ +dbus-gmain - GLib main loop integration for libdbus +=================================================== + +This directory contains GLib main loop integration for libdbus, salvaged +from dbus-glib. At the moment it is designed to be bundled in other +projects using the `git subtree` or `git submodule` commands. + +Please do not use this module unless you really need it. The majority +of GLib-based D-Bus users would be better off using GDBus, part of GLib, +instead of the low-level APIs provided by libdbus. In particular, the +combination of dbus-gmain and libdbus is known to have thread-safety +issues. + +However, using this module is still better than using dbus-glib; the +rest of dbus-glib mostly consists of design flaws. + +Integrating dbus-gmain in a larger project +------------------------------------------ + +dbus-gmain requires libdbus >= 1.8. This can be reduced to some ancient +version if you don't build the tests. + +dbus-gmain requires GLib >= 2.40. This can be reduced to 2.32, or +probably older, if you don't build the tests. + +If you use the included Makefile.am (which requires building the tests), +you must check for libdbus via pkg-config using the prefix `DBUS`, check +for GLib (and optionally gobject and gio) via pkg-config using the prefix +`GLIB`, and check for `DBUS_RUN_SESSION` for the tests: + +``` +PKG_CHECK_MODULES([DBUS], [dbus-1 >= 1.8]) +PKG_CHECK_MODULES([GLIB], [glib-2.0 >= 2.40]) +AC_ARG_VAR([DBUS_RUN_SESSION], + [The dbus-run-session tool from dbus 1.8 or later]) +AC_PATH_PROG([DBUS_RUN_SESSION], [dbus-run-session], [dbus-run-session]) +``` + +Alternatively, you can include dbus-gmain.[ch] among the source files for +some executable or library. + +By default, dbus-gmain declares its functions in the `dbus_gmain_`\* +namespace. To change this, define `DBUS_GMAIN_FUNCTION_NAME(name)` to +a suitably prefixed or suffixed version of name. The default is +`dbus_gmain_ ## name`. + +By default, dbus-gmain declares its functions `G_GNUC_INTERNAL`, so they +will not be part of your library's ABI on supported compilers. To change +this (not recommended), define `DBUS_GMAIN_FUNCTION(ret, name, ...)` to +a form that includes suitable decorators. The default is +`G_GNUC_INTERNAL ret DBUS_GMAIN_FUNCTION_NAME (name) (__VA_ARGS__)`. -- cgit v1.2.1