Skip to main content

Project Management with GitHub

GitHub is a web-based platform that allows us to host our code and collaborate with other developers. It provides a user-friendly interface for managing our code and tracking changes made to it. GitHub also allows us to create pull requests, which are a way to propose changes to a repo and have them reviewed by other developers before they are merged into the main branch.

We have a GitHub organization for our team, which is where all of our repos are hosted. You can find our organization at FRC-Team-4143. When you push or pull changes to a repo, you are sending to one of the repos in our organization.

Clone​

If the project you are going to work on is already hosted on GitHub you can clone the repo to your local machine. This will create a local copy of the repo that you can work on. You can clone a repo using the following command.

git clone REPO_URL
Finding the REPO_URL

You can find the repo URL on the GitHub page for the repo. There are two options, HTTPS and SSH. If you are not sure which one to use, use the HTTPS option. If you are using SSH, make sure you have your SSH key setup with GitHub. For example using this projects repo as an example the REPO_URL may either be

  • SSH_URL: git@github.com:FRC-Team-4143/FRC-Team-4143.github.io.git
  • HTTPS_URL: https://github.com/FRC-Team-4143/FRC-Team-4143.github.io.git

This will create a new directory with the same name as the repo and download all of the files in the repo to that directory. You can then navigate to that directory and start working on the code.

Pull Requests​

A Pull Request (PR) is a way to propose changes to a repo and have them reviewed by other developers before they are merged into the main branch. This is a good way to ensure that the changes are correct and do not break anything in the main branch. You can create a pull request from GitHub and have your peers review your changes before merging.

You can create a pull request by going to the GitHub page for the repo and clicking on the Pull requests tab. From there, you can click on the New pull request button and select the branch you want to into your selected target branch. You can then add a title and description for your pull request and submit it for review. The PR will show all the changes made in that branch and allow your peers or mentors to review your changes before merging. They can leave comments, request changes, or approve the pull request. Once the pull request is approved, you can merge it into the target branch.

Some PRs even have automated checks that will run to ensure that the code is correct and does not break anything. This is a good way to catch errors before they are merged into the main branch.

Issues / Tasks​

Issues are a way to track tasks and bugs in a repo. They allow us to create a list of tasks that need to be completed and assign them to team members. Issues can be created from the GitHub page for the repo and can be assigned to team members. You can also add labels and comments to issues to help organize them.

We like to use issues to track the progress of our projects and see what each team member has been working on. This allows us to prioritize tasks and ensure that everyone is on the same page. They are typically assigned a "Story Point" value to indicate how long the task will take to complete. They are also typically given a label to indicate what type of task it is. Some of our labels include:

  • bug: A bug that needs to be fixed
  • auto feature: New auto routines or changes to the auto framework
  • documentation: Improvements or additions to the documentation
  • robot feature: New robot code feature
  • tools: Update or interfacing with FRC tools
  • And many more!

You should try to update the comments or status of any issues you worked on. This allows us to see the progress on any given issue and offer help if needed.

Project Board​

The issues are attached to a repo, but can be added to a project board. The project boards allows for us to organize our issues and tasks into a kanban style board. This gives everyone on the team a quick overview of what tasks are being worked on, what tasks are completed, and what tasks are still in progress. You can see our project board used for off-season projects at Offseason Projects.

Each issue is sorted into a column based on its status. The columns in our typical project template are:

  • Backlog: Issues that are not yet ready to be worked on
    • These could be issues that are not fully defined, need more information, or are waiting on another task to be completed
  • Ready: Issues that need to be worked on
    • These are issues that are ready to be worked on and have all the information needed to complete them
  • In Progress: Issues that are currently being worked on
    • These are issues that are currently being worked on by a team member
  • In Review: Issues that are ready for review or testing
    • These are issues that have been completed and are ready for review or testing by another team member. Typically this is where you would create a pull request to merge your changes.
  • Done: Issues that have been completed
    • These are issues that have been completed and merged into a parent branch. They are typically closed after they have been merged.

Make sure you assign yourself to any issues you are working on. This allows us to see who is working on what and helps us prioritize tasks. You can also assign issues to other team members if you think they would be a good fit for the task.