CompSci 308 : Spring 2021

GITing Started

Knowing how to use a source control system will be an invaluable tool for you going forward, perhaps personally or even potentially for changes in laws, but especially in a team setting. At its heart, version control is just a way to manage the many changes that occur to your files over time, but that simple idea changes everything! It allows you to revisit previous versions of your code, work with different versions at the same time, and work in teams and track who made which changes. At its best, version control is like a journal that you use to track major, and minor, events in your project. At its most practical, it is like a backup system that prevents you from losing significant work if something happens to your machine. At its worst, it is simply a submit system where you only track your work when told to.

Version control systems have been around for almost fifty years and GIT is currently the cool tool to use (partly because it was created by Linus Torvalds, the creator of Linux, and partly because of the popularity of GitHub, the largest public repository of code). Using source control well is not difficult, but it does take some practice and a little bit of command-line savvy (we do not suggest using visual GIT tools, even the one built into IntelliJ, until you are confident in your version control skills).

When running these programs, unless otherwise noted, we suggest following the default options.

Install Java and IntelliJ

You will be using features from the latest version of Java in this course and I recommend using IntelliJ as your development environment since it has a wide variety of features to help you improve your program's design.

Download and install OpenJDK version 15 (make sure to select the FULL JDK package before starting the download)
Download and install IntelliJ Ultimate version (free for students if you apply by providing your school email address)

Install GIT

Download and install GIT
on Mac or Linux, you can use the built in Terminal program to interact with GIT
on Windows, there are some settings you should set to work well with other platforms and it comes with a program called Git Shell that you can use to enter the commands below (you can also install a full version of Ubuntu Linux !)
Within Terminal/Shell, configure GIT for your computer (note, these commands need to be done once for each computer you program on)
```
    git config --global user.name "YOUR NAME"
    git config --global user.email "NETID@duke.edu"
```

Login to Gitlab

Within a Browser, go to the website: https://coursework.cs.duke.edu/
Press the Shibboleth button to log in using your Duke NetID
After you have successfully been logged in through Duke's standard log in page, there may be a warning at the top of the page saying you need to set up an SSH key.
If so, go to User Settings → SSH Keys to set it up because you have never used the CompSci coursework Gitlab site.
Clicking on that link should take you to a page prompting you to paste the public part of SSH key into the given text area
Next, we will get that public key

Generate an SSH Key

Within a Browser, go to the website: https://coursework.cs.duke.edu/help/ssh/README
If you have not already generated an SSH key for another class (such as CompSci 201):
- Within Terminal/Shell, do Step 1 in the second section "Generating a new SSH key pair" and accept the defaults (steps 2 and 3)
```
    ssh-keygen -t rsa -C "NETID@duke.edu" -b 4096
```
- Copy public part of the key using the command given in step 4 corresponding to your OS
If you have not already connected your current computer to the CompSci coursework Gitlab site:

Within Terminal/Shell, copy the public key using the command given in Step 4 in the second section "Generating a new SSH key pair"
Within a Browser, paste the copied public key into the Gitlab text area (User Settings → SSH Keys → Key Text Area)
giving it the same title: id_rsa, and press Add key

Getting Your Own Copy of a Gitlab Project's Starter Code

Within a Browser, visit the project for this lab, https://coursework.cs.duke.edu/CompSci308_2021Spring/lab_bounce
Press Fork button in the upper right corner of the page to create a version of the project in your own account with the same name (e.g., NETID/lab_bounce)
Note, we are using fork to create your own copy repository of this project so you can experiment with a variety of GIT commands but, in general, a repository will be provided for you for assignment projects (so using fork is not generally correct)
On the project page that appears, copy the blue Clone button and copy the SSH URL (e.g., git@coursework.cs.duke.edu:NETID/lab_bounce.git)

Cloning Your Copy of the Project onto Your Local Machine

Within Terminal, change to your workspace folder
```
    cd WORKSPACE/FOLDER
```
Download a local version of the project that is linked to your Gitlab repository
```
    git clone git@coursework.cs.duke.edu:NETID/lab_bounce.git
```
That command should create a folder named lab_bounce within your workspace folder that contains configuration information for GIT (e.g., a folder named .git — note that it starts with a period)
```
    ls -a lab_bounce
```

Importing Your Local Copy into IntelliJ

Within IntelliJ, open the newly cloned folder using File → Open (or the Open button if the File menu is not available)
Select the folder you just created: lab_bounce, and press Open
Once the project window appears, you will need to a few more steps to get it to run:
1. Click on the Project label in the leftmost gutter to expand the contents of your project folder
2. Click to expand the folders src → bounce to find the Java class ExampleBounce
3. Right click on this class to run it by selecting Run ExampleBounce.main()
Run the program to verify that your Java installation is working.
If there are compilation errors or it does not run, then you may not have installed the latest versions of Java or IntelliJ or the project is not correctly configured.

Push Changes to your Project back up to Gitlab

Within Terminal, your lab_bounce folder should now have the configuration folders for both GIT (e.g., .git) and IntelliJ (e.g., .idea)
```
    ls -a lab_bounce
```
Within IntelliJ, open the file README.md by double clicking on it
Add your name and save the file
When you do this, you should see the file's name in the Project View's list of files change color to indicate GIT knows it has been changed
Within Terminal, you can verify that GIT also knows that it has been changed by typing
```
    git status
```
Add your changed files to those staged for your next commit
```
    git add README.md
```
Then note that all the added files should be grouped together into a single commit to the repository, with a message describing the changes contained in this commit
```
    git commit -m "Included my name in the README"
```
Push all your commits to the remote repository, e.g., Gitlab, so that others (UTAs, teammates, etc.) can see your changes
```
    git push -u origin master
```
Within a browser, refresh the Gitlab page for your repository to see your changed README file

Make Substantive Changes

Complete the following tasks to practice the basic GIT workflow commands (add, commit, and push), get used to OpenJFX, and begin to think about how to organize code within a project. For each task, you may make any changes to the code you think are warranted (functional, organizational, or creating new classes). After you think you have completed each task, make a GIT commit with an appropriate comment (i.e., there should be at least four commits in your project history). After every two commits, push your changes up to Gitlab so your online lab_bounce repository reflects the work you have done in lab today.

Make the bouncer "bounce" off of one "wall" (pick any edge of the application window) by reversing its direction
Make the bouncer bounce off of all the walls, including the corners
Make two bouncers that start at different places, with different sizes, move in different directions, but with both bouncing off of all the walls
Make any number of bouncers, with different random initial properties, that bounce around

Resources

Submission

At the end of lab, use Gitlab's Merge Request back to the original organization repository's master branch to submit your updated code and commits. Make sure the title of your Merge Request is of the form "lab_bounce - your NetID". Just in case, also include your name and NetID at the top of the README.md file. This is how all lab submissions will be done for this course — only what is in your Gitlab repository will be considered part of your work.