Skip to content

Creating and reviewing repositories

Jump to bottom
RValner edited this page Feb 7, 2019 · 9 revisions

This guideline contains instructions and conventions for creating and managing repositories in IMS Robotics git organization.

  • If you are just starting to learn ROS and robotics in general, then only pay attention to Naming & Location section.
  • If you are just looking for coding conventions in IMS Robotics, then skip to Conventions & Reviewing

Table of Contents

Prerequisites

Basic familiarity with git is assumed. Git is a great tool and it's surely not made to torture you, instead it's an inseparable tool when working/sharing/versioning/reviewing code. Hence make sure you know about:

  • git clone
  • git status
  • git add
  • git commit
  • git push
  • know about branches and merging

Creating and setting up a repository

Naming & Location

The name of your repository should reflect the state of the project you are developing. Here's the repository naming convention:

  • yourname_otherinitials_sandbox:
    • NB! These repos should be created in https://github.com/ut-ims-robotics-sandbox
    • If you are developing something that you think is not a concrete package yet (maybe its a bunch of launch files that speed up your work), then use this naming convention. So for example "John Huckleberry Smith" should name the repository "john_hs_sandbox".
  • codename_of_the_project:
    • NB! These repos should be created in https://github.com/ut-ims-robotics
    • If your project has a specific codename, say it's a collection of ROS packages that contain driver code for a specific robot "xyz", then the name of the repository should be something along the lines of "xyz_ros_driver".
    • If you are developing, for instance, one ROS package with a name of "example_package", then this name can be the name of your repository.

Reviewing setup

NB! Reviewing setup is not required for sandbox repositories, but feel free to have your code reviewed if you wish.

It is the convention of IMS Robotics lab to review code. This gives the code some quality control and also provides additional experiences to the ones that are reviewing the code.

So if you're creating a repository for your work, any changes that you merge with the master branch has to undergo a review process before the changes are accepted. You can develop and push your code to your development branch without any review requirements, but it is reasonable to merge with the master branch every once in a while - you wouldn't want to review 2000+ lines of code in a single review, would you?

After you have created your repository, you need to set up a rule that forbids automatic merging with the master branch. For that:

1) Click the setting tab

2) Under Branches tab, click Add Rule

3) Set up the rule as shown in the following image

Setting up a development branch

NB! For the sake of clarity, follow the following branch naming convention:

  • yourname-devel
As mentioned before, you should develop your code under a development branch. You can create a new branch via Github web GUI and then directly clone from the newly created branch: 
git clone -b <yourname-devel> <link-to-the-repo>
or you can create a branch via commandline and push the branch to upstream: 
git clone <link-to-the-repo>
cd <name-of-the-repo>

# Create new branch and push it to the upstream
git checkout -b <yourname-devel>
git push --set-upstream origin <yourname-devel>

Pull request & Reviewers

So you have been developing some code that you would now like to merge with the master branch (even if you dont't want to, remember the 2000-lines-of-code argument made before + the reason why we are reviewing code in the first place). For that:

Creating a pull request

  1. Make sure that you have pushed all the changes in your local system to remote branch.
  2. Open the repo in github web GUI and navigate to your yourname-devel branch
  3. Click on the "Compare & pull request" button as shown in the following image

Assigning reviewers

Once you submitted the pull request, you will see something as shown in the image below. Click on the Reviewers button and choose the reviewers.

NB! For now let the first reviewer be one of your supervisors and the supervisor will assign the second reviewer

Conventions & Reviewing

At first this might look like we're splitting hairs over here, but it's way more clear to review and manage the code if some coding and naming convention is established. Here is the following for IMS Robotics:

Coding conventions

IDEs & code formatting

Integrated development environments (IDE), such as Visual Studio Code, Eclipse, etc., help to drastically speed up code development. It's not up to us to force a specific IDE or even force people to use IDEs in general, but keep in mind, that many IDEs support automated code formatting. Of course, there are also non IDE specific tools out there. Here are some that you can apply:

Reviewing guideline

If you were chosen to be a reviewer, you will get a notification via email or github. The notification should take you to the pull request conversation page, which looks like the image below. Click on Add your review button.

Now you can either review the whole thing or address specific lines of code directly:

For example consider this comment:

After you have added relevant comments, click on Review changes button

Then write a general description and click on Request changes if some changes were required


And now essentially you are done. The author will address the comments and the conversation continues until all comments are resolved.

Clone this wiki locally