1# Contribution guidelines 2 3Thank you for considering contributing to the GTK project! 4 5These guidelines are meant for new contributors, regardless of their level 6of proficiency; following them allows the maintainers of the GTK 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 GTK put into 10managing the project. 11 12GTK is a complex free software GUI toolkit, 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 - new features 20 21Please, do not use the issue tracker for support questions. If you have 22questions on how to use GTK effectively, you can use: 23 24 - the `#gtk` IRC channel on irc.gnome.org 25 - the [gtk tag on the GNOME Discourse instance](https://discourse.gnome.org/tag/gtk) 26 27You can also look at the GTK tag on [Stack 28Overflow](https://stackoverflow.com/questions/tagged/gtk). 29 30The issue tracker is meant to be used for actionable issues only. 31 32## How to report bugs 33 34### Security issues 35 36You should not open a new issue for security related questions. 37 38When in doubt, send an email to the [security](mailto:security@gnome.org) 39mailing list. 40 41### Bug reports 42 43If you're reporting a bug make sure to list: 44 45 0. which version of GTK 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; screenshots are also welcome 50 0. a small, self-contained example exhibiting the behavior; if this 51 is not available, try reproducing the issue using the GTK examples 52 or interactive tests 53 54If the issue includes a crash, you should also include: 55 56 0. the eventual warnings printed on the terminal 57 0. a backtrace, obtained with tools such as GDB or LLDB 58 59It is fine to include screenshots of screen recordings to demonstrate 60an issue that is best to understand visually, but please don't just 61dump screen recordings without further details into issues. It is 62essential that the problem is described in enough detail to reproduce 63it without watching a video. 64 65For small issues, such as: 66 67 - spelling/grammar fixes in the documentation 68 - typo correction 69 - comment clean ups 70 - changes to metadata files (CI, `.gitignore`) 71 - build system changes 72 - source tree clean ups and reorganizations 73 74You should directly open a merge request instead of filing a new issue. 75 76### Features and enhancements 77 78Feature discussion can be open ended and require high bandwidth channels; if 79you are proposing a new feature on the issue tracker, make sure to make 80an actionable proposal, and list: 81 82 0. what you're trying to achieve 83 0. prior art, in other toolkits or applications 84 0. design and theming changes 85 86If you're proposing the integration of new features it helps to have 87multiple applications using shared or similar code, especially if they have 88iterated over it various times. 89 90Each feature should also come fully documented, and with tests. 91 92## Your first contribution 93 94### Prerequisites 95 96If you want to contribute to the GTK project, you will need to have the 97development tools appropriate for your operating system, including: 98 99 - Python 3.x 100 - Meson 101 - Ninja 102 - Gettext (19.7 or newer) 103 - a [C99 compatible compiler](https://wiki.gnome.org/Projects/GLib/CompilerRequirements) 104 105Up-to-date instructions about developing GNOME applications and libraries 106can be found on [the GNOME Developer Center](https://developer.gnome.org). 107 108The GTK project uses GitLab for code hosting and for tracking issues. More 109information about using GitLab can be found [on the GNOME 110wiki](https://wiki.gnome.org/GitLab). 111 112### Dependencies 113 114In order to get GTK from Git installed on your system, you need to have the 115required versions of all the software dependencies required by GTK; typically, 116this means a recent version of GLib, Cairo, Pango, and ATK, as well as the 117platform-specific dependencies for the windowing system you are using (Wayland, 118X11, Windows, or macOS). 119 120The core dependencies for GTK are: 121 122 - [GLib, GObject, and GIO](https://gitlab.gnome.org/GNOME/glib) 123 - [Cairo](http://cairographics.org) 124 - [Pango](https://gitlab.gnome.org/GNOME/pango) 125 - [GdkPixbuf](https://gitlab.gnome.org/GNOME/gdk-pixbuf) 126 - [Epoxy](https://github.com/anholt/libepoxy) 127 - [ATK](https://gitlab.gnome.org/GNOME/atk) 128 - [Graphene](https://github.com/ebassi/graphene) 129 130GTK will attempt to download and build some of these dependencies if it 131cannot find them on your system. 132 133Additionally, you may want to look at projects that create a development 134environment for you, like [jhbuild](https://wiki.gnome.org/HowDoI/Jhbuild) 135and [gvsbuild](https://github.com/wingtk/gvsbuild). 136 137### Getting started 138 139You should start by forking the GTK repository from the GitLab web UI, and 140cloning from your fork: 141 142```sh 143$ git clone https://gitlab.gnome.org/yourusername/gtk.git 144$ cd gtk 145``` 146 147**Note**: if you plan to push changes to back to the main repository and 148have a GNOME account, you can skip the fork, and use the following instead: 149 150```sh 151$ git clone git@gitlab.gnome.org:GNOME/gtk.git 152$ cd gtk 153``` 154 155To compile the Git version of GTK on your system, you will need to 156configure your build using Meson: 157 158```sh 159$ meson _builddir . 160$ cd _builddir 161$ ninja 162``` 163 164Typically, you should work on your own branch: 165 166```sh 167$ git checkout -b your-branch 168``` 169 170Once you've finished working on the bug fix or feature, push the branch 171to the Git repository and open a new merge request, to let the GTK 172maintainers review your contribution. 173 174### Code reviews 175 176Each contribution is reviewed by the core developers of the GTK project. 177 178The [CODEOWNERS](./docs/CODEOWNERS) document contains the list of core 179contributors to GTK and the areas for which they are responsible; you 180should ensure to receive their review and signoff on your changes. 181 182### Commit messages 183 184The expected format for git commit messages is as follows: 185 186```plain 187Short explanation of the commit 188 189Longer explanation explaining exactly what's changed, whether any 190external or private interfaces changed, what bugs were fixed (with bug 191tracker reference if applicable) and so forth. Be concise but not too 192brief. 193 194Closes #1234 195``` 196 197 - Always add a brief description of the commit to the _first_ line of 198 the commit and terminate by two newlines (it will work without the 199 second newline, but that is not nice for the interfaces). 200 201 - First line (the brief description) must only be one sentence and 202 should start with a capital letter unless it starts with a lowercase 203 symbol or identifier. Don't use a trailing period either. Don't exceed 204 72 characters. 205 206 - The main description (the body) is normal prose and should use normal 207 punctuation and capital letters where appropriate. Consider the commit 208 message as an email sent to the developers (or yourself, six months 209 down the line) detailing **why** you changed something. There's no need 210 to specify the **how**: the changes can be inlined. 211 212 - When committing code on behalf of others use the `--author` option, e.g. 213 `git commit -a --author "Joe Coder <joe@coder.org>"` and `--signoff`. 214 215 - If your commit is addressing an issue, use the 216 [GitLab syntax](https://docs.gitlab.com/ce/user/project/issues/automatic_issue_closing.html) 217 to automatically close the issue when merging the commit with the upstream 218 repository: 219 220```plain 221Closes #1234 222Fixes #1234 223Closes: https://gitlab.gnome.org/GNOME/gtk/issues/1234 224``` 225 226 - If you have a merge request with multiple commits and none of them 227 completely fixes an issue, you should add a reference to the issue in 228 the commit message, e.g. `Bug: #1234`, and use the automatic issue 229 closing syntax in the description of the merge request. 230 231### Commit access to the GTK repository 232 233GTK is part of the GNOME infrastructure. At the current time, any 234person with write access to the GNOME repository can merge changes to 235GTK. This is a good thing, in that it encourages many people to work 236on GTK, and progress can be made quickly. However, GTK is a fairly 237large and complicated project on which many other things depend, so to 238avoid unnecessary breakage, and to take advantage of the knowledge 239about GTK that has been built up over the years, we'd like to ask 240people committing to GTK to follow a few rules: 241 2420. Ask first. If your changes are major, or could possibly break existing 243 code, you should always ask. If your change is minor and you've been 244 working on GTK for a while it probably isn't necessary to ask. But when 245 in doubt, ask. Even if your change is correct, somebody may know a 246 better way to do things. If you are making changes to GTK, you should 247 be subscribed to the [gtk-devel](https://mail.gnome.org/mailman/listinfo/gtk-devel-list) 248 mailing list; this is a good place to ask about intended changes. 249 The `#gtk` IRC channel on irc.gnome.org is also a good place to find GTK 250 developers to discuss changes, but if you live outside of the EU/US time 251 zones, an email to the gtk-devel mailing list is the most certain and 252 preferred method. 253 2540. Ask _first_. 255 2560. Always write a meaningful commit message. Changes without a sufficient 257 commit message will be reverted. 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 GTK. 264 265If you have been contributing to GTK for a while and you don't have commit 266access to the repository, you may ask to obtain it following the [GNOME account 267process](https://wiki.gnome.org/AccountsTeam/NewAccounts). 268