diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/CONTRIBUTING.md | 160 | ||||
| -rw-r--r-- | doc/HACKING.md | 131 |
2 files changed, 291 insertions, 0 deletions
diff --git a/doc/CONTRIBUTING.md b/doc/CONTRIBUTING.md new file mode 100644 index 0000000..4c623f1 --- /dev/null +++ b/doc/CONTRIBUTING.md @@ -0,0 +1,160 @@ +# Contributing to Endeavour + +When contributing to the development of Endeavour, 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](#code-of-conduct), please follow it in all +your interactions with the project. + +# Table of contents +1. [Creating an issue](#issues-issues-and-more-issues) + 1. [Template](#issue-template) + 2. [Example of a good issue](#example-task-rows-should-have-a-maximum-width) +2. [Pull requests](#pull-request-process) +3. [Code of Conduct](#code-of-conduct) + +# Issues, issues and more issues! + +There are many ways you can contribute to Endeavour, and all of them involve creating issues +in [Endeavour issue tracker](https://gitlab.gnome.org/World/Endeavour/issues). This is the +entry point for your contribution. + +To create an effective and high quality ticket, try to put the following information on your +ticket: + + 1. A detailed description of the issue or feature request + - For issues, please add the necessary steps to reproduce the issue. + - For feature requests, add a detailed description of your proposal. + 2. A checklist of Development tasks + 3. A checklist of Design tasks + 4. A checklist of QA tasks + +## Issue template +``` +[Title of the issue or feature request] + +Detailed description of the issue. Put as much information as you can, potentially +with images showing the issue or mockups of the proposed feature. + +If it's an issue, add the steps to reproduce like this: + +Steps to reproduce: + +1. Open Endeavour +2. Create a task +3. ... + +## Design Tasks + +* [ ] design tasks + +## Development Tasks + +* [ ] development tasks + +## QA Tasks + +* [ ] qa (quality assurance) tasks +``` + + +This is an example of a good and informative issue: + +--- +<pre> +<h1>Example: Task rows should have a maximum width</h1> + +When using a very wide window, task rows grow super wide currently, because they +always take up the entire width of the window. This is not great for window sizes +larger than about 600px. + +<img src="https://gitlab.gnome.org/World/Endeavour/uploads/a414239a44c5b2714634df5cb85a7a78/too-wide.png" width="400px" /> + +This is how it would look with a maximum width of 650px: + +<img src="https://gitlab.gnome.org/World/Endeavour/uploads/7dfc77b1c3cc942cf1977770ea15b198/too-wide-fixed.png" width="400px" /> + +<h3>Design Tasks</h3> +* [x] Define how much rows should expand horizontally + +<h3>Development Tasks</h3> +* [ ] Implement maximum-width rows + +<h3>QA Tasks</h3> +* [ ] Rows don't grow horizontally above 650px +* [ ] No regressions were introduced + +</pre> + +--- + +# Pull Request Process + +1. Ensure your code compiles. Run `make` before creating the pull request. +2. If you're adding new external 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 bug ticket> +``` + +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 + +Endeavour 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/ diff --git a/doc/HACKING.md b/doc/HACKING.md new file mode 100644 index 0000000..260e1ff --- /dev/null +++ b/doc/HACKING.md @@ -0,0 +1,131 @@ +# Style + +Endeavour 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**. + +Endeavour's line length is 120 columns. + +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 +GtdManager* gtd_manager_foo_bar (GtdManager *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 _GtdTimer +{ + GtdObject parent; + + guint update_timeout_id; + + GDateTime *current_day; + + GDBusProxy *logind; + GCancellable *cancellable; +}; +``` + +### 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 `gtd_class_name` 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 `gtd_class_name` prefix as well, but have a `on_` prefix and `_cb` suffix. For example: + +```c +static void +on_size_allocated_cb (GtkWidget *widget, + GtkAllocation *allocation, + gpointer user_data) +{ + /* ... */ +} +``` + +### Line Splitting + +Endeavour's line length is 120 columns. + +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. |