From: bones_was_here Date: Thu, 14 Sep 2023 16:36:17 +0000 (+1000) Subject: Add a CONTRIBUTING.md X-Git-Url: https://git.rm.cloudns.org/?a=commitdiff_plain;h=65f0135b04e6574132cedd99385bd23d537e7e2a;p=xonotic%2Fxonotic.git Add a CONTRIBUTING.md This is based on wiki pages and DP's CONTRIBUTING.md and it adds some policies that previously were expected but not documented. This is intended to replace policy and licensing sections of the wiki, partly to collate these and partly because only the Team should be able to push updates to them. Signed-off-by: bones_was_here --- diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..a2aa5615 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,149 @@ +# Requesting Access + +It's recommended to [request access](https://docs.gitlab.com/ee/user/group/index.html#request-access-to-a-group) to the [Xonotic project group](https://gitlab.com/xonotic). Forking our repositories and submitting merge requests from there will work but you won't be able to use our CI setup for the [xonotic-data.pk3dir](https://gitlab.com/xonotic/xonotic-data.pk3dir) repo. + +Please let us know your GitLab username [on Matrix](https://xonotic.org/chat) so we know you're legit. + + +# Licensing + +A condition for write (push) access and submission of merge requests is that **you agree that any code or data you push will be licensed under the [GNU General Public License, version 2](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html), or any later version.** + +If the directory or repository your changes apply to contains a LICENSE or COPYING file indicating another license or a dual license, then **you agree that your pushed code will be licensed as specified in that file.** Examples of subdirectories and repositories with a dual license or a different license: +* [xonotic-data.pk3dir/qcsrc/lib/warpzone](https://gitlab.com/xonotic/xonotic-data.pk3dir/-/tree/master/qcsrc/lib/warpzone) - dual licensed with GNU GPLv2 (or any later version), or MIT license. +* [xonstat-go](https://gitlab.com/xonotic/xonstat-go/) - licensed with [GNU AGPLv3](https://www.gnu.org/licenses/agpl-3.0.html) + +In case the code you pushed was not written by you, it is your responsibility to ensure proper licensing. + + +# Technical + +The Xonotic repo structure and git HOWTO are on the [Xonotic Git wiki page](https://gitlab.com/xonotic/xonotic/-/wikis/Git). +Build tools are documented on the [Repository_Access wiki page](https://gitlab.com/xonotic/xonotic/wikis/Repository_Access). + + +# Policies + +### for all Developers + +- Branches should be named `myname/mychange`. For instance, if your name is Alex and the change you are committing is a menu fix, use something like `alex/menufix`. +- Ask the branch owner before pushing to someone else's branch. + +### for Maintainers + +- During a release freeze only user-visible fixes/polishing and documentation may be merged/pushed to master, other changes (eg new features, redesigns, refactors) must be discussed with the team first. +- Pushing to someone else's branch is allowed if changes are required for merging the branch AND the owner has left the project or indicated they won't develop the branch further. +- Any change pushed directly to `master` must be top quality: no regressions, no controversy, thoughtful design, great perf, clean and readable, successful pipeline, compliant with the Code Style below, no compiler warnings. +- When merging, if the commit history is "messy" (contains commits that just fix the previous commit(s), and/or commits that don't compile and run, and/or poorly described commits) the MR should be squash merged. Clean concise commit history is useful and is to be merged intact. +- Force pushes must not be made to the default branch (typically `master` or `main`). + + +# Code Style + +This should be approximately consistent with the [DarkPlaces style](https://gitlab.com/xonotic/darkplaces/-/blob/master/CONTRIBUTING.md). + +### All code submitted should follow the Allman style for the most part. + +- In statements, the curly brace should be placed on the next line at the + same indentation level as the statement. If the statement only involves + a single line, preferably don't use braces. + + ```c + // Example: + if (foo == 1) + { + Do_Something(); + Do_Something_Else(); + } + else + Do_Something_Else_Else(); + + if (bar == 1) + Do_Something_Else_Else_Else(); + ``` + +- Use tabs for indentation. + Use spaces subsequently when aligning text such as the + parameters of multi-line function calls, declarations, or statements. + + ```c + switch (foo) + { + case 1337: I_Want(); break; + case 0xffff: These(); break; + default: Aligned(); + } + + AFuncWith(way, + too, + many, + args & STUFF); + ``` + +- If possible, try to keep individual lines of code less than 100 characters. + +- As in the example above, it would be preferable to attempt to limit + line length when it comes to very long lists of function arguments + by manually wrapping the lines, but not prematurely. + +- Pointer operators should be placed on the right-hand side and type casts should have a space between the type and the pointer. + + ```c + int foo = 1; + int *bar = &foo; + int *baz = (int *)malloc(5); + ``` + +- Place a space after each comma when listing parameters or defining array/struct members, + and after each semicolon of a `for` loop. + Don't place a space between the function name and the `(` and don't place a space between the `(` or `)` and the parameter. + +- Significant documentation comments should be formatted like so: + + ```c + /* + * This is a multi-line comment. + * Sometimes, I dream about cheese. + */ + ``` + + But this is okay too: + + ```c + /* This is another multi-line comment. + * Hiya! How are you? + */ + ``` + + Place a space between the `//` or `#` and the comment text (_not_ recommended for commented lines of code): + + ```c + // Do you know who ate all the doughnuts? + //ItWasThisAwfulFunc(om, nom, nom); + ``` + +- Use parentheses to separate bitwise and logical versions of an operator when they're used in the same statement. + + ```c + foo = (bar & FLAG) && baz; + ``` + +- Variables names should preferably be in either lowerCamelCase or snake_case + but a cautious use of lowercase for shorter names is fine. + Functions in CamelCase, macros in UPPERCASE. + Underscores should be included if they improve readability. + +- If following these guidelines in any manner would make any code less + readable or harder to follow, ***ignore them***. This section is only + guidelines, not rules. We're not going to beat you over the head in + merge requests because you misplaced a dereference operator. + + For example, in some situations, placing the block on the same line as + the condition would be okay because it looks cleaner: + + ```c + if (foo) DoSomething(); + if (bar) Do_Something_Else(); + if (far) Near(); + if (boo) AHH("!!!\n"); + ``` diff --git a/README.md b/README.md index a9446a12..fa6dd743 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ The community is primarily active in the [forums](https://forums.xonotic.org/) a To compile the latest revision from git, [follow this guide](https://gitlab.com/xonotic/xonotic/wikis/Repository_Access). Learn more about the [directory structure here](https://gitlab.com/xonotic/xonotic/wikis/Git). Check out [our project page on GitLab](https://gitlab.com/groups/xonotic) to see [development activity](https://gitlab.com/groups/xonotic/-/activity) and code ([xonotic-data.pk3dir](https://gitlab.com/xonotic/xonotic-data.pk3dir) is where most development takes place). -Please ensure you've read and understood [Contributing and Getting Write Access](https://gitlab.com/xonotic/xonotic/-/wikis/Repository_Access#contributing-and-getting-write-access) before pushing commits or opening merge requests. +Please ensure you've read and understood [CONTRIBUTING.md](CONTRIBUTING.md) before pushing commits or opening merge requests. ## Contributing