Thank you for contributing to the team's code base! However, before submitting your contribution, please make sure to read the following guidelines carefully.
🚨 Please be sure to check out the branch workflow and commit style guide, prior to contributing 🚨
Clone the project on GitHub.
$ git clone git@github.com:ftc16626/Skystone-2019.git
$ cd Skystone-2019
Develop and build the project using Android Studio. This GitHub repo contains the default code styling format to be used by Intellij in .idea/codeStyles. Intellij should now be able to format your code. Please do so before every commit. It is good practice to do so regularly (Intellij lacks a format on save option so please do so manually). If you have any complaints, please see the footnote at the bottom of this page.
Checkout the dev
branch to start contributing. Any major features should have their own branch.
Never make a pull request directly to the master
branch. All PR's doing so will be rejected.
When contributing to dev
$ git checkout -b dev
When creating a new feature branch
$ git checkout -b feature-myname -t upstream/dev
Check out the branch workflow for further details.
Please keep your changes grouped logically within individual commits. This makes it easier to review changes that are split across multiple commits.
$ git add my/changed/files
$ git commit
Please adhere to the commit style guide
It is preferred to use git rebase
instead of git merge
to synchronize your work with the main
repository, once you have committed your changes.
$ git fetch upstream
$ git rebase upstream/dev
This ensures that your working branch has the latest changes. If you'd like to read on why rebase is preferred, please refer to Atlassian's great tutorial
Please make sure the changed code builds in Android Studio.
Ensure that your code is properly formatted (press ctrl+alt+L) in Android studio for formatting.
Ensure that your commits follow the style guide
Ensure that you are on the correct branch (follow the branch workflow
Once done, push your changes to the dev
branch.
$ git push origin feature-myname
From within GitHub, open a new pull request. Be sure to detail what changes have been made.
The project will adhere to the Git Workflow by Vincent Driessen. Atlassian provides a great article for a high level read on the Git Workflow (https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow.
To surmise the branch workflow:
- Contributors should not (usually) open pull requests to the
master
branch.master
serves as a snapshot of the latest, stable code release to be used at competitions. - Development should be done on the
dev
branch.- The admin will merge
dev
tomaster
when necessary.
- The admin will merge
- Major features (new drive-train code, new autonomous code, etc.) should have their own branch (off
of the
dev
branch). - These branches should be namedfeature-myname
. - This is encouraged so that major features can be developed in isolation, without side-effects. - Feature branches will be merged intodev
when necessary. - Any direct pull requests to the
dev
branch should be minor features or bug fixes. - Pull requests can be made to the
master
branches in the event of ahotfix
.- Hotfixes are critical errors that must be corrected in production environments (like if the code is broken during a competition).
- Hotfix branches should be named
hotfix-fixname
- The
hotfix
branch should be merged into bothdev
andmaster
.
The commit style guide is adapter from Electron's commit message guidelines.
A commit message should describe what changed and why. It should follow the semantic commit messages to ensure consistency and a streamlined release process. Commits must have a title and semantic prefix prior to merging. Examples of commit messages:
fix: don't overwrite prevent_default if default wasn't prevented
feat(MainActivity.java): add app.isPackaged() method
refactor(RefactoredFile.kt): fix teertho's mistakes
A common appending the prefix indicates a specific file change. This should be used if only a single file was changed.
Common prefixes:
- fix: A bug fix
- feat: A new feature
- docs: Documentation changes
- build: Changes that affect the build system (gradle)
- refactor: A code change that neither fixes a bug nor adds a feature
- style: Changes that do no affect the meaning of the code (linting)
This project will adhere to the code style included within the project (located in
.idea/codeStyles). The code formatting options is based on Google's Java
Codestyle Guidelines and
Kotlin's default coding conventions.
This means that by default, the Java files will use 2 spaces per tab and Kotlin files will use 4
spaces. The purpose of adhering to the Google style guide is to be able to use consistent formatting.
This is important when committing to git so git blame does not log unnecessary changes based on
differing formatting options. You may use whatever tab style you want on your own but please
format your code based on the project guidelines (press ctrl+alt+L
) before every commit.