GitHub Guide - UTRA-ART/Caffeine GitHub Wiki

Creating issues

During development, you may realize a feature is missing or that we have a bug.

To create an issue, navigate to the issues tab in GitHub, then click New Issue. Then click the green button saying Get Started.

You should now be in a webpage to create the issue. For the title, assign a priority (e.g. P0 for must have, P1 for should have, P2 for nice to have, etc). If you don't know about the priority of a task, please ask someone. Also think of a name that describes the issue. For example, if you want to create an issue for enabling traversal during night, and say we only plan on using this feature for demonstrations. A suitable title would be P2 - Enable traversal during night. This example is a trivial example so note that.

Now fill in the template as instructioned. Roughly, the description is just a brief description of what you aim to accomplish. For example, for the issue mentioned above,

  • Description could be: During night, it's too dark for our cameras to capture useful images, causing navigation to fail. We should implement a feature to add lights to enable nighttime traversal.
  • Goals could be: Successfully have the robot navigate through the competition course during night
  • Acceptance criteria could be: Robot lights are turned on when it's dark and Robot planning works identical to when it's daytime

When formatting it, make sure each point is it's own checklist.

Now, for assignees, assign the person in charge of the task. This could be you, or another person. If you are assigning another person, give them a heads up that they will be doing this task. Under projects, add the relevant project it's under. The example we've been using so far would go under Navigate Autonomously. If you find none of the projects are sufficient, please add a new project. You can also optionally add labels, but we typically don't do this.

Making changes

Please consult the git guide here. This will walk you through things such as creating a branch, and the guideline we follow for branch names. Remember that the branch name should be CAFF-NUM where NUM is the number of the issue!

Creating Pull Requests

Once you think you're ready to merge your code into master, you should create a pull request. This will merge your changes into master. When you push your code, you should see a link automatically show up in teriminal. You can copy and paste that to make your pull request. Alternatively, you can go to the Pull Requests tab, and then click New Pull Request. If you want to merge to master, you should place master as the base, and <your-branch> as the compare branch. If you wish to merge to a different branch, you can change the base (but this is generally not necessary). Now create the pull request by clicking Create Pull Request. In general, you should try to make Pull Requests small to make it easy to review.

When titling your Pull Request, put the title as CAFF-NUM - title of what you did. For example, for the night traversal example, CAFF-NUM Night Traversal might be a suitable title. Note NUM corresponds to the issue number!

Now leave a brief explanation giving context about the Pull Request. What you write is up to you, but I recommend including the following information:

  • What you changed (briefly)
  • How to test your changes
  • Justifcations for any design decisions that you feel a reviewer should know about

It's also very important that you link an issue to your Pull Request. You can do this by typing a closing word followed by the issue number. For example, if I typed closes #NUM, it will automatically link the issue. The # symbol is necessary. You can also manually link issues if that is easier by visiting the issue and clicking Linked Pull Requests.

You should more or less assume that the person reviewing your code doesn't know what they're looking at (because that probably is the case), so giving enough information so that someone can read your changes and understand is good.

Now assign reviewers to review your code. Try to select about 2-3 members who you think will understand what you did. Make sure that they did not actually work on the task directly. When in doubt, just assign a lead as a reviewer. For assignees, assign the people who worked on the task (e.g. you and maybe a partner). You can also fill in the other relevant parts (like projects, etc).

Now, you should create the Pull Request, by clicking Create Pull Request. Afterwards, you need to wait for your reviewers to review your code. If they request changes (by commenting on the Pull Request), you should either justify your decision and explain why a change isn't necessary, or address the the comments by updating your branch with whatever changes you need. Eventually, you will get approval. Once code is approved, it can be safely squash and merged by pressing the Squash and Merge button. Note it's on the developer to merge, not the reviewer. There are a few other options you can do too, but squash and merge is what we typically do.

Once you merged your code, please delete the branch by clicking Delete Branch. This helps keep things clean since having too many branches gets messy really fast.