summaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/CONTRIBUTING.md212
-rw-r--r--docs/HACKING.md291
-rw-r--r--docs/MAINTAINERS.md62
3 files changed, 565 insertions, 0 deletions
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
new file mode 100644
index 0000000..697e84c
--- /dev/null
+++ b/docs/CONTRIBUTING.md
@@ -0,0 +1,212 @@
+# 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. Create a fork in GitLab and push your work to there
+2. Open a Merge Request
+ 1. Always allow maintainer edits
+ 2. Mark the Merge Request as WIP if your work is not ready to be reviewed
+3. Assign the correct maintainer to the Merge Request (see [`MAINTAINERS.md`][maintainers] to select
+ the correct maintainer)
+4. Format commit messages 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 and GitHub's community
+guidelines. 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.
+
+### Communication Guidelines
+
+It is of ultimate importance to maintain a community in which everyone feels free to express
+themselves, review, and comment on each others ideas, both technical and otherwise. Correspondingly,
+an environment in which individuals are silenced, berated, or are otherwise afraid to speak up is
+unlikely to foster fruitful dialog.
+
+Everyone interacting with members of the community should always keep in mind the asymmetry of
+communication: while your interaction with community members (and in particular, maintainers and
+long-term contributors) may be singular and fleeting, these members generally interact with a high
+volume of individuals each day. Before writing a comment, opening a new issue, or engaging as part
+of any forum or IRC discussion, please take a moment to appreciate that fact.
+
+While communicating, it is expected that all involved participants be respectful and civil at all
+times and refrain from personal attacks.
+
+#### Communication Rules
+
+The following behavior will not be tolerated on any occasion:
+
+ * **Threats of violence**: You may not threaten violence towards others or use the site to organize,
+ promote, or incite acts of real-world violence or terrorism. Think carefully about the words you
+ use, the images you post, and even the software you write, and how they may be interpreted by
+ others. Even if you mean something as a joke, it might not be received that way. If you think
+ that someone else might interpret the content you post as a threat or as promoting violence or
+ terrorism, stop. Don't post it. In extraordinary cases, we may report threats of violence to law
+ enforcement if we think there may be a genuine risk of physical harm or a threat to public safety.
+
+ * **Hate speech and discrimination**: While it is not forbidden to broach topics such as age, body
+ size, disability, ethnicity, gender identity and expression, level of experience, nationality,
+ personal appearance, race, religion, or sexual identity and orientation, we do not tolerate speech
+ that attacks a person or group of people on the basis of who they are. When approached in an
+ aggressive or insulting manner these (and other) sensitive topics can make others feel unwelcome,
+ or perhaps even unsafe. While there's always the potential for misunderstandings, we expect our
+ community members to remain respectful and civil when discussing sensitive topics.
+
+ * **Bullying and harassment**: We do not tolerate bullying, harassment, or any other means of
+ habitual badgering or intimidation targeted at a specific person or group of people. In general,
+ if your actions are unwanted and you cease to terminate this form of engagement, there is a good
+ chance that your behavior will be classified as bullying or harassment.
+
+ * **Impersonation**: You may not seek to mislead others as to your identity by copying another
+ person's avatar, posting content under their email address, using a similar username, or otherwise
+ posing as someone else. Impersonation and identity theft is a form of harassment.
+
+ * **Doxxing and invasion of privacy**: Don't post other people's personal information, such as phone
+ numbers, private email addresses, physical addresses, credit card numbers, Social Security/National
+ Identity numbers, or passwords. Depending on the context, we may consider such behavior to be an
+ invasion of privacy, with particularly egregious examples potentially escalating to the point of
+ legal action, such as when the released material presents a safety risk to the subject.
+
+ * **Obscene content**: In essence, do not post pornography, gore, or any other depiction of violence.
+
+#### General Advice
+
+The following advice will help to increase the efficiency of communication with community members:
+
+ * Do not post "me too" comments. Use the GitLab reactions instead, e.g. “thumbs up” or “thumbs down”.
+ * Avoid adding priority, time, or relevance hints if you are not involved with the development of
+ the application. For example, `“This is an urgent issue”`, or `“This should be fixed now”`, or
+ even `“The majority of users need this feature”`.
+ * Do not use passive-aggressive communication tactics.
+ * When reporting technical problems with the application, such as misbehavior or crashes, focus on
+ sharing as many details as possible and avoid adding non-technical information to it.
+
+ An example of a **good** issue report:
+
+ ```
+ GNOME Settings crashes when opening the Wi-Fi panel with 3+ Wi-Fi adapters
+
+ Steps to reproduce (assuming 3+ Wi-Fi adapters are present):
+
+ 1. Open GNOME Settings
+ 2. Select the Wi-Fi panel
+ 3. Observe the crash
+
+ This does not happen with 2 or less adapters. Here is a backtrace of the
+ crash: backtrace.txt
+ ```
+
+ In contrast, here is an example of a **bad** issue report:
+
+ ```
+ GNOME Settings crashed while I was trying to connect to the internet. How can such
+ a thing happen and nobody notice? Did you not test it before releasing it?
+
+ This should be fixed as quick as possible!
+ ```
+
+ * When asking for new features, try and add as much information as possible to justify its relevance,
+ why should it not be implemented as an auxiliary program, what problems it would solve, and offer
+ suggestions about how you think it should be implemented.
+
+ Example of a **good** feature request:
+
+ ```
+ GNOME Settings needs to expose IPv6 options
+
+ As of now, the connection editor dialog does not allow editing various IPv6
+ options. This is relevant because without some of these options, it is not
+ possible to have a valid IPv6 configuration and, consequently, not have access
+ to various websites and services.
+
+ The list of missing configurations that are essential is:
+
+ * <Feature A>
+ * <Feature B>
+
+ Optionally, the following configurations can also be added:
+
+ * <Feature C>
+ * <Feature D>
+
+ Here is a quick sketch I have made showing how I think these options
+ should be exposed as a user interface: sketch.png.
+ ```
+
+ Example of a **bad** feature request:
+
+ ```
+ Merge GNOME Tweaks in GNOME Settings
+
+ The options in GNOME Tweaks are absolutely essential to the majority of us
+ users. Why was it not merged already? This is an urgent issue and should
+ have been addressed years ago. You should allocate all your resources on
+ merging those two applications.
+ ```
+
+#### What happens if someone breaks these rules or guidelines?
+
+Actions that may be taken in response to an abusive comment include but are not limited to:
+
+ * Content removal (when breaking any of the guidelines or rules)
+ * Content blocking (when breaking any of the guidelines or rules)
+ * Formal report to the Code of Conduct Committee (when breaking any of the rules)
+
+### 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/
+[maintainers]: https://gitlab.gnome.org/GNOME/gnome-control-center/blob/main/docs/MAINTAINERS.md
diff --git a/docs/HACKING.md b/docs/HACKING.md
new file mode 100644
index 0000000..a60e206
--- /dev/null
+++ b/docs/HACKING.md
@@ -0,0 +1,291 @@
+# 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**.
+
+That said, GNOME Settings assumes:
+
+ * 2 spaces of indentation
+ * 120 columns of line width
+ * Newline before `{`
+
+Another rule that applies to function declarations is that all parameters are
+aligned by the last '*'. There are plenty of examples below.
+
+## Comments
+
+Comment blocks should be formatted as following:
+
+```c
+/* Single line comment */
+
+/* Multiline comments start at the first line of the comment block,
+ * but have the closing slash a line after. Every line starts with
+ * an asterisk that is aligned with every the rest of the block.
+ */
+```
+
+## Conditionals
+
+Conditionals should either be all in one line, or one per line. Newlines inside
+conditionals are aligned by the last parenthesis.
+
+
+Some examples below:
+
+```c
+// Single line if
+if (a || b || (c && d))
+ return;
+
+// Multiline if with nested parenthesis
+if (long_boolean_variable_used_in_this_condition_a ||
+ long_boolean_variable_used_in_this_condition_b ||
+ (long_boolean_variable_used_in_this_condition_c &&
+ long_boolean_variable_used_in_this_condition_d))
+ {
+ return;
+ }
+
+// Another single line example with do {} while (...)
+do
+ {
+ /* something */
+ }
+while (a || b || (c && d));
+```
+
+## Structs and Enums
+
+Structures and enums are formatted as following:
+
+```c
+struct _FooBar
+{
+ guint32 field_one;
+ gchar *text;
+};
+
+typedef struct
+{
+ FooParent parent;
+
+ guint32 field_one;
+ gchar *text;
+
+ struct
+ {
+ CustomType *something;
+ guint something_else;
+ } inner_struct;
+
+ gboolean flag : 1;
+} FooBar;
+
+enum
+{
+ FIRST,
+ SECOND,
+ LAST,
+};
+
+typedef enum
+{
+ FOO_BAR_FIRST,
+ FOO_BAR_SECOND,
+ FOO_BAR_LAST,
+} FooEnumBar;
+```
+
+## 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
diff --git a/docs/MAINTAINERS.md b/docs/MAINTAINERS.md
new file mode 100644
index 0000000..67fe470
--- /dev/null
+++ b/docs/MAINTAINERS.md
@@ -0,0 +1,62 @@
+This document describes how maintainership works on GNOME Settings. It is intended to be a guideline
+for future reference.
+
+The list of current maintainers can be found at the [gnome-control-center.doap][doap] DOAP file.
+
+# General Rules
+
+The purpose of the shared maintainership model in GNOME Settings is to avoid as much as possible
+pushing unreviewed code in the main repository. Not only it is a good engineering practice, but it
+also increases the code quality and reduces the number of bugs.
+
+GNOME Settings has two types of maintainers:
+
+ * **General Maintainer**: take care of the whole codebase and of panels without a specific maintainer.
+ * **Panel Maintainer**: take care of a specific panel with a stronger authority over General
+ Maintainers.
+
+
+## For Contributors
+
+Panel Maintainers have a stronger authority over their panels than a General Maintainer. If you are
+contributing to a specific panel, and that panel has a dedicate maintainer, they should be the main
+point of contact.
+
+In the rare case of Panel Maintainers not being responsive, it is allowed to contact General
+Maintainers.
+
+## For Maintainers
+
+If you are a Panel Maintainer, your merge requests will be reviewed by General Maintainer. The
+opposite is true as well - General Maintainers contributing to a specific panel will have their
+merge requests reviewed by the Panel Maintainer of that panel.
+
+If you are a General Maintainer contributing to an unmaintained panel, or to the main codebase, your
+merge requests will be reviewed by another General Maintainer.
+
+Avoid pushing commits without an explicit review, except in the following cases:
+
+ * The commit is a translation commit
+ * The commit is trivial
+ * The commit is urgent and no reviewers were available in time
+
+When accepting a merge request and allowing the other maintainer to merge, avoid misunderstandings
+by being explicit. Suggested acceptance phrase:
+
+`I approve this merge request. You are allowed to merge it.`
+
+### Urgency Commits
+
+Urgency commits should never happen, but in case they're needed, they are defined by the following
+criteria:
+
+ * On stable branches (or `main` right after a stable release)
+ * Symptoms:
+ * Always OR often reproducible; AND
+ * Crash; OR
+ * Data loss; OR
+ * System corruption
+ * Quickly followed by an emergency release (at most 2 days after the commit)
+
+
+[doap]: https://gitlab.gnome.org/GNOME/gnome-control-center/blob/main/gnome-control-center.doap