CS 257: Software Design

WordGameAssistant, Phase 1 of 3

Work with one or two partners on this. Do all the installations and account signups individually on your own computers, but share a single git repository for your project. Put both of your names in the comments at the top of each source file.

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 WordGameAssistant 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 WordGameAssistant 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 WordGameAssistant. 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 (e.g. it's available by default on most Macs).

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.

3a. [Optional but recommended] Windows only: Install cygwin

Installing cygwin gives Windows users access to a wide range of Unix/POSIX/GNU tools. These are the tools that you'll see me using all the time in a Mac terminal, because MacOS X is based on a Unix core. Similarly, Linux is a variant of Unix, and thus has all the usual Unix tools. Windows has its own command-line interface and command collection that's plenty powerful, so you can definitely work to become an expert on that interface and not worry about having Unix on Windows. That said, the documentation and open source software available for Unix-like systems is a huge benefit to day-to-day programmers, and I personally never work long with a Windows machine without first installing cygwin. Since I won't be demonstrating Windows-specific tools at all this term, you might find it handy to have the tools that I do demonstrate.

The cygwin installer is pretty much self-explanatory, and it leaves a shortcut on your desktop. But there's a moment during installation when you have the option to add non-default tools. The available choices are bewilderingly numerous, but I recommend that you make sure you're installing at least: git, vim, emacs, OpenSSH, python.

4. Get a local copy of your WordGameAssistant repository

Right now, your WordGameAssistant 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/wordgameassistant.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 WordGameAssistant, 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 "WordGameAssistant" 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 WordGameAssistant there.)
• Change the "Base package" to something suitable--I used edu.carleton.jeffondich

7. Add your IntelliJ files to your WordGameAssistant repository

• Quit IntelliJ so it will close all your project files and delete any temporary files it may use at runtime.
• Take a look at the contents of the project you just created. You should see subfolders called ".idea" and "src", plus a file called WordGameAssistant.iml.
• Move .idea, src, and WordGameAssistant.iml into your WordGameAssistant git repository.
• Go to your WordGameAssistant repository and take a look at what git sees.
  cd path/to/WordGameAssistant git status
  I do "git status" very often to keep track of what changes I have made to my repository.
• Now add the "untracked" items to the repository:
  git add .idea src WordGameAssistant.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
  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." To type this message, you'll be thrown into whatever text editor git uses by default. At the command line on Unix systems (including MacOS X), the default editor is usually vim, but the editor choice is configurable. (Go ahead and research that on your own, if you wish.)
• 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 WordGameAssistant git repository (File→Open, then select the WordGameAssistant 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 status git diff git add [whatever the path to Main.java is] git status git commit git push
  Note that those two "git status" invocations are there because I want you to see the status messages before and after the "git add". This sort of exploration is part of coming to understand how git works, but it's also something I often do myself to make sure I don't make big changes too fast. I also use "git diff" to make sure I look one last time at every line of code I have changed before committing. Yes, I can always roll back to the previous commit, but I like to avoid unnecessarily putting myself in that position. Going a little bit slowly like this is just a good habit.
• 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 WordGameAssistant 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 -m "tagged for assignment due 9/17/14" git push origin phase1
  Please use that exact tag name ("phase1") 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 WordGameAssistant repository. Use the "Send invitation" button to share your repository with me (jeffondich) and the grader, Chet Aldrich (aldrichc). Now we'll be able to clone your repository to take a look at your work.