Contributing
============
For general help on using GitHub to contribute to a project, check out the
[GitHub.com help].
We have a Discord server for discussion; feel free to join it here:
https://discord.gg/8pxE4j8.
## Testing
The *master* branch represents the latest development snapshot, and should be
considered ready for play-testing at all times. If you're a Brogue player, you
can help out by playing the latest *master* and letting us know of any bugs you
run into! Just follow the build instructions (BUILD.md).
## Code
When submitting patches or opening pull requests to Brogue CE, please
attempt to meet the follow guidelines. To avoid wasted work, I recommend
first discussing with us the proposed changes on the Discord or by opening
an issue report.
### Branches and versions
Brogue CE version numbers follow 1.MINOR.PATCH. Essentially, patch-level
releases don't change the gameplay experience in any way--this is to avoid
breaking saves and replays. Minor-point releases may do so.
The are two long-term branches which you should base PRs on:
* *master* is for gameplay changes for the next minor-point release
* *release* is for bug fixes and other non-gameplay changes, for the next patch
release. It is merged into *master* periodically.
Any other public branches may be rebased and force-pushed at any time, so please
be careful when branching from them.
### Commits
I find a clear Git history very beneficial to work with, so I care quite a bit
about how commits are presented in PRs.
Please read my [tips for using Git effectively][Git guidance], which can be
considered guidelines for contributing to this project.
### Change files
When making user-facing changes, please add a non-technical description of each
change to a Markdown (.md) file in `changes/`. These files are collated to
create the release notes.
If the change is from one commit, include this file in it. For a branch of
multiple commits, add it in a separate commit.
### Style
- Use 4 space of indentation
- Be consistent with formatting (pay attention to whitespace between brackets,
commas, etc.)
- Try to follow the style of existing code
- Declare functions and variables local to a file as `static`
- Prefer `int` in new integer declarations; use `short` only when working with
existing `short` variables
- Use braces for control structures on multiple lines
```c
// no
if (cond)
action();
// yes
if (cond) {
action();
}
// acceptable
if (cond) action();
```
- When writing bracketed lists over multiple lines, wrap it naturally and don't
align to the open bracket (this includes declarations)
```c
// yes
some_function(
a, b,
c,
d
);
// no
some_function(a, b,
c,
d);
```
- When writing multi-line if/while conditions, use at least the same indentation
as the body. It can be clearer to over-indent to separate it
```c
// same indent is ok
while ((A && B)
|| C) {
...
}
// over-indent can be clearer
while ((A && B)
|| C) {
...
}
// a gap works too
while ((A && B)
|| C) {
...
}
```
[GitHub.com help]: https://docs.github.com/en/free-pro-team@latest/github
[Git guidance]: http://www.collider.in/tom/git-guidance.html