CONTRIBUTING.md

Contributing

Issues and Pull Requests are welcome!

There are only a few rules:

1. Be respectful in comments/discussions
2. When submitting a patch for an issue, reference the issue in your pull request by typing a # followed by the issue number, and describe what you did to resolve the issue.
3. If you would like to solve several issues at once, they should all have separate pull requests.
4. Follow the coding style below when submitting code

Coding Style

The following guidelines only apply for the core parts of the app. Changes to upstream libraries such as hoedown and charter should try to match the styles of those projects.

General

• Indentations are done with 2 spaces
• There is always a space before opening parentheses
• Curly braces are on their own lines
• When declaring pointer-type variables, the * is paired with the variable name
• Since we are working heavily with gnome libraries, use glib types and functions over C standards when possible
  • Use gchar * instead of char *
  • Use g_malloc () and g_free () over malloc () and free ()
  • Use g_print () and g_err ()
  • etc...
• Namespacing
  • All filenames are prefaced with marker-
  • All public types are prefaced with Marker
  • All other public symbols are prefaced with marker_

Header (.h) files

Function prototypes have the function name start at column 22, the opening parenthases at column 66, and the last asterisk for pointer types, at column 86:

void                 marker_editor_window_set_tab_width          (MarkerEditorWindow *window,
                                                                  guint               value);

Source (.c) files

In order to keep the code predictable and easy-to-navigate, items should appear in the following order:

1. GPL header
2. Structures
3. Function prototypes
4. G_DEFINE_TYPE ()
5. Enums
6. Static variables
7. Auxillary methods
8. Action callbacks
9. Action array
10. Signal callbacks
11. Interface implementations
12. Parent class overrides
13. class_init () and init ()
14. Public API

Action Callbacks

Names for action callbacks should start with action_:

static void
action_zoom_in (GSimpleAction *action,
                GVariant      *parameter,
                gpointer       user_data)
{
  /* ... */
}

Auxillary Methods

Names for auxillary methods do not have the marker_ prefix because they are not part of the public API:

static void
print_hello_world ()
{
  g_print ("Hello World!\n");
}

Signal Callbacks

Names for signal callbacks should be the past-tense of the signal name without the marker_ prefix, but followed by _cb:

static void
size_allocated_cb (GtkWidget     *widget,
                   GtkAllocation *allocation,
                   gpointer       user_data)
{
  /* ... */
}

Releases

When making a release, do all of the following:

1. Update the version number in the meson.build
2. Add a release into data/com.github.fabiocolacio.marker.appdata.xml.
3. Validate the appdata file with the command appstream-util validate-relax data/com.github.fabiocolacio.marker.appdata.xml.
4. Create a release archive using the script archive.sh
5. Create a release on GitHub (see guidelines for release notes below).
6. Update the tag name in the flatpak manifest of the flathub repo
   • If you do not have push access, create a pull request. Someone who has push access will merge it for you.

Version Numbering

We use dates for version numbers in the format YYYY.MM.DD

e.g. 2018.04.25.

Release Notes

When making a release on GitHub, you will be prompted to write release notes. The notes should list every change between the previous release and the new one. The first section should list new features, and the second section should list bug fixes.

An easy way to check what has been changed since the previous release is by finding the previous release in GitHub, and clicking the link that says "X commits to master since this release".