Thank you for considering contributing to the GLib project!
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.
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:
Please, do not use the issue tracker for support questions. If you have questions on how to use GLib effectively, you can use:
#gtk channel on Matrixglib tag on GNOME's DiscourseYou can also look at the glib tag on Stack Overflow.
The issue tracker is meant to be used for actionable issues only.
You must not open a new public issue for security related concerns.
Instead, see the SECURITY.md documentation.
If you’re reporting a bug make sure to list:
If the issue includes a crash, you should also include:
If the issue includes a memory leak, you should also include:
For small issues, such as:
.gitignore),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.
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:
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.
Many APIs and features may be best implemented in another library, unless they will be useful for a significant number of applications. GLib does not, and cannot, grow its API surface forever. APIs which integrate well with existing GLib API, or which extend it to allow it to be integrated better with other libraries, are more likely to be accepted than self-contained new APIs or features which can easily exist outside of GLib.
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. See the testing policy for more details.
If proposing a large feature or change, it’s better to discuss it (on the #gtk Matrix channel or on Discourse before putting time into writing an actionable issue — and certainly before putting time into writing a merge request.
If you want to contribute to the GLib project, you will need to have the development tools appropriate for your operating system, including:
Up-to-date instructions about developing GNOME applications and libraries can be found on the GNOME Developer Center.
The GLib project uses GitLab for code hosting and for tracking issues. More information about using GitLab can be found on the GNOME wiki.
You should start by forking the GLib repository from the GitLab web UI, and cloning from your fork:
$ git clone https://gitlab.gnome.org/yourusername/glib.git $ cd glib
To compile the Git version of GLib on your system, you will need to configure your build using Meson:
$ meson setup _builddir . $ meson compile -C _builddir
Typically, you should work on your own branch:
$ 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.
Each contribution is reviewed by the core developers of the GLib project.
The CODEOWNERS 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 by spreading knowledge of each commit between at least two people.
With each code review, we intend to:
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 Matrix, to ask for a second opinion.
The expected format for git commit messages is as follows:
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 <joe@coder.org>" and --signoff.
If your commit is addressing an issue, use the GitLab syntax to automatically close the issue when merging the commit with the upstream repository:
Closes #1234 Fixes #1234 Closes: https://gitlab.gnome.org/GNOME/glib/issues/1234
Bug: #1234, and use the automatic issue closing syntax in the description of the merge request.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:
Never push to the main 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.
Always get a code review, even for seemingly trivial changes.
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.