diff --git a/Contribution-guide.md b/Contribution-guide.md new file mode 100644 index 0000000..2d4e83e --- /dev/null +++ b/Contribution-guide.md @@ -0,0 +1,127 @@ +So, you want to help develop Brogue CE? Thank you! + +We have a Discord server for contributors; feel free to join it: + + +There are some ports of CE. They adopt all our changes, but you can contribute to port-specific parts at their repos: + +- Web Brogue: +- iPad: + +For general help on using GitHub: + +## How you can help + +- **Test** the latest changes on the *master* branch, and let us know what you + think and report any bugs you run into! See [[Playing dev versions]]. + +- **Fix bugs.** See issues labelled *bug*. (Also see *good first issue* for + suggested starter fixes.) + +- **Implement approved features.** Tickets with the *enhancement* label have + been greenlit and just need someone to pick them up! + +- **Add detail to ideas and tickets.** Unlabeled but open tickets just need some + more attention or discussion to decide what they really mean and whether we + want to try them. Turning a vague feature idea into a more detailed + description can be useful to figure out edge cases and also helps whoever + might implement it. + +- **Improve the tiles** or make new alternative tile sets. + +## Pull request guide + +### Base branch + +Brogue CE version numbers follow 1.MINOR.PATCH. Except in rare circumstances, +gameplay changes are only allowed in minor releases. + +PRs should be based on: + +* *master* for gameplay changes for the next minor-point release +* *release* for bug fixes and other non-gameplay changes, for the next patch + release. It is merged into *master* periodically. + +### 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. + +[Git guidance]: http://tmewett.com/git-guidance/ + +### Change files + +When making user-facing changes, please add a non-technical description of each +change to a .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. + +## Code style + +- Use 4 spaces of indentation. +- Be consistent with formatting (pay attention to whitespace between brackets, + commas, etc.) and try to follow how existing code looks. +- Declare functions and variables local to a file as `static`. +- Prefer `int` over `short` in new integer declarations. +- Some existing code declares all variables at the top of functions, but this isn't necessary to replicate. +- 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, but... + while ((A && B) + || C) { + ... + } + + // over-indent can be clearer + while ((A && B) + || C) { + ... + } + + // a gap works too + while ((A && B) + || C) { + + ... + } + ```