Contribution guide

So, you want to help develop Brogue CE? Thank you!

We have a Discord server for contributors; feel free to join it: https://discord.gg/8pxE4j8

There are some ports of CE. They adopt all our changes, but you can contribute to port-specific parts at their repos:

• Web Brogue: https://github.com/flend/web-brogue
• iPad: https://github.com/btaylor84/iBrogueCE

For general help on using GitHub: https://docs.github.com/

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 significant gameplay changes for the next minor-point release
• release for bug fixes and less significant changes, for the next patch release. It is merged into master periodically.

If you need to change gameplay code on branch 'release', use the BROGUE_VERSION_ATLEAST macro defined in Rogue.h to avoid breaking previous replays.

Commits

I squash most PRs to one commit, so you can work how you like on your branch.

For multi-commit PRs, I find a clear Git history very beneficial to work with, so I care quite a bit about how they are presented.

Please read my tips for using Git effectively, 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 .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:

  // 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):

  // 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

  // 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) {
  
      ...
  }