Table of Contents
DISCLAIMER: This guide assumes that you have prior git knowledge. PLEASE learn git before you attempt this. You WILL break things if you don't.
This year, we are using git flow, a development model to make our repository all neat and pretty.
The main idea is to use separate branches for development and for features. The full blog post can be found here.
- Install the git flow extension.
- Follow these instructions.
That's it, you're done! Now you just need to know how to use git flow. A cheat sheet can be found here
The blog gives a good explanation on how to manually use commands to use the git flow technique. Although this is only recommended for people experienced in git, you can try it if you want. Just don't delete all our code.
So let's say you have a great idea for the robot, such as better code for the shooter or something. How would you put this code on GitHub?
If you haven't already, clone the repository into a folder:
git clone https://github.com/RoboEagles4828/2018Robot.git
Now cd into the repository.
If you are using the git flow extension, set it up using:
git flow init
Since all features must branch off develop, make a branch from develop:
With extension: git flow feature start <name>
Without extension: git checkout -b <name> develop
Type up your code in whatever text editor you choose, and commit using:
git commit -a -m "Title message" -m "Description (optional)"
Now, connect your branch to the remote and push your commits:
git push --set-upstream origin <name>
EXTENSION USERS: This is EXTREMELY important! DO NOT use git flow feature finish <name>! Since our branches have protection, this will break things, most likely deleting your code!
Go to GitHub. On the repository page, you should see a tab labeled "Pull Requests". Click it.
On the right hand side, click "New pull request".
Near the top of the page, there should be 2 dropdowns, each with master selected. Switch the base one to develop and the compare one to your branch. Click "Create Pull Request".
Create a nice title for your pull request, and click "Create pull request".
Near the bottom, you will see some checks. You must wait for these to finish before merging.
You will also need a person to review your code. Just contact any programmer on Slack, and they'll probably look it over for you and merge it.
Now that the code is in develop, it is officially a part of the robot code!
We've all experience this before. You get to the shop, get out your computer, open up IntelliJ (or, god forbid, Eclipse), and sit there for 30 minutes, not knowing what to do.
Say no more. Introducing: Issues and Projects
Issues are basically problems with the code, and Projects are a place to store all the TODO's and such.
Found a bug in the code? Want a feature to be implemented on the robot? Here's how to make an Issue.
- Click the "Issues" tab on the toolbar.
- Click "New Issue".
- Type the Issue and click "Submit new issue".
- On the right side, assign people to the Issue.
That's it for making an Issue
Projects can be found at the GitHub organization page or the repository page in the "Projects" tab. This is basically a running list of things to do.
If you want to do a thing, click the dropdown arrow and then "Convert to Issue". This allows you to make an Issue for that card. When finished, drag to the appropriate section.
GradleRIO is a powerful plugin that allows FRC teams to produce and build their code without being limited to the Eclipse IDE. It allows you to use it with Eclipse, IntelliJ IDEA or any IDE of your choice. GradleRIO also allows you to build and deploy your code to the RoboRIO from the command-line. Finally it has a myriad of small but useful benefits over the default build system like lowered deploy times, better dependency handling, and the ability to easily integrate unit tests.
See here for more information.
In the past we've had to put up with the ANT build system supplied by FIRST but due to its limitations we decided to switch to GradleRIO for the 2017 season and onward.
GradleRIO can be used in IntelliJ and Eclipse (but why would you use Eclipse?). This guide will be focused on IntelliJ because I hate Eclipse.
Just get it from the site.
Install the most recent JDK from Oracle. Follow the prompts.
You should have this done, but if you haven't, use this command:
git clone https://github.com/RoboEagles4828/2018Robot.git
Don't forget to cd into the directory.
Run this command to set up the workspace:
Windows: gradlew idea
OSX/Linux: ./gradlew idea
Go into a file explorer and open the directory with the files. Double click the .ipr file.
When in IntelliJ, there should be a pop-up that asks you to import the project as Gradle. Click import.
Click "Import" to use the default options.
There is a chance that your JAVA_HOME variable will not be set. If you run into a problem with importing in the last step, follow these instructions to set it.
That's it! You're now all set to mess with the code.
These practices are good for everything. Use them.
- Try to use an insightful title. Bonus points for including the specific error if you can figure it out, but keep things concise (one line).
- Great: "Null pointer exception in Toaster class when setting temperature" or "Out of memory error while saving custom temperature preset"
- Good: "Problem with vision when running with toaster mode on" or "Pancake cooking functionality?"
- Not good: "The robot broke" or "I want something to be added"
- Include exactly what happened if the Issue is about a bug. Try to be as specific as possible, and document the exact steps that you followed to produce the issue. If you have logs, error codes, or dumps, you should include those inside code blocks in the Issues. A sequence of three backticks (`) indicate the start and end of code blocks.
- Don't use Issues for random information, such as documentation. See here for an example of what not to do.
- When referencing other Commits, Pull Requests, or Issues, use it's
#code. This can be found next to the name of the commit/issue/pull request. Example "Jackie, you totally broke the whole robot in #123" - When writing a title for anything, use the imperative form of the verb.
- Good: "Fix Vision"
- Not good: "Fixed Vision"