1 # Contribution guidelines
3 Thank you for considering contributing to the GLib project!
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
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:
16 - bug reporting and fixing
17 - documentation and examples
19 - testing and support for other platforms
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:
25 - the `#gtk` channel on [Matrix](https://wiki.gnome.org/GettingInTouch/Matrix)
26 - the [`glib` tag on GNOME's Discourse](https://discourse.gnome.org/tags/glib)
28 You can also look at the [`glib` tag on Stack
29 Overflow](https://stackoverflow.com/questions/tagged/glib).
31 The issue tracker is meant to be used for actionable issues only.
37 You **must not** open a new public issue for security related concerns.
39 Instead, see the [`SECURITY.md` documentation](./SECURITY.md).
43 If you’re reporting a bug make sure to list:
45 0. which version of GLib are you using?
46 0. which operating system are you using?
47 0. the necessary steps to reproduce the issue
48 0. the expected outcome
49 0. a description of the behavior
50 0. a small, self-contained example exhibiting the behavior
52 If the issue includes a crash, you should also include:
54 0. the eventual warnings printed on the terminal
55 0. a backtrace, obtained with tools such as GDB or LLDB
57 If the issue includes a memory leak, you should also include:
59 0. a log of definite leaks from a tool such as [valgrind’s
60 memcheck](http://valgrind.org/docs/manual/mc-manual.html)
62 For small issues, such as:
64 - spelling/grammar fixes in the documentation,
67 - changes to metadata files (CI, `.gitignore`),
68 - build system changes, or
69 - source tree clean ups and reorganizations;
71 or for self-contained bug fixes where you have implemented and tested a solution
72 already, you should directly open a merge request instead of filing a new issue.
74 ### Features and enhancements
76 Feature discussion can be open ended and require high bandwidth channels; if
77 you are proposing a new feature on the issue tracker, make sure to make
78 an actionable proposal, and list:
80 0. what you’re trying to achieve and the problem it solves
81 0. three (or more) existing pieces of software which would benefit from the
83 0. how the feature is implementable on platforms other than Linux
85 New APIs, in particular, should follow the ‘rule of three’, where there should
86 be three (or more) pieces of software which are ready to use the new APIs. This
87 allows us to check that the new APIs are usable in real-life code, and fit well
88 with related APIs. This reduces the chances of awkward or unusable APIs becoming
89 stable in GLib and having to be supported forever.
91 A common way to introduce new APIs or data types to GLib is to prototype them in
92 another code base for a while, to gain real-life experience with them before
93 they are imported into GLib and marked as stable.
95 Many APIs and features may be best implemented in another library, unless they
96 will be useful for a significant number of applications. GLib does not, and
97 cannot, grow its API surface forever. APIs which integrate well with existing
98 GLib API, or which extend it to allow it to be integrated better with other
99 libraries, are more likely to be accepted than self-contained new APIs or
100 features which can easily exist outside of GLib.
102 Each feature should also come fully documented, and with tests which approach
103 full branch coverage of the new code. GLib’s CI system generates code coverage
104 reports which are viewable for each merge request. See
105 [the testing policy](./docs/testing.md) for more details.
107 If proposing a large feature or change, it’s better to discuss it (on the
108 `#gtk` Matrix channel or on [Discourse](https://discourse.gnome.org) before
109 putting time into writing an actionable issue — and certainly before putting
110 time into writing a merge request.
112 ## Your first contribution
116 If you want to contribute to the GLib project, you will need to have the
117 development tools appropriate for your operating system, including:
122 - Gettext (19.7 or newer)
123 - a [C99 compatible compiler](./docs/toolchain-requirements.md)
125 Up-to-date instructions about developing GNOME applications and libraries
126 can be found on [the GNOME Developer Center](https://developer.gnome.org).
128 The [GLib project uses GitLab](https://gitlab.gnome.org/GNOME/glib/) for code
129 hosting and for tracking issues. More information about using GitLab can be
130 found [on the GNOME wiki](https://wiki.gnome.org/GitLab).
134 You should start by forking the GLib repository from the GitLab web UI, and
135 cloning from your fork:
138 $ git clone https://gitlab.gnome.org/yourusername/glib.git
142 To compile the Git version of GLib on your system, you will need to
143 configure your build using Meson:
146 $ meson setup _builddir .
147 $ meson compile -C _builddir
150 Typically, you should work on your own branch:
153 $ git checkout -b your-branch
156 Once you’ve finished working on the bug fix or feature, push the branch
157 to the Git repository and open a new merge request, to let the GLib
158 core developers review your contribution.
162 Each contribution is reviewed by the core developers of the GLib project.
164 The [CODEOWNERS](./docs/CODEOWNERS) document contains the list of core
165 contributors to GLib and the areas for which they are responsible; you
166 should ensure to receive their review and signoff on your changes.
168 It is our intention that every commit to GLib is reviewed by at least one other
169 person, including commits from core developers. We all make mistakes and can
170 always learn from each other, and code review allows that. It also reduces
171 [bus factor](https://en.wikipedia.org/wiki/Bus_factor) by spreading knowledge
172 of each commit between at least two people.
174 With each code review, we intend to:
176 0. Identify if this is a desirable change or new feature. Ideally for larger
177 features this will have been discussed (in an issue, on Matrix, or on Discourse)
178 already, so that effort isn’t wasted on putting together merge requests
179 which will be rejected.
180 0. Check the design of any new API.
181 0. Provide realistic estimates of how long a review might take, if it can’t
183 0. Ensure that all significant contributions of new code, or bug fixes, are
184 adequately tested, either through requiring tests to be submitted at the
185 same time, or as a follow-up.
186 0. Ensure that all new APIs are documented and have [introspection
187 annotations](https://gi.readthedocs.io/en/latest/annotations/giannotations.html).
188 0. Check that the contribution is split into logically separate commits, each
189 with a good commit message.
190 0. Encourage further high quality contributions.
191 0. Ensure code style and quality is upheld.
193 If a code review is stalled (due to not receiving comments for two or more
194 weeks; or due to a technical disagreement), please ping another GLib core
195 developer on the merge request, or on Matrix, to ask for a second opinion.
199 The expected format for git commit messages is as follows:
202 Short explanation of the commit
204 Longer explanation explaining exactly what’s changed, whether any
205 external or private interfaces changed, what bugs were fixed (with bug
206 tracker reference if applicable) and so forth. Be concise but not too
212 - Always add a brief description of the commit to the _first_ line of
213 the commit and terminate by two newlines (it will work without the
214 second newline, but that is not nice for the interfaces).
216 - First line (the brief description) must only be one sentence and
217 should start with a capital letter unless it starts with a lowercase
218 symbol or identifier. Don’t use a trailing period either. Don’t exceed
221 - The main description (the body) is normal prose and should use normal
222 punctuation and capital letters where appropriate. Consider the commit
223 message as an email sent to the developers (or yourself, six months
224 down the line) detailing **why** you changed something. There’s no need
225 to specify the **how**: the changes can be inlined.
227 - When committing code on behalf of others use the `--author` option, e.g.
228 `git commit -a --author "Joe Coder <joe@coder.org>"` and `--signoff`.
230 - If your commit is addressing an issue, use the
231 [GitLab syntax](https://docs.gitlab.com/ce/user/project/issues/automatic_issue_closing.html)
232 to automatically close the issue when merging the commit with the upstream
238 Closes: https://gitlab.gnome.org/GNOME/glib/issues/1234
241 - If you have a merge request with multiple commits and none of them
242 completely fixes an issue, you should add a reference to the issue in
243 the commit message, e.g. `Bug: #1234`, and use the automatic issue
244 closing syntax in the description of the merge request.
246 ### Merge access to the GLib repository
248 GLib is part of the GNOME infrastructure. At the current time, any
249 person with write access to the GNOME repository can merge merge requests to
250 GLib. This is a good thing, in that it allows maintainership to be delegated
251 and shared as needed. However, GLib is a fairly large and complicated package
252 that many other things depend on, and which has platform specific behavior — so
253 to avoid unnecessary breakage, and to take advantage of the knowledge about GLib
254 that has been built up over the years, we’d like to ask people contributing to
255 GLib to follow a few rules:
257 0. Never push to the `main` branch, or any stable branches, directly; you
258 should always go through a merge request, to ensure that the code is
259 tested on the CI infrastructure at the very least. A merge request is
260 also the proper place to get a comprehensive code review from the core
263 0. Always get a code review, even for seemingly trivial changes.
265 0. Pay attention to the CI results. Merge requests cannot be merged until the
266 CI passes. If they consistently fail, either something is wrong with the
267 change, or the CI tests need fixing — in either case, please bring this to
268 the attention of a core developer rather than overriding the CI.
270 If you have been contributing to GLib for a while and you don’t have commit
271 access to the repository, you may ask to obtain it following the [GNOME account
272 process](https://wiki.gnome.org/Infrastructure/NewAccounts).