CONTRIBUTING.md

   1 # Requesting Access
   2
   3 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.
   4
   5 Please let us know your GitLab username [on Matrix](https://xonotic.org/chat) so we know you're legit.
   6
   7
   8 # Licensing
   9
  10 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.**
  11
  12 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:
  13 * [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.
  14 * [xonstat-go](https://gitlab.com/xonotic/xonstat-go/) - licensed with [GNU AGPLv3](https://www.gnu.org/licenses/agpl-3.0.html)
  15
  16 In case the code you pushed was not written by you, it is your responsibility to ensure proper licensing.
  17
  18
  19 # Technical
  20
  21 The Xonotic repo structure and git HOWTO are on the [Xonotic Git wiki page](https://gitlab.com/xonotic/xonotic/-/wikis/Git).
  22 Build tools are documented on the [Repository_Access wiki page](https://gitlab.com/xonotic/xonotic/wikis/Repository_Access).
  23
  24
  25 # Policies
  26
  27 ### for all Developers
  28
  29 - 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`.
  30 - Ask the branch owner before pushing to someone else's branch.
  31
  32 ### for Maintainers
  33
  34 - 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.
  35 - 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.
  36 - 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.
  37 - 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.
  38 - Force pushes must not be made to the default branch (typically `master` or `main`).
  39
  40
  41 # Code Style
  42
  43 This should be approximately consistent with the [DarkPlaces style](https://gitlab.com/xonotic/darkplaces/-/blob/master/CONTRIBUTING.md).
  44
  45 ### All code submitted should follow the Allman style for the most part.
  46
  47 - In statements, the curly brace should be placed on the next line at the
  48   same indentation level as the statement. If the statement only involves
  49   a single line, preferably don't use braces.
  50
  51         ```c
  52         // Example:
  53         if (foo == 1)
  54         {
  55                 Do_Something();
  56                 Do_Something_Else();
  57         }
  58         else
  59                 Do_Something_Else_Else();
  60
  61         if (bar == 1)
  62                 Do_Something_Else_Else_Else();
  63         ```
  64
  65 - Use tabs for indentation.
  66   Use spaces subsequently when aligning text such as the
  67   parameters of multi-line function calls, declarations, or statements.
  68
  69         ```c
  70         switch (foo)
  71         {
  72                 case 1337:   I_Want();  break;
  73                 case 0xffff: These();   break;
  74                 default:     Aligned();
  75         }
  76
  77         AFuncWith(way,
  78                   too,
  79                   many,
  80                   args & STUFF);
  81         ```
  82
  83 - If possible, try to keep individual lines of code less than 100 characters.
  84
  85 - As in the example above, it would be preferable to attempt to limit
  86   line length when it comes to very long lists of function arguments
  87   by manually wrapping the lines, but not prematurely.
  88
  89 - Pointer operators should be placed on the right-hand side and type casts should have a space between the type and the pointer.
  90
  91         ```c
  92         int foo = 1;
  93         int *bar = &foo;
  94         int *baz = (int *)malloc(5);
  95         ```
  96
  97 - Place a space after each comma when listing parameters or defining array/struct members,
  98   and after each semicolon of a `for` loop.
  99   Don't place a space between the function name and the `(` and don't place a space between the `(` or `)` and the parameter.
 100
 101 - Significant documentation comments should be formatted like so:
 102
 103         ```c
 104         /*
 105          * This is a multi-line comment.
 106          * Sometimes, I dream about cheese.
 107          */
 108         ```
 109
 110   But this is okay too:
 111
 112         ```c
 113         /* This is another multi-line comment.
 114          * Hiya! How are you?
 115          */
 116         ```
 117
 118   Place a space between the `//` or `#` and the comment text (_not_ recommended for commented lines of code):
 119
 120         ```c
 121         // Do you know who ate all the doughnuts?
 122         //ItWasThisAwfulFunc(om, nom, nom);
 123         ```
 124
 125 - Use parentheses to separate bitwise and logical versions of an operator when they're used in the same statement.
 126
 127         ```c
 128         foo = (bar & FLAG) && baz;
 129         ```
 130
 131 - Variables names should preferably be in either lowerCamelCase or snake_case
 132   but a cautious use of lowercase for shorter names is fine.
 133   Functions in CamelCase, macros in UPPERCASE.
 134   Underscores should be included if they improve readability.
 135
 136 - If following these guidelines in any manner would make any code less
 137   readable or harder to follow, ***ignore them***. This section is only
 138   guidelines, not rules. We're not going to beat you over the head in
 139   merge requests because you misplaced a dereference operator.
 140
 141   For example, in some situations, placing the block on the same line as
 142   the condition would be okay because it looks cleaner:
 143
 144         ```c
 145         if (foo)  DoSomething();
 146         if (bar)  Do_Something_Else();
 147         if (far)  Near();
 148         if (boo)  AHH("!!!\n");
 149         ```