Lab 1: Unix, Workflow, and Coinstrip

In this lab, we will explore tools, techniques, and workflows used by many programmers. We will adopt some of these best practices and use them for managing our written and lab assignments, collaborating, and exchanging feedback.

The skills developed in this lab will help us on multiple fronts. The tools that we explore (Terminal.app, the emacs text editor) and the workflow we use (checkpointing our progress using the git version control system) will help us to work efficiently, safely, and flexibly throughout the semester.

We will also write a program to play the Silver Dollar Game found at the end of Bailey Chapter 3 (page 67). In addition to gaining experience writing, compiling, and running programs from scratch, this lab will help us to think about how we can efficiently represent data and break our logic into reusable methods. Careful planning will help tremendously, so take the time to write a well-thought-out design document before arriving to lab.

PRE-LAB Step 0: Version Control Systems and GitHub

Please complete PRE-LAB Step 0 by Monday at 4pm. This part is worth 2 basis points of your Lab 1 grade.

Review what a version control system is and why you might want to use one. We will talk about these more in the lecture and the lab.
Sign up for a GitHub account by following the GitHub Getting Started guide on the course webpage. Please choose your username thoughtfully–students often use a GitHub account for years and like to show their work to prospective employers!
Complete the Hello World guide. We will be using the features discussed throughout the semester.
After you’ve registered, please fill out this Google Form, and be sure to include your GitHub username. This form is how we know that you completed PRE-LAB Step 0. We will add you to the Williams CS GitHub organization prior to your scheduled lab.

PRE-LAB Step 1: Testing Your CS Mac Lab Account

Login to a MacOS machine in TCL 216 or TCL 217. You must use your CS-department username and password. Please see Mary Bailey in TCL 312 if you do not have a CS-department Mac account or if you have forgotten your username/password.

Mary Bailey is available at the following times:

Day	Time
Friday, Feb 1	10–11:30am
Mon, Feb 4	10–11:30am, 3–4:30pm
Tues, Feb 5	10:30–11:30am, 3–4:30pm
Wed, Feb 6	10–11:30am

If you cannot make it to any of the above times, you can email Mary (mary@cs.williams…) for an alternative time.

PRE-LAB Step 2: Design Documents

Read through this lab handout and sketch out a design for your Silver Dollar Game program. You should use the sample Dice Design Document as a guide. Each week your design document will account for a small portion of your lab grade, so please bring it to lab, be prepared to discuss it with a partner, and be prepared to submit it. For the first week, it is OK if the design is rough: we are not going to deduct points for correctness. The purpose is to ensure that you think about the lab in advance.

Step 1: The Mac Lab Environment

Complete the following Unix tutorial. That guide will teach you how to log in and out of the machines, access the command line shell, use basic Unix commands, and compile and run Java programs. Depending on your prior background, you may already be familiar with this environment. If that is the case, please refresh your memory and review the following commands:

  ls         cd         cp         mv         rm         mkdir      pwd
  man        history    cat        more       grep       head       tail    	

To be successful, you should know how to use each command on the command line and use them to explore, create, modify, and rename files. Even though there is nothing to turn in for this step, learning core Unix commands is going to help you with everything you do this semester and beyond.

Step 2: Cloning

By the start of lab, you should have a private repository in your GitHub account, named cs136_lab1_USERNAME, where USERNAME is replaced with your GitHub ID. Clone the repository to your local disk using the following steps:

In your web browser, click the green “clone or download” button on the right side of the repository page, above the list of repository contents. You can clone via HTTPS or SSH. We’ll use HTTPS, so first click on the “Clone with HTTPS” link and then click on the little clipboard with an arrow icon to copy the URL to the local clipboard.
Open up the Terminal.app application and navigate to your home directory by typing
```
 $ cd ~
```
Make a new directory called cs136 using
```
 $ mkdir cs136
```
Change directory into the cs136 directory using
```
 $ cd cs136
```
Now clone your private repository cs136_lab1_USERNAME by typing git clone and then pasting the copied repository URL on the command line (⌘-v). It should look like this:
```
 $ git clone https://github.com/williams-cs/cs136_lab1_USERNAME.git
```
You will be prompted for your username, and then for your password. Enter them in when prompted.
Change directory into the new repository directory using
```
 $ cd cs136lab1-USERNAME
```

Step 3: emacs and git

There are many good text editors. Traditionally, we use the emacs text editor in Williams CS courses. emacs is a capable editor, and gaining proficiency is worth the time investment and learning curve because it gives you great flexibility in limited environments.

If you need a refresher on emacs, see Duane’s Incredibly Brief Intro to Unix and Emacs.

In the second half of the semester, we will switch to IntelliJ IDEA, which is a more modern integrated development environment (IDE). IDEs provide programmers with a sophisticated ecosystem of tools that make debugging and testing substantially easier than with a text editor alone. If you are feeling adventurous, give it a try.

In your cs136_lab1-USERNAME folder, create a README.md file using emacs.
```
 $ emacs README.md
```
You may be surprised by the way README.md looks in emacs compared to how it looks on GitHub. This is because GitHub understands the “Markdown” format. You may want to use the GitHub Markdown syntax to format your file so that it displays nicely on GitHub.
The README.md for a repository is shown when you view that repository on github.com. Make a small change (perhaps write the word “test” at the bottom of the page). Save the file (C-x C-s, which on a Mac is the same as Ctrl-x Ctrl-s).
To suspend emacs and temporarily return to the shell, type C-z. You should see the following:
```
 [1]+  Stopped                 emacs README.md
```
and you will be back at the shell prompt again. emacs is now running in the background.

Type git status. You should see something like the following:

 $ git status
 On branch master
 Your branch is up to date with 'origin/master'.
    
 Changes not staged for commit:
   (use "git add <file>..." to update what will be committed)
   (use "git checkout -- <file>..." to discard changes in working directory)
    
 	modified:   README.md
    
 no changes added to commit (use "git add" and/or "git commit -a")

This message tells you that README.md has been changed since your last git commit. The key part of the message is the phrase Changes not staged for commit.

To add your changes to your changeset, type
```
$ git add README.md
```
When you run git status a second time, you should see that git is now tracking your changed file.
```
 $ git status
 On branch master
 Your branch is up to date with 'origin/master'.
    
 Changes to be committed:
   (use "git reset HEAD <file>..." to unstage)
    
 	modified:   README.md
```
You can git add as many files as you want to a changeset. Many people often type the shorthand git add ., which adds all the files in the local directory to the changeset.
We are now going to save the state of all of the files in our changeset. This is a kind of checkpoint called a commit. You can commit your files by using the git commit command. For instance, I might type:
```
 $ git commit -m "Updated README."
```
where the -m "Updated README." is a commit message of your choosing.

git will respond by echoing your message and it will tell you the commit ID of your new checkpoint.
```
 [master 33c8c86] Updated README.
  1 file changed, 3 insertions(+), 1 deletion(-)
```
In the above example, the commit ID is 33c8c86.

If we type git status again, we should see that no changes remain.

 $ git status
 On branch master
 Your branch is ahead of 'origin/master' by 1 commit.
   (use "git push" to publish your local commits)
    
 nothing to commit, working tree clean

The key part to pay attention to is nothing to commit.

Nonetheless, note that our status message also says Your branch is ahead of 'origin/master' by 1 commit. This means that although we committed our changes, they are only committed to the local copy of our repository. We have not yet uploaded the changes to the remote copy of the repository. In this class, the remote repository will always be GitHub. The remote repository is called origin/master in git terminology. To upload changes to GitHub, we use the git push command.
```
 $ git push
 Counting objects: 3, done.
 Delta compression using up to 4 threads.
 Compressing objects: 100% (2/2), done.
 Writing objects: 100% (3/3), 321 bytes | 321.00 KiB/s, done.
 Total 3 (delta 0), reused 0 (delta 0)
 To github.com:williams-cs/cs136_lab1_dbarowy.git
    2301b3f..33c8c86  master -> master
```
git prints a lot of information, but the most important part is where it says 2301b3f..33c8c86 master -> master, which indicates that the latest commit ID on origin/master went from being 2301b3f (the previous commit) to 33c8c86 (our latest commit). In other words, our upload was successful.
If we run git status one last time, you should see that there are no more changes, and that our local copy (“Your branch”) and Github (“origin/master”) are now synchronized.
```
 $ git status
 On branch master
 Your branch is up to date with 'origin/master'.
    
 nothing to commit, working tree clean
```
Finally, we want to return to emacs. Type fg in the shell. fg returns a program running in the background to the foreground. Remember that we put emacs into the background when we typed Ctrl-z? Sometimes people forget that they’ve put emacs in the background and they start it up again, and weird problems ensue. If you use Ctrl-z remember to use fg to get your editor back.

Step 4: Hello Odd World: Writing Your First Program.

In this step, we will write, compile, and run a Java program under Unix that prints the first ten odd numbers.

We will create a new file called Odd.java. You will turn in your source code for Odd.java by committing it to your local git repository and pushing that commit to your private repository on GitHub. You should complete this step by the end of lab on Wednesday.

The instructors and TAs are around to give as much assistance as we can on this step, so do not hesitate to ask questions! We want you to successfully complete this step so that you can move on to the main lab assignment. This is the simplest program we will write all semester, but it is often the hardest to complete. Ask questions early and often!

Inside your project folder, create a new file using emacs named Odd.java. That file should contain a class called Odd, and that class should include a method called main.
Once you have written your program, compile it using
```
 $ javac Odd.java
```
After successfully compiling your program, you should see a new file called Odd.class when you type
```
 $ ls
```
To test your code, type
```
 $ java Odd
```

The output should look something like:

When you have finished writing Odd.java and are happy with the output, please commit Odd.java (with a meaningful commit message) and push it to your private repository. Confirm that your changes are visible online by visiting your GitHub repository in your web browser.

Step 5: Main Lab Program (Coinstrip.java)

This week, we will write the Silver Dollar Game at the end of Bailey Chapter 3 (page 67). As you think about the design of your game, you should first decide on a representation of the coin strip. Make sure your representation supports all of the operations necessary such as:

generating different game boards
testing for a legal move
printing the board
testing for a win
moving pieces easily
…

When we say “representation,” what we mean is: what data structures will you use? For instance, you might use an array.

Once you have chosen a representation, write down the set of operations supported by your data structure. Since we’re using Java, your representation should be hidden inside a class called CoinStrip. Operations are made possible by providing public methods that implement those operations. Therefore, you should specify the public methods of your CoinStrip class. Think about what parameters they take, what values they return, and what the methods do. In lab, we will briefly discuss this initial design with a partner. Bring a printed copy of your design to lab for discussion. We will check design documents at the beginning of lab.

A good exercise to do when designing a representation is to consider alternative designs. For example, do you want a data structure that stores the spaces on the game board? Or would it be better to use a data structure that stores the coins themselves? Often it helps to think about the tradeoffs: which operations become easier to implement if you choose one representation over another? Expert computer scientists almost always do this step out on paper before they start coding, which is why we want you to work on a design document before you start.

If you’re feeling frisky, you may read ahead to the book’s section on Vectors, but the lab can be implemented just as well with arrays.

The main method of your CoinStrip class should create a CoinStrip object and then prompt each of two players to make their moves. A move will be of the form:

<cn> <ns>

where <cn> specifies the coin to be moved and <ns> specifies the number of spaces that coin should be moved.

The program should prompt the user for another input if the move is illegal.

To read input from a terminal window, you should use the Scanner class, as we have seen in lecture. Consult the scanner handout, Oracle Scanner documentation or sample code from class for details.

Step 6: Thought Questions

Consider the following questions as you complete the lab:

How might one pick game sizes so that, say, one has a 50 percent chance of a game with three coins, a 25 percent chance of a game with four coins, a 12 1/2 percent chance of a game with five coins, and so on? Would your technique bias your choice of underlying data structure?
How might one generate games that are not immediate wins? Suppose you wanted to be guaranteed a game with the possibility of n moves.
Suppose the computer could occasionally provide good hints. What opportunities appear easy to recognize?
How might you write a method, computerPlay, where the computer plays to win?
A similar game, called Welter’s Game (after C. P. Welter, who analyzed the game), allows the coins to pass each other. Would this modification of the rules change your implementation significantly?

Hint: When flipped, the Belgian Euro is heads 149 times out of 250.

Lab Deliverables

When you are finished with your CoinStrip program, answer the thought questions at the end of the lab, and put your answers in a separate file called PROBLEMS.md. Commit and push PROBLEMS.md along with your other lab files as part of your repository. Your repository should have the files:

cs136lab1-USERNAME/
           Odd.java
           CoinStrip.java
           README.md
           PROBLEMS.md
		   MISTAKES.md

Submitting Your Lab

As you complete various milestones, you should commit your changes and push them. Commit early and often. When the deadline arrives, we will retrieve the latest version of your code. If you are confident that you are done, please include “Lab 1 Submission” as the commit message for your final commit. If you later decide that you have more edits to make, it is OK. We will look at the latest commit before the deadline.

Be sure to push your changes to GitHub
Verify your changes on Github. Navigate in your web browser to your private repository on GitHub. It should be available at https://github.com/williams-cs/cs136lab01_coinstrip-USERNAME You should see all changes reflected in the various files that you submit. If not, go back and make sure you committed and pushed.

We will know that the files are yours because they are in your git repository. Do not include identifying information in the code that you submit. Our goal is to grade the programs anonymously to avoid any bias. However, in your README.md file, please cite any sources of inspiration or collaboration (e.g., conversations with classmates). We take the honor code very seriously, and so should you. Please include the statement “I am the sole author of the work in this repository.” in the comments at the top of your Java files.

Bonus: Mistakes

Did you find any mistakes in this writeup? If so, add a file called MISTAKES.md to your GitHub repository and describe the mistakes using bullets. For example, you might write

* Where it says "bypass the auxiliary sensor" you should have written "bypass the primary sensor".
* You spelled "college" wrong ("collej").
* A quadrilateral has four edges, not "too many to count" as you state.

You will receive 1 bonus point on this assignment for each mistake we are able to validate.