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