Return to CONTRIBUTING.md CVS log

Up to [contributed] / brogue-ce

Annotation of brogue-ce/CONTRIBUTING.md, Revision 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