CONTRIBUTING.md 9.65 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# Contribution guidelines

Thank you for considering contributing to the GTK project!

These guidelines are meant for new contributors, regardless of their level
of proficiency; following them allows the maintainers of the GTK 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 GTK put into
managing the project.

GTK is a complex free software GUI toolkit, and it would not exist without
contributions from the free and open source software community. There are
many things that we value:

 - bug reporting and fixing
 - documentation and examples
 - tests
 - new features

Please, do not use the issue tracker for support questions. If you have
questions on how to use GTK effectively, you can use:

24
 - the `#gtk` IRC channel on irc.gnome.org
Matthias Clasen's avatar
Matthias Clasen committed
25
 - the [gtk tag on the GNOME Discourse instance](https://discourse.gnome.org/tag/gtk)
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

You can also look at the GTK tag on [Stack
Overflow](https://stackoverflow.com/questions/tagged/gtk).

The issue tracker is meant to be used for actionable issues only.

## How to report bugs

### Security issues

You should not open a new issue for security related questions.

When in doubt, send an email to the [security](mailto:security@gnome.org)
mailing list.

### Bug reports

If you're reporting a bug make sure to list:

 0. which version of GTK are you using?
 0. which operating system are you using?
 0. the necessary steps to reproduce the issue
 0. the expected outcome
 0. a description of the behavior; screenshots are also welcome
 0. a small, self-contained example exhibiting the behavior; if this
    is not available, try reproducing the issue using the GTK examples
    or interactive tests

If the issue includes a crash, you should also include:

 0. the eventual warnings printed on the terminal
 0. a backtrace, obtained with tools such as GDB or LLDB

Matthias Clasen's avatar
Matthias Clasen committed
59
60
61
62
63
64
It is fine to include screenshots of screen recordings to demonstrate
an issue that is best to understand visually, but please don't just
dump screen recordings without further details into issues. It is
essential that the problem is described in enough detail to reproduce
it without watching a video.

65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
For small issues, such as:

 - spelling/grammar fixes in the documentation
 - typo correction
 - comment clean ups
 - changes to metadata files (CI, `.gitignore`)
 - build system changes
 - source tree clean ups and reorganizations

You should directly open a merge request instead of filing a new issue.

### Features and enhancements

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:

 0. what you're trying to achieve
 0. prior art, in other toolkits or applications
 0. design and theming changes

If you're proposing the integration of new features it helps to have
multiple applications using shared or similar code, especially if they have
iterated over it various times.

Each feature should also come fully documented, and with tests.

## Your first contribution

### Prerequisites

If you want to contribute to the GTK project, you will need to have the
development tools appropriate for your operating system, including:
98

99
100
101
102
 - Python 3.x
 - Meson
 - Ninja
 - Gettext (19.7 or newer)
103
 - a [C99 compatible compiler](https://wiki.gnome.org/Projects/GLib/CompilerRequirements)
104
105

Up-to-date instructions about developing GNOME applications and libraries
106
can be found on [the GNOME Developer Center](https://developer.gnome.org).
107

108
109
110
The GTK project uses GitLab for code hosting and for tracking issues. More
information about using GitLab can be found [on the GNOME
wiki](https://wiki.gnome.org/GitLab).
111

112
### Dependencies
113

114
In order to get GTK from Git installed on your system, you need to have the
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
required versions of all the software dependencies required by GTK; typically,
this means a recent version of GLib, Cairo, Pango, and ATK, as well as the
platform-specific dependencies for the windowing system you are using (Wayland,
X11, Windows, or macOS).

The core dependencies for GTK are:

 - [GLib, GObject, and GIO](https://gitlab.gnome.org/GNOME/glib)
 - [Cairo](http://cairographics.org)
 - [Pango](https://gitlab.gnome.org/GNOME/pango)
 - [GdkPixbuf](https://gitlab.gnome.org/GNOME/gdk-pixbuf)
 - [Epoxy](https://github.com/anholt/libepoxy)
 - [ATK](https://gitlab.gnome.org/GNOME/atk)
 - [Graphene](https://github.com/ebassi/graphene)

GTK will attempt to download and build some of these dependencies if it
cannot find them on your system.

Additionally, you may want to look at projects that create a development
environment for you, like [jhbuild](https://wiki.gnome.org/HowDoI/Jhbuild)
and [gvsbuild](https://github.com/wingtk/gvsbuild).
136

137
138
### Getting started

Emmanuele Bassi's avatar
Emmanuele Bassi committed
139
140
141
You should start by forking the GTK repository from the GitLab web UI, and
cloning from your fork:

142
```sh
Emmanuele Bassi's avatar
Emmanuele Bassi committed
143
144
145
146
147
148
$ git clone https://gitlab.gnome.org/yourusername/gtk.git
$ cd gtk
```

**Note**: if you plan to push changes to back to the main repository and
have a GNOME account, you can skip the fork, and use the following instead:
149
150

```sh
Emmanuele Bassi's avatar
Emmanuele Bassi committed
151
152
$ git clone git@gitlab.gnome.org:GNOME/gtk.git
$ cd gtk
153
154
```

155
To compile the Git version of GTK on your system, you will need to
156
157
158
159
configure your build using Meson:

```sh
$ meson _builddir .
Emmanuele Bassi's avatar
Emmanuele Bassi committed
160
161
162
163
164
165
166
167
$ cd _builddir
$ ninja
```

Typically, you should work on your own branch:

```sh
$ git checkout -b your-branch
168
169
```

Emmanuele Bassi's avatar
Emmanuele Bassi committed
170
171
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 GTK
172
173
174
175
176
177
maintainers review your contribution.

### Code reviews

Each contribution is reviewed by the core developers of the GTK project.

Timm Bäder's avatar
Timm Bäder committed
178
The [CODEOWNERS](./docs/CODEOWNERS) document contains the list of core
179
180
contributors to GTK and the areas for which they are responsible; you
should ensure to receive their review and signoff on your changes.
181
182
183
184
185
186
187
188
189
190
191
192

### Commit messages

The expected format for git commit messages is as follows:

```plain
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.
193
194

Closes #1234
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
```

 - 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`.

215
216
217
218
 - If your commit is addressing an issue, use the
 [GitLab syntax](https://docs.gitlab.com/ce/user/project/issues/automatic_issue_closing.html)
 to automatically close the issue when merging the commit with the upstream
 repository:
219
220
221
222

```plain
Closes #1234
Fixes #1234
223
Closes: https://gitlab.gnome.org/GNOME/gtk/issues/1234
224
225
```

226
227
228
229
230
 - If you have a merge request with multiple commits and none of them
 completely fixes an issue, you should add a reference to the issue in
 the commit message, e.g. `Bug: #1234`, and use the automatic issue
 closing syntax in the description of the merge request.

231
### Commit access to the GTK repository
232

233
234
235
236
237
GTK is part of the GNOME infrastructure. At the current time, any
person with write access to the GNOME repository can merge changes to
GTK. This is a good thing, in that it encourages many people to work
on GTK, and progress can be made quickly. However, GTK is a fairly
large and complicated project on which many other things depend, so to
238
avoid unnecessary breakage, and to take advantage of the knowledge
239
240
about GTK that has been built up over the years, we'd like to ask
people committing to GTK to follow a few rules:
241
242

0. Ask first. If your changes are major, or could possibly break existing
243
244
245
246
247
248
   code, you should always ask. If your change is minor and you've been
   working on GTK for a while it probably isn't necessary to ask. But when
   in doubt, ask. Even if your change is correct, somebody may know a
   better way to do things. If you are making changes to GTK, you should
   be subscribed to the [gtk-devel](https://mail.gnome.org/mailman/listinfo/gtk-devel-list)
   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
252
   zones, an email to the gtk-devel mailing list is the most certain and
   preferred method.
253
254
255
256
257
258

0. Ask _first_.

0. Always write a meaningful commit message. Changes without a sufficient
   commit message will be reverted.

259
0. Never push to the `main` branch, or any stable branches, directly; you
260
261
262
263
   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 GTK.
264
265
266
267

If you have been contributing to GTK for a while and you don't have commit
access to the repository, you may ask to obtain it following the [GNOME account
process](https://wiki.gnome.org/AccountsTeam/NewAccounts).