created: 20200702091026430
modified: 20200707005526287
section: 4.2
tags: lab02
title: /Labs/02/Topic Branches
type: text/x-markdown

The 'master' branch is the primary/default branch in a Git repository.  It is where the primary version of the code usually resides.

When working in a team it is important that you keep the master branch 'clean' --- that means that there should never be incomplete or broken code in the master branch.   There are two good reasons for this:

* If you are working on a feature, but don't have it working yet, and you push your broken code to the master branch of a shared repository then you will effectively break all versions of the project for all of your team mates.  Your team mates are unlikely to be happy with you for doing this.

*  In order to avoid merge conflicts you should be regularly pulling from the shared repository so that you are always working on the most recent version of the code.  If you are doing all of your work in the master branch then you will need to merge your code with the changes coming from other developers, and you will likely need to regularly deal with merge conflicts (which is what you were trying to avoid by regularly pulling in the first place).

To avoid these problems we can use 'topic' branches (sometimes also called 'feature' branches).  A topic branch is a branch that you create to work on an issue.  You create and switch to the branch and work on the issue, and don't merge the branch back into master until the issue is resolved and tested.  Since you are working on a branch that is not master then you are isolated from other developers.

Let's create a simple menu form that allows the user to access the main features of the system:

1.  First we should add an issue to GitBucket.  We are adding a menu that allows the user to access the main features of the system, so create an issue that that describes this feature.

2.  Before continuing, we should ensure that our repository is fully synced with the remote repository (we are pretending that we are working with a shared remote repository where other team members are regularly pushing their own changes):

    * Commit the entire project.  <<menu "RCTP > Git > Commit">>.

      The only way you can lose work in Git is by not committing it.  We are committing here in case we have to perform a merge when syncing with the remote server --- if all of our work is committed then it will be included in the merge.

    * Pull from upstream.  <<menu "RCTP > Git > Remote > Pull from Upstream">>.

      This ensures that we have the latest version of the code in our local repository.  If you are working with an out-of-date version of the code then you may find that when you try to push, you get a merge conflict because another team member has also worked on the same code as you.  It is good practice to pull before you do anything --- it dramatically reduces the amount of merge problems you will encounter.

    * Push to upstream. <<menu "RCTP > Git > Remote > Push to Upstream">>.

        This ensures that the shared repository includes any changes that you have made.  The longer you wait before pushing then the larger the window is for another team member to push changes to the same code.  If this happens then you will be forced to pull (Git will insist that you pull if it detects that the remote branch is ahead of your local branch), and you will have to deal with a merge conflict.

    If you are regularly having to deal with merge conflicts then it is YOU that is causing it --- Git problems are largely self-inflicted.  Commit, pull, and push (in that order) regularly to ensure that your local repository is synced with the remote server --- doing this regularly will avoid most of the problems.  You will always want to do this before starting on a new issue.

3. Now we need to create a topic branch for this issue.  <<menu "RCTP > Git > Branch/Tag > Create Branch">>.

   Enter `topic/main_menu` as the branch name.

   Make sure the <<menu "Checkout Created Branch">> checkbox is ticked.

4. Look at the branches using the repository browser pane (<<menu "Branches > Local">>).  You should now be able to see that your repository is using the `topic/main_menu` branch since it will be bold --- the bold branch is the current branch.

    You should also be able to see the current branch beside the root of your project in the projects pane.  If you don't see this then you should enable this using the <<menu "View > Show Versioning Labels">>.

    Any commits that are made at this point will go into the topic branch rather than `master`.  When working with branches you need to keep an eye on the current branch.  It can be easy to add commits to the wrong branch if you aren't paying sufficient attention.

5.  Create a Java Swing Dialog using <<menu "File > New File > Swing GUI Forms > JFrame Form">>.

    Name the file `MainMenu` and put it in a package named `gui`.

6.  The NetBeans GUI editor will open up.  Play around with it.  The lo-fi mockup for the menu looks like the following:

    {{/Labs/02/images/Main Menu Mockup}}

    The big boxes represent buttons.  You can drag and drop `JButton` components from the component palette onto your form.

    We will give you more information on how to work with the GUI editor in  next week's lab.

7.  Commit your `gui` package.  Remember to reference the issue.

9.  Before merging the topic branch, we need to sync it with the remote master so that it includes any changes made by team members.  First we need to update the local master:

    *  Switch to the master branch using the the repository browser.  Right click the local master branch, and then select <<menu "Checkout Revision > Checkout">>.

    * Pull from upstream.

    Now we have the latest code in the local master.

10.  Switch back to the topic branch again.  Right click <<menu "topic/main_menu > Checkout Revision > Checkout">>.

11.  Merge the local master branch.  Right click <<menu "master > Merge Revision">>.  The default settings are fine, so click <<menu "Merge">>.

     Note that merge operations are performed in the current branch.  You need to first checkout the branch (which we did in the previous step) that you want to perform the merge in.

     Your topic branch is now fully up to date and includes all changes that are in both the remote and local master, and should be able to be merged back into master without any problems since everything is based on the most up-to-date code.

12.  You should test your system to ensure that nothing was broken by merging the remote changes.  There is not much for you to do here other than checking that your menu still looks OK.  If you had automated tests (we will start adding tests in next week's lab) then you would run those tests to check the system.

12.  Switch back to master by checking it out.

     Uh oh, your menu just vanished from your project.  That is expected --- that work currently only exists in the topic branch since it hasn't yet been merged into the local master yet.

13. Merge the topic branch.  Right click  <<menu "topic/main_menu > Merge Revision > Merge">>.

    Your menu should be back, since we have merged the topic branch back into master.

14.  Push to upstream to share your completed work with the rest of the team.

15.  Check GitBucket.  You should be able to see your `MainMenu` class.

16. The following is more of an FYI.  You don't have to do anything here for this lab.

    Topic branches are temporary branches that can be deleted once they have been merged back into master, and generally don't need to be pushed unless you have a good reason to do so.  You might want to push a topic branch to a remote server if you want another team member to take a look at your work, or you need to use more than one computer (which is common if you need to test the code on a different environment, or you are working from multiple locations).

    To push a branch you use <<menu "Push...">> rather than <<menu "Push to Upstream">>.  You will be asked to choose which branches you want to push, and you can select your topic branch.

    You should delete the remote topic branch once you are finished with it, otherwise you could end up with hundreds of useless branches on your git server.   You can delete remote topic branches in the repository browser by deleting them from the <<menu  "Branches > Remote">> and selecting <<menu "Delete Branch">>.  You have only deleted the local version at this point --- you still need to push the deletion --- use <<menu "Push...">> rather than <<menu "Push to Upstream">>.  You will need to click the <<menu "Enable Deletes">> button before NetBeans will let you select the deleted branch.

17.  Delete the local topic branch by right clicking it in <<menu "Branches > Local">> and selecting <<menu "Delete Branch">>.  If a dialog pops up telling you that the branch has not been properly merged then may have messed up the merge.  Go back and work through steps 12 and 13 again.

18.  Close the issue since we have completed the associated task.  You can do this from GitBucket.  Open the issue, and click the little up arrow to the right of the <<menu "Comment">> button.  Select <<menu "Close and comment">>, and then click the <<menu "Close and comment">> button.

It is up to you whether you want to use topic branches in INFO202.  There is some benefit to using topic branches even in a single-developer scenario --- it allows you to work on multiple issues at the same time (not recommended, but occasionally necessary if you need to fix a bug in another part of the system while still working on an incomplete feature).  You can also use topic branches to work on experimental code that you are not sure will work --- if the experiment doesn't pan out then you delete the topic branch without ever merging it into master.

You do need to be careful though.  If you aren't regularly merging your branches (first, master into your topic branches, and then your completed topic branches into master) then you can make a mess.

If you aren't confident with using Git then you should stick to doing all of your work in the master branch.