CompSci 307 : Fall 2021

Lab: GITing Started and Debugging

This exercise is intended to ensure you have correctly installed the course software, can use it to develop Java programs with OpenJFX, and can submit your code to the course's Gitlab group. It will not be explicitly graded but, instead, ensure that you can participate in the course.

Download and Install Development Software

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 Java 16 (make sure to select the FULL JDK, DMG or MSI package, before starting the download)
Download and install IntelliJ Ultimate version (free for students if you apply by providing your school email address)
Download and install GIT (includes a Unix style command-line Shell for Windows)

Here is a video of the process (since there are some specific notes I wanted to show in choosing what to download)

And here is another video showing the steps below with some explanations along the way.

Configure GIT

Note, we recommend using the command-line when interacting with GIT, at least for the first half of the course, to make sure you have a firm understanding of the foundational principles.

Accessing the command-line within IntelliJ you can use the Terminal tab within IntelliJ (View → Tool Windows → Terminal)
outside of IntelliJ, you can access the Terminal
- on Mac or Linux, you can use the built in Terminal program
- on Windows, GIT comes with a program called Git Shell but there are some settings you should set to work well with other platforms
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 not, go to Preferences → SSH Keys to set it up if you have never used this 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 RSA 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:
- Within Terminal/Shell, run the command below and accept the default options (details are in the RSA SSH Keys section within "Generating a new SSH key pair")
```
    ssh-keygen -t rsa -C "NETID@duke.edu" -b 4096
```
If you have not already connected your current computer to our Gitlab site (coursework):

Within Terminal/Shell, copy the public key using the command corresponding to your OS given in the section Adding an SSH key to your GitLab account
Within a Browser, paste the copied public key into the Gitlab text area (Preferences → 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 exercise, CompSci307_2021Fall/example_animation
Press Fork (the button is in the right upper corner) to create a version of the project in your own account with the same name (e.g., NetID/example_animation)
Note, you will use fork only to create your own repository of lab_ or example_ repositories.
A repository will be provided for you for project_ or portfolio_ repositories (so using fork is not the general practice)
On the new project page that appears, copy the SSH URL (e.g., git@coursework.cs.duke.edu:NetID/example_animation.git)
Note, it is will appear as an option when you press the Clone button on the right side of the page

Cloning Your Copy of the Project onto Your Local Machine

Within Terminal, change to your workspace folder (WORKSPACE_FOLDER can be any directory you want on your computer as long as there are no spaces anywhere in the path)
```
    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/example_animation.git
```
That command should create a folder named example_animation 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 example_animation
```

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: example_animation, 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 → animation to find the Java class ExampleAnimation
3. Right click on this class to run it by selecting Run ExampleAnimation.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.

Completing this step verifies your Java and IntelliJ installations are correct and working together.

Push Changes to your Project back up to Gitlab

Within Terminal, your example_animation folder should now have the configuration folders for both GIT (e.g., .git) and IntelliJ (e.g., .idea)
```
    ls -a example_animation
```
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

Completing this step verifies you can correctly access the course Gitlab group to submit your work for the semester.

Resources

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 over forty 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).