Using Git - struct-by-lightning/wpi-suite GitHub Wiki

This tutorial will run you through everything you will have to do to add a new feature to the project.

Creating a New Feature Branch

Most of the time you shouldn't have to do this, as branches should be created within the team repository by the release engineer after notification of a need for a new feature branch by the process engineer. But just in case you do need to create a new branch, such as to test out an idea without messing with the feature branch.

The first step here is to navigate to the repository within terminal. Following this, you need to create the new branch. To do this, enter the following command into terminal:

$ git branch new-feature-name parent-branch

This creates a new branch named new-feature-name that is a copy of parent-branch. For our purposes, you will almost always be creating a new branch off of the sbl-dev branch. So if you are adding a new feature to display the Planning Poker numbers, you would enter something like the following.

$ git branch display-numbers sbl-dev

Now, you need to switch to the new branch, in this case display-numbers. You use the checkout command for this.

$ git checkout display-numbers

However, this branch still only exists locally. So now you need to push the branch to your remote repository, using the push command.

$ git push origin display-numbers

Modifying the branch

Now you are ready to start modifying or creating files to add the feature!

Committing and Pushing Changes

So now you've gotten a portion of the new feature working, with all of its tests passing? You should probably commit it.

The first step to do this is to use the add command to add all modified files to what will be committed. To do this you enter the following into terminal:

$ git add all

That will add all of the changed files in the repository. If you only want to commit changes to specific files, then you would instead list the names of all the files:

$ git add file_1 file_2 file_3 ... file_n

The next step to commit is to actually make the commit, using the commit command, like below:

$ git commit

This will open up an emacs file with which you should enter your commit message. You should follow this standard for commits, outlined by Linus Torvalds:

A good commit message looks like this:
 
	Header line: explaining the commit in one line
 
	Body of commit message is a few lines of text, explaining things
	in more detail, possibly giving some background about the issue
	being fixed, etc etc.
 
	The body of the commit message can be several paragraphs, and
	please do proper word-wrap and keep columns shorter than about
	74 characters or so. That way "git log" will show things
	nicely even when it's indented.
 
	Reported-by: whoever-reported-it
	Signed-off-by: Your Name <[email protected]>
 
where that header line really should be meaningful, and really should be
just one line.  That header line is what is shown by tools like gitk and
shortlog, and should summarize the change in one readable line of text,
independently of the longer explanation.

Once you've written up the commit message, hit CTRL-X, followed by Y to save the message, and then ENTER to exit and submit the commit.

However, the commit only exists on your local repository. It needs to be pushed to the remote repository. You use the push command for this:

$ git push origin display-numbers

This will update the remote display-numbers branch with the commit.

Submitting a Pull Request

So you've worked on the feature, and finally finished and bugtested it, and it works. But how do you get this into the team repository? The answer is a pull request.

To submit a pull request, go to GitHub and navigate to your fork of WPI-Suite. Then change the branch to the feature branch you want to get merged into the team repository. There, hit the green button next to the branch select menu.

This will take you to a page showing the pull requests. Hit the big, green, "Create A Pull Request" button. This brings you to a page where you can fill out the commit information. Make sure to use the same commit style as outlined above! Once you're finished detailing the commit, hit the submit button!

Then a release engineer will take a look at the pull request, and it will be merged into the sbl-dev branch on the team repository.