From 7f14e9f561262357e7dc149070bb7e2115e09808 Mon Sep 17 00:00:00 2001
From: Georges Basile Stavracas Neto <georges.stavracas@gmail.com>
Date: Fri, 8 Sep 2017 21:34:52 -0300
Subject: [PATCH] project: rewrite HACKING guides

Now I don't have to pass all this tribal knowledge every
single time.
---
 HACKING    |  30 ------------
 HACKING.md | 138 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 138 insertions(+), 30 deletions(-)
 delete mode 100644 HACKING
 create mode 100644 HACKING.md

diff --git a/HACKING b/HACKING
deleted file mode 100644
index fcf43893..00000000
--- a/HACKING
+++ /dev/null
@@ -1,30 +0,0 @@
-Code formating and ordering
-===========================
-
-+ The source file will keep and order of methods. The order will be as
-  following:
-  1. Private functions
-  2. vfuncs implementations
-  3. interface init
-  4. class_init and init
-  5. Public API will go in the end
-
-+ Methods naming will be according to:
-  1. Private methods will have no prefix
-  2. vfuncs and public API will have the right prefix
-
-+ The methods prototype will always be placed at the top of the source, in the
-  same order as their implementation below.
-
-+ Lines will have 120 chars of width. I've been to long of just 80
-
-+ Line splitting will work accordingly to Gtk+ code style, adding the following:
-  1. Pure mathematic calculation can extend over the 120 pixel line
-
-Contributing guidelines
-=======================
-
-+ Fill a bug, attach a patch, wait for review (ping the maintainers if you think
-we took too long)
-+ If you patch touch any Meson-related files at all in any non trivial way,
-ensure **make distcheck** pass before posting the patch
diff --git a/HACKING.md b/HACKING.md
new file mode 100644
index 00000000..6f9b8689
--- /dev/null
+++ b/HACKING.md
@@ -0,0 +1,138 @@
+# Style
+
+GNOME Calendar has a coding style based on GTK Coding Style, but with a few more
+rules. Please read them carefully and, if in doubt, ask a maintainer for directions.
+
+## General
+
+The most important rule is: **see the surrounding code, and copy its style**.
+
+Another rule that applies to function declarations is that all parameters are
+aligned by the last '*'. There are plenty of examples below.
+
+## Header (.h) files
+
+ * The '*' and the type come together, without any spaces in between.
+ * Function name starts at column 22.
+ * Parenthesis after function name is at column 66
+ * The last '*' in parameters are at column 86
+
+As an example, this is how a function should look like:
+
+```c
+GcalManager*         gcal_manager_foo_bar                        (GcalManager        *self,
+                                                                  GError            **example);
+```
+
+## Source code
+
+The source file keeps an order of methods. The order will be as following:
+
+  1. GPL header
+  2. Structures
+  3. Function prototypes
+  4. G_DEFINE_TYPE()
+  5. Enums
+  6. Static variables
+  7. Auxiliary methods
+  8. Signal callbacks
+  9. Interface implementations
+  10. Parent class overrides
+  11. class_init and init
+  12. Public API
+
+### Structures
+
+The structures must have the last pointer asterisk at column 22. Non-pointer fields
+start at column 23. For example:
+
+```c
+struct _GcalQuickAddPopover
+{
+  GtkPopover          parent;
+
+  GtkWidget          *add_button;
+  GtkWidget          *calendars_listbox;
+  GtkWidget          *calendar_name_label;
+  GtkWidget          *color_image;
+  GtkWidget          *stack;
+  GtkWidget          *summary_entry;
+  GtkWidget          *title_label;
+
+  /* Internal data */
+  GDateTime          *date_start;
+  GDateTime          *date_end;
+
+  GtkWidget          *selected_row;
+
+  gboolean            clock_format_24h;
+
+  GcalManager        *manager;
+};
+```
+
+### Function Prototypes
+
+Function prototypes must be formatted just like in header files.
+
+### Auxiliary Methods
+
+Auxiliary method names must have a verb in the dictionary form, and should always
+perform an action over something. They don't have the gcal_foo prefix. For example:
+
+```c
+static void
+do_something_on_data (Foo *data,
+                      Bar *bar)
+{
+  /* ... */
+}
+```
+
+### Signal Callbacks
+
+Signal callback names must have the name of the signal in the past. They don't have
+the gcal_foo prefix as well, but have a _cb suffix. For example:
+
+```c
+static void
+size_allocated_cb (GtkWidget     *widget,
+                   GtkAllocation *allocation,
+                   gpointer       user_data)
+{
+  /* ... */
+}
+```
+
+### Line Splitting
+
+Line splitting works following the GTK code style, but legibility comes over above
+all. If a function call looks unbalanced following the GTK style, it is fine to
+slightly escape the rules.
+
+For example, this feels extremelly unbalanced:
+
+```c
+foo_bar_do_somthing_sync (a,
+                          1,
+                          object,
+                          data,
+                          something
+                          cancellable,
+                          &error);
+```
+
+Notice the empty space before the arguments, and how empty and odd it looks. In
+comparison, it will look better if written like this:
+
+```c
+foo_bar_do_somthing_sync (a, 1, object, data,
+                          something
+                          cancellable,
+                          &error);
+```
+
+# Contributing guidelines
+
+See CONTRIBUTIONS.md file for the contribution guidelines, and the Code of Conduct
+that contributors are expected to follow.