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
CVSweb