From 70b346d8b522b1a9a85e2c7a4232af4c19c74082 Mon Sep 17 00:00:00 2001 From: Georges Basile Stavracas Neto Date: Wed, 2 May 2018 23:00:31 -0300 Subject: project: Add coding style and contribution guidelines And also update the README file. --- README | 53 -------------- README.md | 40 +++++++++++ docs/CONTRIBUTING.md | 71 ++++++++++++++++++ docs/HACKING.md | 200 +++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 311 insertions(+), 53 deletions(-) delete mode 100644 README create mode 100644 README.md create mode 100644 docs/CONTRIBUTING.md create mode 100644 docs/HACKING.md diff --git a/README b/README deleted file mode 100644 index d9646c7a3..000000000 --- a/README +++ /dev/null @@ -1,53 +0,0 @@ -GNOME Control Center -==================== - -About - - -The control center is GNOME's main interface for configuration of various -aspects of your desktop. - -Installation - - -See the file 'INSTALL' - -How to report bugs - - -Bugs should be reported to the GNOME bug tracking system under the product -gnome-control-center. It is available at http://bugzilla.gnome.org. - -In the report please include the following information - - - Operating system and version - For Linux, version of the C library - How to reproduce the bug if possible - If the bug was a crash, include the exact text that was printed out - A stacktrace where possible [see below] - -How to get a stack trace - - -If the crash is reproducible, it is possible to get a stack trace and -attach it to the bug report. The following steps are used to obtain a -stack trace - - - Run the program in gdb [the GNU debugger] or any other debugger - ie. gdb gnome-keyboard-properties - Start the program - ie. (gdb) run - Reproduce the crash and the program will exit to the gdb prompt - Get the back trace - ie. (gdb) bt full - -Once you have the backtrace, copy and paste this either into the -'Comments' field or attach a file with it included. - - -Patches - - -Patches should be submitted to bugzilla.gnome.org or emailed to the -gnomecc-list@gnome.org list. If using bugzilla, attach -the patch to a new bug report [or preferably, check to see if there is -already a bug report that corresponds to your patch]. Bug reports -containing patches should include the 'PATCH' keyword. - -See https://wiki.gnome.org/Newcomers/CodeContributionWorkflow for how to -create patches. diff --git a/README.md b/README.md new file mode 100644 index 000000000..3de9100bc --- /dev/null +++ b/README.md @@ -0,0 +1,40 @@ +GNOME Settings +==================== + +GNOME Settings is GNOME's main interface for configuration of various aspects of +your desktop. + +## Contributing + +See `docs/CONTRIBUTING.md` for details on the contribution process, and `docs/HACKING.md` +for the coding style guidelines. + +## Reporting Bugs + +Bugs should be reported to the GNOME bug tracking system under the product +gnome-control-center. It is available at https://gitlab.gnome.org. + +In the report please include the following information - + + Operating system and version + For Linux, version of the C library + How to reproduce the bug if possible + If the bug was a crash, include the exact text that was printed out + A stacktrace where possible [see below] + +### How to get a stack trace + +If the crash is reproducible, it is possible to get a stack trace and +attach it to the bug report. The following steps are used to obtain a +stack trace - + + Run the program in gdb [the GNU debugger] or any other debugger + ie. gdb gnome-keyboard-properties + Start the program + ie. (gdb) run + Reproduce the crash and the program will exit to the gdb prompt + Get the back trace + ie. (gdb) bt full + +Once you have the backtrace, copy and paste this either into the +'Comments' field or attach a file with it included. \ No newline at end of file diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 000000000..7e054da29 --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,71 @@ +# Contributing + +When contributing to the development of GNOME Settings, please first discuss the change you wish to +make via issue, email, or any other method with the maintainers before making a change. + +Please note we have a Code of Conduct, please follow it in all your interactions with the project. + +## Pull Request Process + +1. Ensure your code compiles and doesn't break anything. Run `meson test -C ` before creating + the pull request. +2. If you're adding new API, it must be properly documented. +3. The commit message is formatted as follows: + ``` + component: + ‌ + A paragraph explaining the problem and its context. +‌ + Another one explaining how you solved that. +‌ + + ``` +4. You may merge the pull request in once you have the sign-off of the maintainers, or if you + do not have permission to do that, you may request the second reviewer to merge it for you. + +## Code of Conduct + +GNOME Settings is a project developed based on GNOME Code of Conduct. You can read it below: + +### Summary + +GNOME creates software for a better world. We achieve this by behaving well towards +each other. + +Therefore this document suggests what we consider ideal behaviour, so you know what +to expect when getting involved in GNOME. This is who we are and what we want to be. +There is no official enforcement of these principles, and this should not be interpreted +like a legal document. + +### Advice + + * **Be respectful and considerate**: Disagreement is no excuse for poor behaviour or personal + attacks. Remember that a community where people feel uncomfortable is not a productive one. + + * **Be patient and generous**: If someone asks for help it is because they need it. Do politely + suggest specific documentation or more appropriate venues where appropriate, but avoid + aggressive or vague responses such as "RTFM". + + * **Assume people mean well**: Remember that decisions are often a difficult choice between + competing priorities. If you disagree, please do so politely. If something seems outrageous, + check that you did not misinterpret it. Ask for clarification, but do not assume the worst. + + * **Try to be concise**: Avoid repeating what has been said already. Making a conversation larger + makes it difficult to follow, and people often feel personally attacked if they receive multiple + messages telling them the same thing. + + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +### Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ \ No newline at end of file diff --git a/docs/HACKING.md b/docs/HACKING.md new file mode 100644 index 000000000..aa798d44e --- /dev/null +++ b/docs/HACKING.md @@ -0,0 +1,200 @@ +# Style + +GNOME Settings 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 + +It is organized by the following structure: + + 1. GPL header + 2. Local includes + 3. System includes + 4. `G_BEGIN_DECLS` + 5. `#defines` + 6. `G_DECLARE_{FINAL,DERIVABLE}_TYPE` + 7. Public API + 8. `G_END_DECLS` + +The following style rules apply: + + * The '*' and the type come together, without any spaces in between. + * Function names are aligned by the widest return value. + * Parenthesis after function name is aligned by the widest function name + * The last '*' in parameters are aligned by the widest parameter type + * No new line at the end of the file + +As an example, this is how a header file should look like (extracted from +the `cc-object-storage.h` file): + +```c +/* cc-object-storage.h + * + * Copyright 2018 Georges Basile Stavracas Neto + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program. If not, see . + */ + +#pragma once + +#include +#include + +G_BEGIN_DECLS + +/* Default storage keys */ +#define CC_OBJECT_NMCLIENT "CcObjectStorage::nm-client" + + +#define CC_TYPE_OBJECT_STORAGE (cc_object_storage_get_type()) + +G_DECLARE_FINAL_TYPE (CcObjectStorage, cc_object_storage, CC, OBJECT_STORAGE, GObject) + +gboolean cc_object_storage_has_object (const gchar *key); + +void cc_object_storage_add_object (const gchar *key, + gpointer object); + +gpointer cc_object_storage_get_object (const gchar *key); + +gpointer cc_object_storage_create_dbus_proxy_sync (GBusType bus_type, + GDBusProxyFlags flags, + const gchar *name, + const gchar *path, + const gchar *interface, + GCancellable *cancellable, + GError **error); + +void cc_object_storage_create_dbus_proxy (GBusType bus_type, + GDBusProxyFlags flags, + const gchar *name, + const gchar *path, + const gchar *interface, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); + +G_END_DECLS +``` + +## 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. Callbacks + 9. Interface implementations + 10. Parent class overrides + 11. class_init and init + 12. Public API + +### Structures + +The structures must have the first pointer asterisk aligned one space after the +widest type name. For example: + +```c +typedef struct +{ + GBusType bus_type; + GDBusProxyFlags flags; + gchar *name; + gchar *path; + gchar *interface; + gboolean cached; +} TaskData; + +``` + +### 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 `cc_` prefix. For example: + +```c +static void +execute_something_on_data (Foo *data, + Bar *bar) +{ + /* ... */ +} +``` + +### Callbacks + + * Callbacks always have the `_cb` suffix + * Signal callbacks always have the `on_` prefix + * Callback names must have the name of the signal in the past + +For example: + +```c +static void +on_foo_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. \ No newline at end of file -- cgit v1.2.1