CS 257: Software Design

EncodingHelper

What you should know after this assignment:

• What is a version control system?
• How to perform a few basic operations with the version control system git.
• How to create and use a git repository with the online service Bitbucket.
• What is an Integrated Development Environment (IDE)?
• How to create a Java project with the IDE IntelliJ.
• How to manage your IntelliJ project's files with git.

Your practical goals for this assignment are:

• Set up an account on Bitbucket.
• Install IntelliJ Community Edition on your computer.
• Install git on your computer.
• Create a Java command-line project called EncodingHelper in IntelliJ. For now, this project should be a simple "hello, world" program. You'll turn it into a useful program for a later assignment.
• Create a git repository on BitBucket containing your EncodingHelper project.
• Share the git repository with me and the course grader.

You'll have lots of questions. You'll be able to answer some of them through experimentation and searching the Internet, but don't hesitate to ask other people (including me) for help.

So, here we go...

1. Set up an account on Bitbucket

Go to bitbucket.org and create an account for yourself based on your Carleton email address. (It's important to use an address ending in ".edu" so you will get a free, unlimited academic account.)

2. Create a Bitbucket git repository to hold your project

Login to your Bitbucket account, go to Repositories→Create repository and create a git (not mercurial!!) repository named EncodingHelper. Keep it private.

A repository is essentially a folder in which you can store whatever files and subfolders you want. What makes a repository more than a folder, however, is that the version control system (git, in this case) keeps track of all the changes that get made to the files in the repository. This saving of history makes it possible for you to retrieve old work, track down the time when a bug was introduced (and who introduced it), collaborate on a project with a team of programmers, easily back up your work, etc., etc. Version control systems are a bit of a hassle to learn for the first time, but they're indispensable programming tools and unquestionably worth the effort..

3. Install git on your computer

You can get git here. It's possible that you already have git on your computer, but you would probably know it if you do.

Once you install git, you'll be able to use it from the command line. For many people, that's sufficient. However, there are some benefits to using a GUI git client, too. Since we'll be using Bitbucket to host our git repositories, I recommend that you take Bitbucket's advice and install Atlassian SourceTree, which integrates very well with BitBucket.

For the rest of this document, whenever there's need to show a git operation, I will show you the git command-line version of that operation. If you're using SourceTree or any other git client, you'll need to figure out the equivalent operations in your client.

4. Get a local copy of your EncodingHelper repository

Right now, your EncodingHelper repository is stored only on the Bitbucket server. To add files to it, you'll need to "clone" a copy of the repository onto your own computer. You will then add files to your local copy of the repository and push your changes back up to Bitbucket.

Bitbucket gives you some setup instructions right after you create a new repository, and they work just fine, but there's a simpler way to make your clone:

(Note that bitbucket instructs you to use git@bitbucket.org:YOUR_USER_NAME/encodinghelper.git instead of the https version above. However, this latter version only works if you have installed an SSH key in your Bitbucket account. Doing so can make some Bitbucket operations simpler, but it's not required.)

You should now have a folder called EncodingHelper, containing only a subfolder called ".git". (Curious? Go ahead and poke around in .git to see what's there. It gets more interesting, of course, after you add some files.)

5. Install IntelliJ Community Edition on your computer

Get it at IntelliJ Community Edition.

6. Create an IntelliJ project

Here are the steps. (There's also good help at the JetBrains IntelliJ Help page.)

• Create New Project
• Project SDK: if the dropdown shows "None", click on New and find the JDK installed on your system. (On my Mac, IntelliJ automatically selected the right location, so I just hit OK. If that doesn't happen for you, you may have to dig a bit to find the JDK that's installed on your computer. If you've never installed the Java compiler and dev tools on your computer before, you may have to do that first. Check the JetBrains help.)
• Click "Next"
• Check "Create project from template" and select "Command Line App"
• Name the project "EncodingHelper" and put it in a temporary location. (You can't put it in the folder where your git repository lives, since you already have a folder named EncodingHelper there.)
• Change the "Base package" to something suitable--I used edu.carleton.jeffondich

7. Add your IntelliJ files to your EncodingHelper repository

• Quit IntelliJ
• Take a look at the contents of the project you just created. You should see subfolders called ".idea" and "src", plus a file called EncodingHelper.iml.
• Move .idea, src, and EncodingHelper.iml into your EncodingHelper git repository.
• Now add those items to the repository:
  cd EncodingHelper git add .idea src EncodingHelper.iml
• Commit your changes. That is, you tell git to make your changes a permanent part of the history of your repository. When you perform the commit operation:
  git commit -a
  you will be required to type a commit message. In this case, your message should be something like "Added the initial IntelliJ project files to the repository."
• Push your changes from your copy of the repository up to the Bitbucket server's copy:
  git push

(Curious again? Take a look at what your repository now looks like on Bitbucket. Also, you can take a look at the contents of .git to see whether anything changed.)

8. Add a little bit of code, commit, and push again

• Launch IntelliJ
• Open the project found in your EncodingHelper git repository (File→Open, then select the EncodingHelper folder, then click Choose).

• In the left-side panel, find "Main" under your src directory. Double-click on Main to see the contents of Main.java.
• Add something like System.out.println("hello, world!"); to your main method.
• Find the bug icon in the toolbar at the top of IntelliJ, and click on it.
• Your program should compile and run. Where does the output appear?
• Once you're happy with your hello world message or whatever Java code you have added to Main, save the file, then do "git commit -a" and "git push" again.
• If you feel like entertaining the grader, go nuts--this is just a Java program, and you can do whatever you want with it. But make sure that your project loads, builds, and runs by the time the assignment is due.
• Finally, "tag" your code at the point where you want it graded. Since you may start work on Phase 2 of the EncodingHelper project before the grader finishes grading Phase 1, he'll need to be able to get a copy of your code as it was when you were done with Phase 1. To do that:
  git tag -a phase1_final -m "tagged for assignment due 9/17/14" git push origin phase1_final
  Please use that exact tag name ("phase1_final") so it's easy for the grader to access everybody's Phase 1 code.
• Check Bitbucket to make sure the tag has appeared in your repository.

9. Share your repository for grading

In your Bitbucket account, go to your EncodingHelper repository. Use the "Send invitation" button to share your repository with me (jeffondich) and the grader, Eric Ewing (ewinge). Now we'll be able to clone your repository to take a look at your work.