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
CVSweb