Contribution Guidelines

Across Momentum Mod, we make a lot of effort to keep both our codebases and Git histories clean - on a volunteer project with lots of sporadic contributions from developers with varying skill levels, it's easy for repos to get messy.

Linting and Formatting

Throughout this repo we use ESLint for linting and Prettier for formatting.

We highly recommend you use plugins in your editors for these, especially so it can highlight errors brought up by ESLint (and often offer fixes).

By running npm install you'll have setup commit hooks that run both of these tools when you make a commit. Prettier will automatically format all code you commit - sorry if you have a preferred style, but we really want to eliminate formatting discussions and keep everything consistent! If ESLint finds an issue, in some cases it'll automatically fix it, in others it'll error and your commit will fail, in which case you need to change your code to fix it yourselves. Just searching the offending rule online should find a docs page for it with explanations of the rule and how to fix it.

Commit Messages

Following a rather embarrassing Gitmoji phase, we now use Conventional Commits. By far the easiest way to use this is to glance at the recent Git logs (git log --oneline).

Valid types are build, chore, ci, docs, feat, fix, perf, refactor, revert, style, and test. Valid scopes are front, front-e2e, back, back-e2e, shared, meta, db, utils, discord, twitch (those last two are our upcoming Discord and Twitch bots).

Commit History

With Git we're passionate advocates of rebasing. Rather than creating merge commits between branches, rebasing lets you just plonk the commits from one branch on top of another. In some cases this means force-pushing branches, especially common after interactive rebases. For us, this is completely fine. Just making regular backups doing complex rebases so you can revert back if you screw something up. Here's some rules for how to handle your branch before making a PR:

• Split changes doing different things into separate commits - just standard Git stuff.
• Never make merge commits, always rebase. Sometimes you may have to manually resolve a merge conflict when rebasing, in those cases make sure to first identify any places that can be merged automatically and let your editor/Git client handle those, then for the actual nasty bit, write a non-conflicting version manually. It's usually pretty straightforward!
• Don't make commits that make changes to things added in your branch. If you have some commit "Add X", and another called "Improve X", the second commit is pointless and makes review harder. Instead just fixup the second commit into the first.
• Don't make extra commits addressing changes in code review. Like above, just do an interactive rebase and use fixup. Our goal here is to keep the main branch as clean as possible, and these commits are just irrelevant.

A GUI client can be really helpful. Fork is excellent for breaking up commits and interactive rebasing, and has an unlimited trial period with minimal badgering about payment. Though, it does not have a native Linux client. If anyone has a Linux client they recommend, feel free to add here.

For a general guide on rebasing, especially interactive rebasing, see here. It might be a bit intimidating at first if you're new to Git, but once you've gotten the hang of it you'll have learnt arguably the most powerful single feature of Git.

Finally, if you're having trouble with Git (or anything else for that matter), please feel free to ask for a hand in Discord, don't spend hours agonizing over Git stuff on your own. This is something we're very used to teaching and we're always happy to go through stuff step-by-step.

Toggling Commit Hooks

Commit hooks are a useful way to ensure branch always passes linting, formatting, and commit message checks (and will save you getting told off by the Code Quality CI jobs). There's some disadvantages however - ESLint can take about 20 seconds per commit, and commitlint will stop you making WIP or fixup commits. If you'd prefer to disable, either add --no-verify to git commit commands, or use these aliases to allow toggling hooks with git enable-hooks/git-disable-hooks:

git config alias.enable-hooks "config core.hooksPath .husky"
git config alias.disable-hooks "config core.hooksPath /dev/null"