From 91493db48ba14f6442a66f212079e808d5390e53 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Fri, 28 Dec 2018 18:33:00 +0000 Subject: [PATCH] docs: Rewrite CONTRIBUTING.md to update it The new version is significantly based on the proposed GTK+ CONTRIBUTING.md file (https://gitlab.gnome.org/GNOME/gtk/merge_requests/358). Signed-off-by: Philip Withnall --- CONTRIBUTING.md | 313 +++++++++++++++++++++++++++++++++++++++-------- docs/CODE-OWNERS | 2 + 2 files changed, 266 insertions(+), 49 deletions(-) create mode 100644 docs/CODE-OWNERS diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 242e3151b..5495fec27 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,63 +1,278 @@ -GLib is part of the GNOME git repository. At the current time, any -person with write access to the GNOME repository, can make changes to -GLib. This is a good thing, in that it encourages many people to work -on GLib, and progress can be made quickly. However, GLib is a fairly -large and complicated package that many other things depend on, so to -avoid unnecessary breakage, and to take advantage of the knowledge -about GLib that has been built up over the years, we'd like to ask -people committing to GLib to follow a few rules: +# Contribution guidelines -1. Ask first. If your changes are major, or could possibly break existing - code, you should always ask. If your change is minor and you've - been working on GLib for a while it probably isn't necessary - to ask. But when in doubt, ask. Even if your change is correct, - somebody may know a better way to do things. +Thank you for considering contributing to the GLib project! - If you are making changes to GLib, you should be subscribed - to `gtk-devel-list@gnome.org`. (Subscription address: - `gtk-devel-list-request@gnome.org`.) This is a good place to ask - about intended changes. +These guidelines are meant for new contributors, regardless of their level +of proficiency; following them allows the core developers of the GLib project to +more effectively evaluate your contribution, and provide prompt feedback to +you. Additionally, by following these guidelines you clearly communicate +that you respect the time and effort that the people developing GLib put into +managing the project. - `#gtk+` on GIMPNet (`irc.gimp.org`, `irc.us.gimp.org`, `irc.eu.gimp.org`, …) - is also a good place to find GTK+ developers to discuss changes with, - however, email to `gtk-devel-list` is the most certain and preferred - method. +GLib is a complex free software utility library, and it would not exist without +contributions from the free and open source software community. There are +many things that we value: -2. Ask _first_. + - bug reporting and fixing + - documentation and examples + - tests + - testing and support for other platforms + - new features -3. You are expected to produce a meaningful commit message. - Changes without a sufficient commit message will be reverted. See below for - the expected format of commit messages. +Please, do not use the issue tracker for support questions. If you have +questions on how to use GLib effectively, you can use: -Notes: + - the `#gtk+` IRC channel on irc.gnome.org + - the [gtk](https://mail.gnome.org/mailman/listinfo/gtk-list) mailing list, + for general questions on GLib + - the [gtk-devel](https://mail.gnome.org/mailman/listinfo/gtk-devel-list) + mailing list, for questions on developing GLib itself -* When developing larger features or complicated bug fixes, it is - advisable to work in a branch in your own cloned GLib repository. - You may even consider making your repository publically available - so that others can easily test and review your changes. +You can also look at the [`glib` tag on Stack +Overflow](https://stackoverflow.com/questions/tagged/glib). -* The expected format for git commit messages is as follows: +The issue tracker is meant to be used for actionable issues only. - ``` - Short explanation of the commit +## How to report bugs - Longer explanation explaining exactly what's changed, whether any - external or private interfaces changed, what bugs were fixed (with bug - tracker reference if applicable) and so forth. Be concise but not too brief. - ``` +### Security issues - - Always add a brief description of the commit to the _first_ line of - the commit and terminate by two newlines (it will work without the - second newline, but that is not nice for the interfaces). +You should not open a new issue for security related questions. - - First line (the brief description) must only be one sentence and - should start with a capital letter unless it starts with a lowercase - symbol or identifier. Don't use a trailing period either. Don't exceed - 72 characters. +When in doubt, send an email to the [security](mailto:security@gnome.org) +mailing list. - - The main description (the body) is normal prose and should use normal - punctuation and capital letters where appropriate. Normally, for patches - sent to a mailing list it's copied from there. +### Bug reports - - When committing code on behalf of others use the `--author` option, e.g. - `git commit -a --author "Joe Coder "` and `--signoff`. +If you’re reporting a bug make sure to list: + + 0. which version of GLib are you using? + 0. which operating system are you using? + 0. the necessary steps to reproduce the issue + 0. the expected outcome + 0. a description of the behavior + 0. a small, self-contained example exhibiting the behavior + +If the issue includes a crash, you should also include: + + 0. the eventual warnings printed on the terminal + 0. a backtrace, obtained with tools such as GDB or LLDB + +If the issue includes a memory leak, you should also include: + + 0. a log of definite leaks from a tool such as [valgrind’s + memcheck](http://valgrind.org/docs/manual/mc-manual.html) + +For small issues, such as: + + - spelling/grammar fixes in the documentation, + - typo correction, + - comment clean ups, + - changes to metadata files (CI, `.gitignore`), + - build system changes, or + - source tree clean ups and reorganizations; + +or for self-contained bug fixes where you have implemented and tested a solution +already, you should directly open a merge request instead of filing a new issue. + +### Features and enhancements + +Feature discussion can be open ended and require high bandwidth channels; if +you are proposing a new feature on the issue tracker, make sure to make +an actionable proposal, and list: + + 0. what you’re trying to achieve and the problem it solves + 0. three (or more) existing pieces of software which would benefit from the + new feature + 0. how the feature is implementable on platforms other than Linux + +New APIs, in particular, should follow the ‘rule of three’, where there should +be three (or more) pieces of software which are ready to use the new APIs. This +allows us to check that the new APIs are usable in real-life code, and fit well +with related APIs. This reduces the chances of awkward or unusable APIs becoming +stable in GLib and having to be supported forever. + +A common way to introduce new APIs or data types to GLib is to prototype them in +another code base for a while, to gain real-life experience with them before +they are imported into GLib and marked as stable. + +Each feature should also come fully documented, and with tests which approach +full branch coverage of the new code. GLib’s CI system generates code coverage +reports which are viewable for each merge request. + +If proposing a large feature or change, it’s better to discuss it (on the +`#gtk+` IRC channel or on the +[gtk-devel](https://mail.gnome.org/mailman/listinfo/gtk-devel-list) mailing +list) before putting time into writing an actionable issue — and certainly +before putting time into writing a merge request. + +## Your first contribution + +### Prerequisites + +If you want to contribute to the GLib project, you will need to have the +development tools appropriate for your operating system, including: + + - Python 3.x + - Meson + - Ninja + - Gettext (19.7 or newer) + - a [C99 compatible compiler](https://wiki.gnome.org/Projects/GLib/CompilerRequirements) + +Up-to-date instructions about developing GNOME applications and libraries +can be found on [the GNOME Developer Center](https://developer.gnome.org). + +The [GLib project uses GitLab](https://gitlab.gnome.org/GNOME/glib/) for code +hosting and for tracking issues. More information about using GitLab can be +found [on the GNOME wiki](https://wiki.gnome.org/GitLab). + +### Getting started + +You should start by forking the GLib repository from the GitLab web UI, and +cloning from your fork: + +```sh +$ git clone https://gitlab.gnome.org/yourusername/glib.git +$ cd glib +``` + +**Note**: if you plan to push changes to back to the main repository and +have a GNOME account, you can skip the fork, and use the following instead: + +```sh +$ git clone git@gitlab.gnome.org:GNOME/glib.git +$ cd glib +``` + +To compile the Git version of GLib on your system, you will need to +configure your build using Meson: + +```sh +$ meson _builddir . +$ cd _builddir +$ ninja +``` + +Typically, you should work on your own branch: + +```sh +$ git checkout -b your-branch +``` + +Once you’ve finished working on the bug fix or feature, push the branch +to the Git repository and open a new merge request, to let the GLib +core developers review your contribution. + +### Code reviews + +Each contribution is reviewed by the core developers of the GLib project. + +The [CODE-OWNERS](./docs/CODE-OWNERS) document contains the list of core +contributors to GLib and the areas for which they are responsible; you +should ensure to receive their review and signoff on your changes. + +It is our intention that every commit to GLib is reviewed by at least one other +person, including commits from core developers. We all make mistakes and can +always learn from each other, and code review allows that. It also reduces +[bus factor](https://en.wikipedia.org/wiki/Bus_factor) by spreading knowledge +of each commit between at least two people. + +With each code review, we intend to: + + 0. Identify if this is a desirable change or new feature. Ideally for larger + features this will have been discussed (in an issue, on IRC, or on the + mailing list) already, so that effort isn’t wasted on putting together merge + requests which will be rejected. + 0. Check the design of any new API. + 0. Provide realistic estimates of how long a review might take, if it can’t + happen immediately. + 0. Ensure that all significant contributions of new code, or bug fixes, are + adequately tested, either through requiring tests to be submitted at the + same time, or as a follow-up. + 0. Ensure that all new APIs are documented and have [introspection + annotations](https://wiki.gnome.org/Projects/GObjectIntrospection/Annotations). + 0. Check that the contribution is split into logically separate commits, each + with a good commit message. + 0. Encourage further high quality contributions. + 0. Ensure code style and quality is upheld. + +If a code review is stalled (due to not receiving comments for two or more +weeks; or due to a technical disagreement), please ping another GLib core +developer on the merge request, or on IRC, to ask for a second opinion. + +### Commit messages + +The expected format for git commit messages is as follows: + +```plain +Short explanation of the commit + +Longer explanation explaining exactly what’s changed, whether any +external or private interfaces changed, what bugs were fixed (with bug +tracker reference if applicable) and so forth. Be concise but not too +brief. + +Closes #1234 +``` + + - Always add a brief description of the commit to the _first_ line of + the commit and terminate by two newlines (it will work without the + second newline, but that is not nice for the interfaces). + + - First line (the brief description) must only be one sentence and + should start with a capital letter unless it starts with a lowercase + symbol or identifier. Don’t use a trailing period either. Don’t exceed + 72 characters. + + - The main description (the body) is normal prose and should use normal + punctuation and capital letters where appropriate. Consider the commit + message as an email sent to the developers (or yourself, six months + down the line) detailing **why** you changed something. There’s no need + to specify the **how**: the changes can be inlined. + + - When committing code on behalf of others use the `--author` option, e.g. + `git commit -a --author "Joe Coder "` and `--signoff`. + + - If your commit is addressing an issue, use the + [GitLab syntax](https://docs.gitlab.com/ce/user/project/issues/automatic_issue_closing.html) + to automatically close the issue when merging the commit with the upstream + repository: + +```plain +Closes #1234 +Fixes #1234 +Closes: https://gitlab.gnome.org/GNOME/glib/issues/1234 +``` + + - If you have a merge request with multiple commits and none of them + completely fixes an issue, you should add a reference to the issue in + the commit message, e.g. `Bug: #1234`, and use the automatic issue + closing syntax in the description of the merge request. + +### Merge access to the GLib repository + +GLib is part of the GNOME infrastructure. At the current time, any +person with write access to the GNOME repository can merge merge requests to +GLib. This is a good thing, in that it allows maintainership to be delegated +and shared as needed. However, GLib is a fairly large and complicated package +that many other things depend on, and which has platform specific behavior — so +to avoid unnecessary breakage, and to take advantage of the knowledge about GLib +that has been built up over the years, we’d like to ask people contributing to +GLib to follow a few rules: + +0. Never push to the `master` branch, or any stable branches, directly; you + should always go through a merge request, to ensure that the code is + tested on the CI infrastructure at the very least. A merge request is + also the proper place to get a comprehensive code review from the core + developers of GLib. + +0. Always get a code review, even for seemingly trivial changes. + +0. Pay attention to the CI results. Merge requests cannot be merged until the + CI passes. If they consistently fail, either something is wrong with the + change, or the CI tests need fixing — in either case, please bring this to + the attention of a core developer rather than overriding the CI. + +If you have been contributing to GLib for a while and you don’t have commit +access to the repository, you may ask to obtain it following the [GNOME account +process](https://wiki.gnome.org/AccountsTeam/NewAccounts). diff --git a/docs/CODE-OWNERS b/docs/CODE-OWNERS new file mode 100644 index 000000000..03943cbb8 --- /dev/null +++ b/docs/CODE-OWNERS @@ -0,0 +1,2 @@ +Currently, all code is maintained equally by the core maintainers. +See glib.doap for their names. \ No newline at end of file