It's 3.30.1 release day, upload a tarball and enjoy the fixes of those pesky bugs 🐛

project: Add coding style and contribution guidelines

And also update the README file.
parent 16f06665
GNOME Control Center
GNOME Settings
====================
About -
GNOME Settings is GNOME's main interface for configuration of various aspects of
your desktop.
The control center is GNOME's main interface for configuration of various
aspects of your desktop.
## Contributing
Installation -
See `docs/CONTRIBUTING.md` for details on the contribution process, and `docs/HACKING.md`
for the coding style guidelines.
See the file 'INSTALL'
How to report bugs -
## Reporting 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.
gnome-control-center. It is available at https://gitlab.gnome.org.
In the report please include the following information -
......@@ -23,7 +22,7 @@ In the report please include the following information -
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 -
### 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
......@@ -38,16 +37,4 @@ stack 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.
'Comments' field or attach a file with it included.
\ No newline at end of file
# 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 <builddir>` 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: <summary>
A paragraph explaining the problem and its context.
Another one explaining how you solved that.
<link to the issue>
```
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
# 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 <georges.stavracas@gmail.com>
*
* 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 <http://www.gnu.org/licenses/>.
*/
#pragma once
#include <glib-object.h>
#include <gio/gio.h>
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_<object_name>` 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
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment