Contribution Guidelines

This team is inclusive, so we're not to strict about code contributions. However, there are still some rules that need to be followed.

Git

Branching

When should I ...?

• Create a new branch: whenever you are going to add a feature or fix bugs and it will take more than one day/commit, make a new branch.
• Merge branches: when your feature is entirely complete and tested.
• Commit directly to master: when your change is completely self-contained (just one commit), compiles, and has no chance of breaking anything.

The rules of branches:

• All code in master must compile, and if possible, should be tested. The purpose of master is to always be safe to make a new branch from, without inheriting bugs or errors from other people's code.
• Development branches are for work-in-progress changes, and should compile (as it always must in professional environments), but it's okay if it sometimes doesn't, e.g. if you're in a rush to get to debrief and can't finish your work.
• When we have a full tested branch, make a new version branch off master. That way, if everything goes horribly wrong, we have something that works at competition, or to use for driver practice.

Issues

We use GitHub issues to track our work. They should be detailed, both for other people, and more importantly because we copy down the information there to the Engineering Notebook.

• When you come up with a new feature or find a bug: create an issue detailing the idea/problem and add a label (e.g. bug, feature, refactoring, enhancement).
• When you start work or have been assigned by a lead to work on something: assign yourself to the issue on GitHub so we can keep track of who's working on what. Don't forget to move the issue to "In Progress" on the project board!
• As you make progress: write about your changes in the issue so that other people can pick up your work, and for the engineering notebook.
• When you finish: close the issue!

If you're not sure what to do, you can pick up an unassigned open issue from the project page.

Formatting

Style

We use the usual formatting style and variable naming conventions. If you're not sure what this means, ask the team lead.

Comments

Most methods and classes should have JavaDoc explaining what they are used for and how to use them. At the very least, all public interfaces should include it. Use @param and @return when possible.

If your method is more than a few lines long, it should probably have comments describing how it functions. Remember, it should explain why the code does what it does-- i++; // adds 1 to i is not a very helpful comment!

Additionally, try to avoid using magic values. Use static final named constants instead.

Make sure you disable Android Studio autogenerated "created by HazenRobotics" comments. They are entirely worthless and should not be there. Remove ones that already exist.

Never commit commented-out code (at the very least, don't put it in master)! You can always use Git history to see your old code, and comments just make the codebase messy. If you need help with doing this, just ask someone more experienced with Git(Hub).

Warnings

When you merge code into master, it should generally not have any warnings, since a big pile of warnings makes it difficult to see what warnings are actually from your code and relevant to you. Try to fix any warnings (if you're not sure how, ask someone more experienced), and if they are truly irrelevant, use @SupressWarnings so that nobody else has to look at them.