CONTRIBUTING.md

   1 # Contribution guidelines
   2
   3 Thank you for considering contributing to the GLib project!
   4
   5 These guidelines are meant for new contributors, regardless of their level
   6 of proficiency; following them allows the core developers of the GLib project to
   7 more effectively evaluate your contribution, and provide prompt feedback to
   8 you. Additionally, by following these guidelines you clearly communicate
   9 that you respect the time and effort that the people developing GLib put into
  10 managing the project.
  11
  12 GLib is a complex free software utility library, and it would not exist without
  13 contributions from the free and open source software community. There are
  14 many things that we value:
  15
  16  - bug reporting and fixing
  17  - documentation and examples
  18  - tests
  19  - testing and support for other platforms
  20  - new features
  21
  22 Please, do not use the issue tracker for support questions. If you have
  23 questions on how to use GLib effectively, you can use:
  24
  25  - the `#gtk+` IRC channel on irc.gnome.org
  26  - the [gtk](https://mail.gnome.org/mailman/listinfo/gtk-list) mailing list,
  27    for general questions on GLib
  28  - the [gtk-devel](https://mail.gnome.org/mailman/listinfo/gtk-devel-list)
  29    mailing list, for questions on developing GLib itself
  30
  31 You can also look at the [`glib` tag on Stack
  32 Overflow](https://stackoverflow.com/questions/tagged/glib).
  33
  34 The issue tracker is meant to be used for actionable issues only.
  35
  36 ## How to report bugs
  37
  38 ### Security issues
  39
  40 You should not open a new issue for security related questions.
  41
  42 When in doubt, send an email to the [security](mailto:security@gnome.org)
  43 mailing list.
  44
  45 ### Bug reports
  46
  47 If you’re reporting a bug make sure to list:
  48
  49  0. which version of GLib are you using?
  50  0. which operating system are you using?
  51  0. the necessary steps to reproduce the issue
  52  0. the expected outcome
  53  0. a description of the behavior
  54  0. a small, self-contained example exhibiting the behavior
  55
  56 If the issue includes a crash, you should also include:
  57
  58  0. the eventual warnings printed on the terminal
  59  0. a backtrace, obtained with tools such as GDB or LLDB
  60
  61 If the issue includes a memory leak, you should also include:
  62
  63  0. a log of definite leaks from a tool such as [valgrind’s
  64     memcheck](http://valgrind.org/docs/manual/mc-manual.html)
  65
  66 For small issues, such as:
  67
  68  - spelling/grammar fixes in the documentation,
  69  - typo correction,
  70  - comment clean ups,
  71  - changes to metadata files (CI, `.gitignore`),
  72  - build system changes, or
  73  - source tree clean ups and reorganizations;
  74
  75 or for self-contained bug fixes where you have implemented and tested a solution
  76 already, you should directly open a merge request instead of filing a new issue.
  77
  78 ### Features and enhancements
  79
  80 Feature discussion can be open ended and require high bandwidth channels; if
  81 you are proposing a new feature on the issue tracker, make sure to make
  82 an actionable proposal, and list:
  83
  84  0. what you’re trying to achieve and the problem it solves
  85  0. three (or more) existing pieces of software which would benefit from the
  86     new feature
  87  0. how the feature is implementable on platforms other than Linux
  88
  89 New APIs, in particular, should follow the ‘rule of three’, where there should
  90 be three (or more) pieces of software which are ready to use the new APIs. This
  91 allows us to check that the new APIs are usable in real-life code, and fit well
  92 with related APIs. This reduces the chances of awkward or unusable APIs becoming
  93 stable in GLib and having to be supported forever.
  94
  95 A common way to introduce new APIs or data types to GLib is to prototype them in
  96 another code base for a while, to gain real-life experience with them before
  97 they are imported into GLib and marked as stable.
  98
  99 Each feature should also come fully documented, and with tests which approach
 100 full branch coverage of the new code. GLib’s CI system generates code coverage
 101 reports which are viewable for each merge request.
 102
 103 If proposing a large feature or change, it’s better to discuss it (on the
 104 `#gtk+` IRC channel or on the
 105 [gtk-devel](https://mail.gnome.org/mailman/listinfo/gtk-devel-list) mailing
 106 list) before putting time into writing an actionable issue — and certainly
 107 before putting time into writing a merge request.
 108
 109 ## Your first contribution
 110
 111 ### Prerequisites
 112
 113 If you want to contribute to the GLib project, you will need to have the
 114 development tools appropriate for your operating system, including:
 115
 116  - Python 3.x
 117  - Meson
 118  - Ninja
 119  - Gettext (19.7 or newer)
 120  - a [C99 compatible compiler](https://wiki.gnome.org/Projects/GLib/CompilerRequirements)
 121
 122 Up-to-date instructions about developing GNOME applications and libraries
 123 can be found on [the GNOME Developer Center](https://developer.gnome.org).
 124
 125 The [GLib project uses GitLab](https://gitlab.gnome.org/GNOME/glib/) for code
 126 hosting and for tracking issues. More information about using GitLab can be
 127 found [on the GNOME wiki](https://wiki.gnome.org/GitLab).
 128
 129 ### Getting started
 130
 131 You should start by forking the GLib repository from the GitLab web UI, and
 132 cloning from your fork:
 133
 134 ```sh
 135 $ git clone https://gitlab.gnome.org/yourusername/glib.git
 136 $ cd glib
 137 ```
 138
 139 **Note**: if you plan to push changes to back to the main repository and
 140 have a GNOME account, you can skip the fork, and use the following instead:
 141
 142 ```sh
 143 $ git clone git@gitlab.gnome.org:GNOME/glib.git
 144 $ cd glib
 145 ```
 146
 147 To compile the Git version of GLib on your system, you will need to
 148 configure your build using Meson:
 149
 150 ```sh
 151 $ meson _builddir .
 152 $ cd _builddir
 153 $ ninja
 154 ```
 155
 156 Typically, you should work on your own branch:
 157
 158 ```sh
 159 $ git checkout -b your-branch
 160 ```
 161
 162 Once you’ve finished working on the bug fix or feature, push the branch
 163 to the Git repository and open a new merge request, to let the GLib
 164 core developers review your contribution.
 165
 166 ### Code reviews
 167
 168 Each contribution is reviewed by the core developers of the GLib project.
 169
 170 The [CODE-OWNERS](./docs/CODE-OWNERS) document contains the list of core
 171 contributors to GLib and the areas for which they are responsible; you
 172 should ensure to receive their review and signoff on your changes.
 173
 174 It is our intention that every commit to GLib is reviewed by at least one other
 175 person, including commits from core developers. We all make mistakes and can
 176 always learn from each other, and code review allows that. It also reduces
 177 [bus factor](https://en.wikipedia.org/wiki/Bus_factor) by spreading knowledge
 178 of each commit between at least two people.
 179
 180 With each code review, we intend to:
 181
 182  0. Identify if this is a desirable change or new feature. Ideally for larger
 183     features this will have been discussed (in an issue, on IRC, or on the
 184     mailing list) already, so that effort isn’t wasted on putting together merge
 185     requests which will be rejected.
 186  0. Check the design of any new API.
 187  0. Provide realistic estimates of how long a review might take, if it can’t
 188     happen immediately.
 189  0. Ensure that all significant contributions of new code, or bug fixes, are
 190     adequately tested, either through requiring tests to be submitted at the
 191     same time, or as a follow-up.
 192  0. Ensure that all new APIs are documented and have [introspection
 193     annotations](https://wiki.gnome.org/Projects/GObjectIntrospection/Annotations).
 194  0. Check that the contribution is split into logically separate commits, each
 195     with a good commit message.
 196  0. Encourage further high quality contributions.
 197  0. Ensure code style and quality is upheld.
 198
 199 If a code review is stalled (due to not receiving comments for two or more
 200 weeks; or due to a technical disagreement), please ping another GLib core
 201 developer on the merge request, or on IRC, to ask for a second opinion.
 202
 203 ### Commit messages
 204
 205 The expected format for git commit messages is as follows:
 206
 207 ```plain
 208 Short explanation of the commit
 209
 210 Longer explanation explaining exactly what’s changed, whether any
 211 external or private interfaces changed, what bugs were fixed (with bug
 212 tracker reference if applicable) and so forth. Be concise but not too
 213 brief.
 214
 215 Closes #1234
 216 ```
 217
 218  - Always add a brief description of the commit to the _first_ line of
 219  the commit and terminate by two newlines (it will work without the
 220  second newline, but that is not nice for the interfaces).
 221
 222  - First line (the brief description) must only be one sentence and
 223  should start with a capital letter unless it starts with a lowercase
 224  symbol or identifier. Don’t use a trailing period either. Don’t exceed
 225  72 characters.
 226
 227  - The main description (the body) is normal prose and should use normal
 228  punctuation and capital letters where appropriate. Consider the commit
 229  message as an email sent to the developers (or yourself, six months
 230  down the line) detailing **why** you changed something. There’s no need
 231  to specify the **how**: the changes can be inlined.
 232
 233  - When committing code on behalf of others use the `--author` option, e.g.
 234  `git commit -a --author "Joe Coder <joe@coder.org>"` and `--signoff`.
 235
 236  - If your commit is addressing an issue, use the
 237  [GitLab syntax](https://docs.gitlab.com/ce/user/project/issues/automatic_issue_closing.html)
 238  to automatically close the issue when merging the commit with the upstream
 239  repository:
 240
 241 ```plain
 242 Closes #1234
 243 Fixes #1234
 244 Closes: https://gitlab.gnome.org/GNOME/glib/issues/1234
 245 ```
 246
 247  - If you have a merge request with multiple commits and none of them
 248  completely fixes an issue, you should add a reference to the issue in
 249  the commit message, e.g. `Bug: #1234`, and use the automatic issue
 250  closing syntax in the description of the merge request.
 251
 252 ### Merge access to the GLib repository
 253
 254 GLib is part of the GNOME infrastructure. At the current time, any
 255 person with write access to the GNOME repository can merge merge requests to
 256 GLib. This is a good thing, in that it allows maintainership to be delegated
 257 and shared as needed. However, GLib is a fairly large and complicated package
 258 that many other things depend on, and which has platform specific behavior — so
 259 to avoid unnecessary breakage, and to take advantage of the knowledge about GLib
 260 that has been built up over the years, we’d like to ask people contributing to
 261 GLib to follow a few rules:
 262
 263 0. Never push to the `master` branch, or any stable branches, directly; you
 264    should always go through a merge request, to ensure that the code is
 265    tested on the CI infrastructure at the very least. A merge request is
 266    also the proper place to get a comprehensive code review from the core
 267    developers of GLib.
 268
 269 0. Always get a code review, even for seemingly trivial changes.
 270
 271 0. Pay attention to the CI results. Merge requests cannot be merged until the
 272    CI passes. If they consistently fail, either something is wrong with the
 273    change, or the CI tests need fixing — in either case, please bring this to
 274    the attention of a core developer rather than overriding the CI.
 275
 276 If you have been contributing to GLib for a while and you don’t have commit
 277 access to the repository, you may ask to obtain it following the [GNOME account
 278 process](https://wiki.gnome.org/AccountsTeam/NewAccounts).