P2: Getting Started with OCSF Framework and Chat Application using GitHub
50 points
Due: September 10, 2016, 11:59 PM via Canvas

1. Goals

The overall goal of this assignment is to be able to practice learning the workflow for team projects in CS314. This means knowing how to work collaboratively using Git, becoming familiar with Java packages and jar files, and getting a high-level understanding of the codebase that you will work on.

  1. Objectives for collaborative work with Git:
    1. To properly set up Eclipse and Git to use your GitHub CS314 repository in a local Eclipse project.
    2. To learn the Git workflow we will be using in CS314.
    3. To practice branching and merging your work with other team members' work.
    4. To practice using the collaborative review system at GitHub.
  2. Objectives for learning to use Java packages and jar files
    1. Being able to import packages corresponding to a framework whose code remains unchanged in Eclipse.
    2. Being able to export Jar files containing Java source files in correct packages and in the correct folder hierarchy.

2. Description

To achieve these objectives you will be working on code that we have made available in your team's GitHub repository. This code is from a textbook that we used in our CS314 course for years. The authors of the textbook and the code are Lethbridge and Laganiere, and the website for the textbook is available here. For your convenience, we have put everything you need in your repository. In fact, you must use what we provided in the repository because we have seeded some "faults" and "issues" that you will uncover during the code inspection exercise in Week 4. Later on, we will tell you how to change back to the correct version of the code before you start P4.

2.1. Change code in simplechat1 (10 points towards team grade)

The projects that are available in the repository that you will connect to your local machine git repository in eclipse (steps shown in section 3) as follows:

In this assignment we want you to practice using GitHub and Eclipse without getting distracted by the complexity of adding new features to the application. However, we do need to modify the code in order to create branches, so we will just stick to these simple tasks:

  1. Change the style of using curly braces. The code uses a begin-curly brace on the next line following a class declaration, if condition, for, which, etc. Your task is to make the begin-curly brace appear on the same line.
  2. Change variable names that are abbreviated (e.g., msg, ex, etc) to something longer, and more appropriate and consistent with traditional Java style.

Team members will divide up the task of modifying the code. There are three files to modify (ChatClient.java, EchoServer.java, and ClientCoonsole.java) and three team members. Each team member modifies a different file.

Team Grade: To get full points for this part, you must have changed the curly braces at every location, and changed some variable names.

2.2. Using Eclipse and GitHub (20 points towards individual grade)

Each team member will create their own local Eclipse project that is connected to the team's CS314 GitHub repository. No development may occur directly on the master branch. Each team member will have their own branch to make changes to the files. Each team member must use the GitHub collaboration tools to review proposed changes with all team members. Finally, each team member will merge all the changes into the master branch.

Please refer to the tutorial in Section 3 to complete Section 2.2. Only then move on to Section 2.3.

To get full points for this part:

2.3. Create overview file for project (10 points towards team grade)

After completing Section 2.2, create a file called overview.txt inside the src folder of the simplechat1 project. In this file add the following information

  1. Names of the team members.
  2. Specific contributions by each team member.
  3. Time (in hours) spent by each team member on this project.
  4. The CSU Honor Pledge: "I have not given, received, or used any unauthorized assistance." with each team member's name listed below.

2.4. Create a jar file and submit (10 points towards team grade)

The jar file must be called P2.jar. It should contain the Java source files, not class files, and the overview.txt file only for the simplechat1 project. Submit this file via the Canvas submission system for P2.

Steps for creating jar file in the eclipse workbench (taken from help.eclipse.org):

  1. In the Package Explorer, you can optionally pre-select one or more Java elements to export. (These will be automatically selected in the Opens the JAR export wizard JAR File Specification wizard page, described in Step 4 below.)
  2. Either from the context menu or from the menu bar's File menu, select Export.
  3. Expand the Java node and select JAR file. Click Next.
  4. In the JAR File Specification page, select the resources that you want to export in the Select the resources to export field.
  5. Select the appropriate checkbox to specify Java source files and resources, not class files. Note: This is the step where most students make a mistake.
  6. In the Select the export destination field, either type or click Browse to select a location for the JAR file.
  7. Clear the Compress the contents of the JAR file checkbox.
  8. Select or clear the Overwrite existing files without warning checkbox. If you clear this checkbox, then you will be prompted to confirm the replacement of each file that will be overwritten.
  9. Click Finish to create the JAR file immediately.

To get full points for this part:

3. Tutorial on using GitHub

3.1. Tutorial 1. Setting up Eclipse for Git (EGit)

  1. Set the location for your repositories on your local system. The default location can be changed from Window→Preferences→Team→Git, and is called "Default repository folder". It is often in your home directory, and called "git". This is fine.

  2. Go to Window→Preferences→Team→Git→Configuration. The table lists entries in a ".gitconfig" file, also usually in your home directory. If the table does not have a bolded key called "user", you need to add this with the Add Entry button. The add form requires a 2-part key and a value. You need keys for your email and real name. For the first key, use "user.email", then add your email as the value. For the second key, use "user.name" and enter your name. These values will be used at GitHub.com during communication with the repository, so the email must match the email you used to create your GitHub account. You also need to configure Eclipse so that branch tracking with the GitHub repository works correctly. The key is "branch.autosetuprebase" and its value needs to be "always".

    There are other items you add to the configuration. The Vogella tutorial lists some useful items, for example the key "push.default" with value "simple".

  3. You can add Git commands to the toolbars as follows. Got to Window→Perspective→Customize Perspective. If possible, check the Git box on the "Tool Bar Visibility" tab. If this is grayed out, then go to the "Action Set Availability" tab, check the "Git" box. This will show the actions in the in the Menubar details frame and the Toolbar details frame. Select the OK button. Next check the "Git Navigation Actions" box and select the OK button. You can then go back to the "Tool Bar Visibility" tab and check the Git box.

  4. You can specify which files Git should ignore in a file called .gitignore which is usually in your home directory. The Vogella tutorial lists some of these files, for example binary files.

3.2. Tutorial 2. Connecting Eclipse to Your GitHub Repository

Now you are ready to create a local copy of your GitHub repository that will be used by Eclipse. Steps:
  1. First show the "Git Repositories" view by going to Window→Show View→Other. In the window that comes up, click the expand icon by "Git" and select "Git Repositories".

  2. There are several icons that will be displayed in this view. Mouse over them to find the one labeled "Clone a Git Repository and add the clone to this view" and select it, or click the link labeled "Clone a Git repository".

  3. You need to enter the URL of your repository on GitHub.com. To find this, login to GitHub.com and navigate to your CS314 repository. There will be a text field with the URL to this repository, prefaced with an https. If you don't see this, click the button on the right side labeled "Clone or download", and copy the URL from there. If you don't see this button, click the tab labeled "<>Code" on the upper part of the window.

    Copy this URL to the Eclipse "Clone Git Repository" form. The Host and Repository path fields will be automatically filled in. You can add your GitHub user name and password to be stored locally if you want, or you can leave these fields blank. Click the Next button.

  4. The next window allows you to pick the branches that will be cloned and copied to your local system. The only branch that should exist is "master", and it will be selected by default. Press the Next button.

  5. The next window lists the directory where the clone will be stored, and it is in the default directory that you added to the configuration file, for example your <home directory>/git.

IMPORTANT: Check the box under the heading "Projects" that is labeled: "Import all existing Eclipse projects after clone finishes". This will create two Eclipse projects from the cloned repository. Click the Finish button and the clone and project creation will begin. If you have added your GitHub credentials to the Eclipse Safe Store then the operation will complete without further work from you. If you have not added the credentials, you will be prompted at least once for this information. The two Eclipse projects will be called OCSF and simplechat1.

3.3. Tutorial 3. Branching

  1. The first thing you need to do is make sure your local copy of the master branch for both projects is up to date with the GitHub repository. To do this, highlight the OCSF project name (which should list your team repository name followed by the word "master" in square brackets next to the name) and click the "Pull" icon on the tool bar or right click the project name, go to "Team"→"Pull". This will merge any updates from the GitHub repository for the master branch into your local copy of the branch. Repeat with the simplechat1 project. DO NOT modify the OCSF project for the rest of the tutorial. Only work with the simplechat1 project.

  2. To create a branch, highlight the simplechat1 project name and click the "Checkout a Branch" icon on the tool bar or right click on the project name, go to "Team"→"Switch to", and choose "New Branch". A new window will be displayed. You can get to this same window by clicking on the branch icon in the tool bar, and clicking the "New Branch" button.

    The area labeled "Source:" has a branching icon. Click the "Select" button on the right of this label. A new Select Source window will appear. Expand the "Remote Tracking" listing if it is not expanded, and select "origin/master" as the source and click the "OK" button. The new branch will be to make the changes as specfied in Section 2, so in the "Branch name" field enter your initials and the name "FixCurly" or "Variable". Click "Merge upstream commits into local branch", and click the "Finish" button. The new branch is created, and the project is changed to that branch. This is shown via the branch name in the square brackets after the project name in the Package Explorer view.

  3. Push the new branch up to the GitHub repository. Do this by clicking the "Push" icon on the tool bar or right clicking on the project/branch name, go to "Team"→"Push to Upstream". This will create the branch in the GitHub repository. A window will appear with information about the push. Click OK.

  4. Make changes to the files. Close the files in the editor. Make sure the "Git Staging" tab is shown in your Eclipse window. It has several parts: "Unstaged Changes", "Staged Changes", "Commit Message", "Author", "Committer", and 2 buttons, labeled "Commit and Push" and "Commit". After your changes to the first file, the file name should listed in the "Unstaged Changes" area. Drag this name and drop it into the "Staged Changes" area. Type a descriptive message into the "Commit Message" area. Make it as descriptive as you can - what the change was and why you did it. If there are several files that have been changed, this message should describe why they were changed. Finally, click the "Commit & Push" button. This will commit your changes to the local copy of your branch and push them to the remote. There is a pop-op with OK button to push to the remote. Press OK.

  5. Look at the GitHub repository. You should see that there is a section that lists your recently pushed branch. If you click on this name, the GitHub repository changes to that branch. If you click the "Compare & pull request" button associated with this branch, you will see a new window that is titled "Open a pull request". This is the Pull Request Code Review System we will be using for collaboration. For now, just scroll down the page, and you will see the commits that have occurred for this branch, and further down there is a code listing that shows changes to the files that were made as part of the commits.

    Just above the code listings there are 2 buttons, "Unified", and "Split". If you click the "Unified" button you see the code changes within a single listing window, and if you click the "Split" button you see file changes side‐by‐side. DO NOT open a pull request – instead scroll back near the top of the window and click the tab labeled "<> Code" to take you back to the main repository page.

  6. Continue making changes and push the commits to GitHub.

  7. Update the overview.txt file with your contributions and your statement of compliance to the CS honor code, then proceed as in step 4 of Section 3.3 to stage, commit, and push the changes to your branch.

3.4. Tutorial 4. Merging Part 1: Merging the remote master to your local working branch

The CS 314 development process requires that the master branch always is deployable. So you need to add your changes to it in two parts. The first part is to make sure that any changes that have been already added to the master work with your proposed changes. This is covered in tutorial 4. The second part is to request a code review from your teammates, and when any issues have been resolved, to merge your changes into the master branch. This second part is covered in tutorial 5.

The Egit help documentation has screen shots of the various operations described below. It can be found here. Expand the EGit Documentation section, go to "EGit User Guide", then "Tasks", then "Merging", and then "Merging a branch or a tag into the current branch"

You now need to merge any changes made on the remote master into your local branch. Then you need to push these changes from your local branch to the GitHub repository, and then merge them into the master on the remote. Do this as follows.

  1. First close any files that are open in the editor. Then switch branches in Eclipse to the master branch. Do this by right clicking on the project name and choosing the Team→Switch To command, and choose the "master" branch. Alternatively, you can click the branch icon in the toolbar, which will open a window titled "Branches". Expand the "Local" section and click on the "master" branch. Next click the "Checkout" button, which just actually switches you to the master branch in your local repository.

  2. Merge any changes from the GitHub repository to this local copy of the master. To do this, click the "Pull" icon on the tool bar or right click the project name and choose Team→Pull.

  3. Switch branches to the branch where you have made changes.

  4. Merge any changes from the GitHub repository on your branch to this local copy of the branch, just like you did for the master branch. If you are sure that you are the only person who is working on this branch and if you have pushed all of your local commits to the GitHub repository you can skip this step.

    Merge the local master branch into your local changed branch. The merge will be using your local branches. Click the "Merge" icon on the tool bar, or right click on the project name (which should indicate that the current branch is one of your changes), and choose the Team→Merge command. A new window will appear.

    The local branch you are viewing is marked with a check mark. Click on the name of the local master branch. Select the "Commit" radio button to commit to the merge. Click the Merge button.

    There shouldn't be any conflicts, but if there are, you must resolve them. The EGit user documentation can help ("EGit User Guide", then "Tasks", then "Merging", and then "Resolving a merge conflict", and the Vogella tutorial has a section on resolving conflicts (section 21.2). EGit has a Merge Tool to help resolve conflicts. If there are conflicts, you will be making changes on your local changes branch to resolve them. Make sure your changed branch compiles and runs. Commit any changes and push them up to the GitHub repository. Then try the merge again, and this time it should work.

  5. If you had to fix merge conflicts in step 4 or make changes, start again at step 1.

3.5. Tutorial 5. Merging Part 2: Request reviews of your changes with the Pull Request Code Review System

  1. Now you need to request that your teammates review your changes using the GitHub.com Pull Request Code Review System. To do this, go to the GitHub repository. Click the dropdown labeled "Branch", and choose your branch name. Then click the "New pull request" button next to the branch name.

  2. The "Open a pull request" form is displayed. You may have to change the branch names that are shown as defaults for the branch comparison. To do this, use the dropdowns to make sure that the base is the master branch and the compare branch is your branch. Scroll down the page to see the commits that have been made to the branches and the changes to the files. Scroll back up to the "Add comments" section and type in a message to your teammates that explains the reason for the changes that you made and briefly what they were, and what files you changed. If there is an issue tracker item associated with these changes, reference it in the reason why you made the changes. Click the "Create Pull Request" button to send the message to your teammates.

  3. Your teammates should see a new pull request when they are logged into the GitHub repository. There is a tab at the top of the window labeled "Pull requests" with a number next to it. If you click on that tab, all open pull requests are visible. Click on one of them to open the window about the request. There is a title with 3 tabs just below this title, "Conversation", "Commits", and "Files changed". Everyone on the team needs to review the changes you are proposing, by clicking the "Files changed" tab and seeing what you want to merge into the master branch. Again there is a "Unified" and "Split" set of buttons to view the changes side by side or sequentially. In this case only the changed lines are shown by default, but there is a "View" button that shows the entire file. Your teammates need to review your code changes, then go back to the "Conversation" tab and enter their comments, adding them to the conversation by clicking the "Comment" button. DO NOT click any other button on the page.

  4. You need to monitor the conversation and if anyone has suggestions or issues with your proposed changes you need to fix them. You can suggest changes in the conversation to make sure you have a fix before proceeding. Only after everyone has agreed to a set of changes, can you proceed to "B" below.

    A. If everyone does NOT agree with your proposed changes, YOU need to click the "Close pull request" button. This will close the request while you work on changes. Make changes on your local branch: First merge any updates that might have occurred in the meantime on the remote master branch into your local master and then merge the local master branch back into your local branch (e.g. "<your initials>fixWarnings"). Make fixes on your local branch, and commit them often and push them to the remote copy of your branch often. Once you have completed this work start again from Tutorial 4, step 1.

    B. Once you receive a thumbs-up from everyone, meaning they agree to your proposed changes, YOU need to click the "Merge pull request" button. This will perform the merge and add your changes to the master branch. Your original pull request message will be shown. Modify this to indicate agreement or things you had to do to get agreement. Then click the "Confirm merge" button. This goes back to the Conversation tab for this merge. You can click on the "<> Code" tab at the top of the window to get to the code in the GitHub repository.

  5. Go back to Eclipse, switch to the "master" branch and use the Pull icon or Team→Pull to update your local copy of the master branch.