CONTRIBUTING.md 4.24 KB
Newer Older
Christian Hergert's avatar
Christian Hergert committed
1 2 3 4 5 6
# Contributing to GNOME Builder

We would love for you to contribute to GNOME Builder!

GNOME Builder is a new IDE focusing on the GNOME desktop environment. It is
primarily written in C, but allows for plugins in C, C++, Python or Vala.
CHHAVI GARG's avatar
CHHAVI GARG committed
7
Additional compiled languages can also be supported with some work.
Christian Hergert's avatar
Christian Hergert committed
8

CHHAVI GARG's avatar
CHHAVI GARG committed
9
Remember that the GNOME community is largely made up of part-time contributors
Christian Hergert's avatar
Christian Hergert committed
10 11 12 13
that do this for fun. Be respectful and assume the best of each other.

## Filing a bug

CHHAVI GARG's avatar
CHHAVI GARG committed
14
Please file bugs for issues, enhancements and features on
15
[our bug tracker](https://gitlab.gnome.org/GNOME/gnome-builder/issues).
Christian Hergert's avatar
Christian Hergert committed
16

17 18 19
Create a
[Merge Request](https://gitlab.gnome.org/GNOME/gnome-builder/merge_requests)
and we'd be happy to review your patch and help you get it merged.
Christian Hergert's avatar
Christian Hergert committed
20 21 22

## Asking for Help

23
You can often find Builder contributors on our IRC channel at
Christian Hergert's avatar
Christian Hergert committed
24 25 26
[irc://irc.gimp.net/#gnome-builder](irc://irc.gimp.net/#gnome-builder).
If you have any questions, we'd be happy to help you.

27
If you'd like to start on a new plugin or feature, stop by our IRC channel and we'd be happy get you oriented.
Christian Hergert's avatar
Christian Hergert committed
28 29 30

## Portability

31
Builder is primarily focused on **GNU/Linux** with the **GNOME desktop**.
Christian Hergert's avatar
Christian Hergert committed
32

33 34
However, we do often accept patches for various BSD-based operating systems and alternate desktops.
It is important that you help us by keep things working for your platform as the Builder team cannot test all possible configurations.
Christian Hergert's avatar
Christian Hergert committed
35 36 37

## Testing

38 39 40
We use meson for our build system.
It provides support for running unit tests with the `ninja test` command.
We run these tests often so it is important that you check nothing was broken by your changes.
Christian Hergert's avatar
Christian Hergert committed
41 42 43

## Licensing

44 45
Contributions should be licensed under the LGPL-2.1+ or GPL-3.
Permissively licensed contributions will also be accepted, but we prefer that original contributions are either LGPL-2.1+ or GPL-3 licensed.
Christian Hergert's avatar
Christian Hergert committed
46 47 48

## Coding Style

49 50 51
Our coding style matches that of Gtk+.
We consider the Gtk+ project an upstream, and often push features into Gtk+.
This might feel unfamiliar at first, but it works well for us.
Christian Hergert's avatar
Christian Hergert committed
52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72

We use the recent GNU GCC '11 mode, such as -std=gnu11.

```c
static GtkWidget *
example_object_get_widget (ExampleObject  *object,
                           GError        **error)
{
  g_return_val_if_fail (EXAMPLE_IS_OBJECT (object), NULL);

  if (object->widget == NULL)
    {
      object->widget = g_object_new (GTK_TYPE_LABEL,
                                     "visible", TRUE,
                                     NULL);
    }

  return object->widget;
}
```

73 74
You may omit curly-braces for single-line conditionals.

75 76
Please use new-style Object declarations such as `G_DECLARE_FINAL_TYPE()` or `G_DECLARE_DERIVABLE_TYPE()`.
Unless you intend to subclass the object, make the object final.
Christian Hergert's avatar
Christian Hergert committed
77 78 79

```c
#define EXAMPLE_TYPE_OBJECT (example_object_get_type())
80

Christian Hergert's avatar
Christian Hergert committed
81 82 83 84 85
G_DECLARE_FINAL_TYPE (ExampleObject, example_object, EXAMPLE, OBJECT, GObject)
```

Builder's default C mode matches our style guide.

86
### Be explicit about ownership transfers
87 88 89

Since `GLib 2.44`, we've had helpful macros and functions to be explit about ownership transfers.
Please use them as it drastically saves time when tracking down memory leaks.
Christian Hergert's avatar
Christian Hergert committed
90

91 92 93 94 95 96
These include:

 * `g_autoptr()`, `g_auto()`, and `g_autofree`.
 * `g_steal_pointer()`
 * `g_clear_object()` and `g_clear_pointer()`

97 98
We prefer that you zero fields in structures when freeing the contents.

99
## Documentation
Christian Hergert's avatar
Christian Hergert committed
100

101 102
Most functions should be obvious what they do from the object type, name, and parameters.
Add additional documentation when it makes sense.
Christian Hergert's avatar
Christian Hergert committed
103

104
If you find you come across something particularly tricky, or are being clever, please add a comment denoting such.
105 106 107

## Making a Release

108
 - Update subprojects like libdazzle/etc for recent releases
109 110 111 112 113
 - Update NEWS for release notes
 - Update meson.build for the new version number
 - Update doc/conf.py to reflect the updated version number
 - Update any necessary tags in org.gnome.Builder.json for Flatpak
 - Make sure documentation builds, tests pass
114
 - Make sure flatpak bundle builds
115 116 117 118 119 120 121
 - Commit release changes, add a signed tag (git tag -s -u $keyid)
 - Configure meson as normal, ensure docs are built
 - From the build directory, run `ninja dist` to generate the tarball
 - Push changes to master (or branch), push tag
 - scp the tarball to master.gnome.org
 - Run ftpadmin install `gnome-builder-*.tar.xz`.