Return to CONTRIBUTING.md CVS log

Up to [contributed] / brogue-ce

Annotation of brogue-ce/CONTRIBUTING.md, Revision 1.1.1.1

1.1       rubenllo    1: Contributing
                      2: ============
                      3:
                      4: For general help on using GitHub to contribute to a project, check out the
                      5: [GitHub.com help].
                      6:
                      7: We have a Discord server for discussion; feel free to join it here:
                      8: https://discord.gg/8pxE4j8.
                      9:
                     10: ## Testing
                     11:
                     12: The *master* branch represents the latest development snapshot, and should be
                     13: considered ready for play-testing at all times. If you're a Brogue player, you
                     14: can help out by playing the latest *master* and letting us know of any bugs you
                     15: run into! Just follow the build instructions (BUILD.md).
                     16:
                     17: ## Code
                     18:
                     19: When submitting patches or opening pull requests to Brogue CE, please
                     20: attempt to meet the follow guidelines. To avoid wasted work, I recommend
                     21: first discussing with us the proposed changes on the Discord or by opening
                     22: an issue report.
                     23:
                     24: ### Branches and versions
                     25:
                     26: Brogue CE version numbers follow 1.MINOR.PATCH. Essentially, patch-level
                     27: releases don't change the gameplay experience in any way--this is to avoid
                     28: breaking saves and replays. Minor-point releases may do so.
                     29:
                     30: The are two long-term branches which you should base PRs on:
                     31:
                     32: * *master* is for gameplay changes for the next minor-point release
                     33: * *release* is for bug fixes and other non-gameplay changes, for the next patch
                     34:   release. It is merged into *master* periodically.
                     35:
                     36: Any other public branches may be rebased and force-pushed at any time, so please
                     37: be careful when branching from them.
                     38:
                     39: ### Commits
                     40:
                     41: I find a clear Git history very beneficial to work with, so I care quite a bit
                     42: about how commits are presented in PRs.
                     43:
                     44: Please read my [tips for using Git effectively][Git guidance], which can be
                     45: considered guidelines for contributing to this project.
                     46:
                     47: ### Change files
                     48:
                     49: When making user-facing changes, please add a non-technical description of each
                     50: change to a Markdown (.md) file in `changes/`. These files are collated to
                     51: create the release notes.
                     52:
                     53: If the change is from one commit, include this file in it. For a branch of
                     54: multiple commits, add it in a separate commit.
                     55:
                     56: ### Style
                     57:
                     58: - Use 4 space of indentation
                     59: - Be consistent with formatting (pay attention to whitespace between brackets,
                     60:   commas, etc.)
                     61: - Try to follow the style of existing code
                     62: - Declare functions and variables local to a file as `static`
                     63: - Prefer `int` in new integer declarations; use `short` only when working with
                     64:   existing `short` variables
                     65: - Use braces for control structures on multiple lines
                     66:
                     67:   ```c
                     68:   // no
                     69:   if (cond)
                     70:       action();
                     71:
                     72:   // yes
                     73:   if (cond) {
                     74:       action();
                     75:   }
                     76:
                     77:   // acceptable
                     78:   if (cond) action();
                     79:   ```
                     80:
                     81: - When writing bracketed lists over multiple lines, wrap it naturally and don't
                     82:   align to the open bracket (this includes declarations)
                     83:
                     84:   ```c
                     85:   // yes
                     86:   some_function(
                     87:       a, b,
                     88:       c,
                     89:       d
                     90:   );
                     91:
                     92:   // no
                     93:   some_function(a, b,
                     94:                 c,
                     95:                 d);
                     96:   ```
                     97:
                     98: - When writing multi-line if/while conditions, use at least the same indentation
                     99:   as the body. It can be clearer to over-indent to separate it
                    100:
                    101:   ```c
                    102:   // same indent is ok
                    103:   while ((A && B)
                    104:       || C) {
                    105:       ...
                    106:   }
                    107:
                    108:   // over-indent can be clearer
                    109:   while ((A && B)
                    110:           || C) {
                    111:       ...
                    112:   }
                    113:
                    114:   // a gap works too
                    115:   while ((A && B)
                    116:       || C) {
                    117:
                    118:       ...
                    119:   }
                    120:   ```
                    121:
                    122: [GitHub.com help]: https://docs.github.com/en/free-pro-team@latest/github
                    123: [Git guidance]: http://www.collider.in/tom/git-guidance.html