Project 1: Course Resources Worksheet and GitLab Setup

Due Date: Thursday, March 31^st, 2022 at 11:59pm PDT

Introduction

This project is intended for you to become familiar with the infrastructure for this course and the rest of the projects for this course. In Project 1, you will walk through the following instructions, use GitLab to access starter code, complete a worksheet, and then practice submitting your work. After these steps, you will have completed Project 1.

If you become unsure of how to proceed at any point in this project and all future projects, please post on the Ed discussion board or email the course staff for clarification.

Part I: Course Resources Worksheet (5 points)

Navigate to the Project 1 assignment on Canvas (linked here). Download the document template titled p1_Course Resources Worksheet & GitLab Setup.docx. Open the document, read the instructions on the first page, and estimate the amount of time you think it will take you to complete this project.

Then, complete the course resources part of the worksheet. This activity is intended to help you get organized for the quarter ahead by compiling resources for your courses into one location.

Submission: Save the document when you are done, and move on to Part II below. We will revisit this document in Part III of Project 1 and submit Part I together with Part III.

Part II: GitLab Setup (5 points)

Opening a Command-Line Interface

This project is written from the perspective of a command-line interface (used interchangeably with the word "shell"). If you aren't sure how to open a command-line interface on your computer, UW's eScience Institute has a tutorial on this page that will help familiarize yourself with the command-line interface. If you use this link, skip the "Download Files" and "Install Software" sections, as they are not relevant for this course. Only the "How to open a new shell" section near the bottom is relevant for us. Once you have a shell open, you can move onto the next steps.

Using Git

This project will require you to use a tool called git, a tool that manages changes to files and handles syncing them with a server (GitLab). If you're already familiar with git, you can skip to the next section.

Here is some terminology for using git: A repository is a single directory (including its subdirectories) that git can keep track of. One version is stored on the server (sometimes called the remote or origin) and you use the git program, installed on your computer, to create a local copy (clone) of that repository. The real power of git is that it tracks changes to files, where a commit is a set of those changes.

You can use git as a command-line tool (which are outlined in these instructions), or as a GUI application. Before continuing, ensure git is installed on the computer where you intend to complete projects for this class by following the instructions at this link: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git. You should be able to complete the project series on any computer operating system, whether that's Windows, MacOS, or Linux. If you are using Windows, use the “Git Bash” application you just installed to run the commands below.

Finding Your CSE 390B GitLab Repository

1. Navigate to https://gitlab.cs.washington.edu/. If you have a CSE NetID, use the green “CSE NetID” button. Otherwise, use the white “UW NetID” button.
2. In your list of Projects, you should see a repository for CSE 390B (named cse390b-22sp-students/cse390b-22sp-[CSE NetID]) created for you already. If not, please contact your instructor as soon as possible so that we can create one for you.

Adding Your SSH Key

SSH stands for "Secure Shell." SSH keys serve as an access credential to connect to a server. This will allow you to access your GitLab repository without having to authenticate (i.e., type your password) every time you connect to your GitLab repository. This allows you to speed up your workflow.

1. Check to see if your environment already has an SSH key
   1. On the command line, run cat ~/.ssh/id_rsa.pub.
   2. If you see a long string starting with ssh-rsa or ssh-dsa, skip to Step 3.
2. Generate a new SSH key
   1. Run ssh-keygen -t rsa -C "[CSE NetID]@cs.washington.edu" (include the quotes).
   2. When prompted which file to save the key in, hit enter (this saves the key in the listed default location).
   3. Press enter when prompted for passphrase (empty for no passphrase).
   4. Hit enter again to confirm no passphrase.
   5. Your SSH key is now created and stored.
3. Copy your SSH key
   1. Run cat ~/.ssh/id_rsa.pub.
   2. Copy the complete key (starting with ssh- and ending with your username and host).
4. Add your SSH key to GitLab
   1. Navigate to your SSH Keys page by clicking your avatar in the upper-right, then “Settings,” then “SSH Keys” in the left-side menu.
   2. Paste into the “Key” text box and give a “Title” to identify what machine the key is for.
   3. Click the green “Add key” button below “Title.”

Exploring the Starter Code

From the command-line, execute the following commands:

1. cd [Preferred local directory to store your repository]
For example, cd /Users/ericfan/Documents/
2. git clone [Clone with SSH URL]
   Clones your repository so a copy of it exists in your local environment—find the URL by clicking the blue “Clone” button in the upper-right of your project’s Details page.
3. cd cse390b-22sp-[CSE NetID]
   Navigates to the top-most directory of your repository, called the "root directory."

Read the README.md file located in the root of your repository to learn more about Project 1.

Changing Files

1. Open your computer's file manager (i.e., File Explorer for Windows and Finder for macOS). Then, navigate to the Project 1 directory: /cse390b-22sp-[CSE NetID]/projects/p1/.
2. Open the file about_me.txt.
3. Tell us a little about yourself in this file! You can talk about your cultural background, what commitments you have this quarter, previous computing experiences, journey into computer science, what you are excited or anxious about for this quarter, your goals for this class, etc. Feel free to write as much or as little as you would like. Just make sure to include something in the file!

Making a Commit

Now, from the command-line, execute the following commands:

1. git status
   1. Prints out the status of the repository. You should see a message informing you that the changes you made to the file have not been staged for commit yet: modified: about_me.txt
2. git add about_me.txt
   1. This command stages a new file or an updated file for the commit phase.
   2. Now, when you run git status, you should see the message: Changes to be committed: with your modified about_me.txt file: modified: about_me.txt
3. git commit -m "Update about_me.txt"
   1. Commits all staged files (files that you ran git add on) with the provided message.
   2. You should receive a message informing you that one file has been changed with the number of characters that have been inserted and deleted.
   3. Commit messages are somewhat arbitary, but they should be informative and reflect what the changes made since the last commit look like. This webpage includes a few general guidelines for writing commit messages.
4. git push
   1. Publishes the changes to the repository on the GitLab server, which should now be viewable (you may need to refresh the page) in the web interface.
   2. You may need to run git push -u origin master on the first commit (only).

Make commits often! They allow you to make checkpoints in your projects that you can always revisit.

Submitting Part II

Whenever you submit a project in this course, you’ll “tag” the last commit so the course staff knows what version of your code you would like us to grade. The following instructions are for Project 1 but can be adapted for every project:

1. Make sure you have committed and pushed your latest changes for Project 1.
2. git tag project-1
   1. Tags the most recent commit with the name "project-1".
3. git push --tags
   1. Similar to before, this version of the git push command publishes tags to the GitLab server (viewable in the web interface).
   2. Don't forget this step! Otherwise, the tag will only be present in your local environment. The course staff won't be able to tell which commit they should grade without a tag.

Part III: Project 1 Reflection (5 points)

Each project will include a reflection component on the last page of the project's template document. In the document titled p1_Course Resources Worksheet & GitLab Setup.docx, record an estimation of how long you think the project will take (this step should be completed after reading through the instructions of each project), how long the project actually took, and a short, written reflection on the project went for you.

Submission: With Parts I & III completed, save the document as a PDF and submit the document on Gradescope under the assignment named Project 1: Course Resources Worksheet & GitLab Setup.

Conclusion

Project 1 will be completed once you have submitted this document to Gradescope and pushed your GitLab changes with the project-1 tag.

Ancillary: Set up a Text Editor for HDL

The course tools we distribute deal only with running, testing, and debugging your code. They are not good for editing code. To complete the coding portions of the projects in this course, you may use any text editor of your choosing. However, please note that we will be using programming languages that were invented for this course, so we don't recommend big heavy IDEs (Integrated Development Environments) like IntelliJ, Eclipse, Visual Studio, or JGrasp. They won't understand the languages well, and you won't need them to run code anyway because the course tools handle that.

Instead, we recommend you use a lightweight text editor like VSCode, Atom, or Sublime Text. Fortunately, there are third-party extensions that can provide syntax highlighting to make your experience more pleasant. Follow the directions below if you'd like to get set up with one of these editors! Note that the extensions listed below are not created by the course staff, and may not have been thoroughly vetted.

You are also welcome to use a command-line editor like Vim or Emacs if you prefer, although syntax highlighting support may be harder to find.

VSCode

Note: Visual Studio Code (this tool, lightweight editor) is different than Visual Studio (heavy IDE).

Install VSCode

Download the latest version at https://code.visualstudio.com/Download.

Configure Syntax Highlighting for .hdl Files

1. Select the "Extensions" panel on the left menu bar (look for an icon near the bottom made up of four squares)
2. Search for roblourens.vscode-nand2tetris-hdl
3. Click "Install" on the single result that comes up

Atom

Install Atom

Download the latest version at https://atom.io/.

Configure Syntax Highlighting for .hdl Files

1. Navigate to the "Settings" menu, then on the bottom left select "Install"
2. Search for language-nand2tetrisHDL
3. Click "Install" on the extension with exactly the same name

Sublime Text

Install Sublime Text

Download the latest version at https://www.sublimetext.com/3. Technically, the full editor costs money, but you may download and use a full-featured free trial for an unlimited period of time.

Configure Syntax Highlighting for .hdl Files

1. Navigate to this public GitHub repository: https://github.com/t17dr/sublime-nand2tetris
2. Follow the directions there to enable syntax highlighting support
3. Restart Sublime Text

Acknowledgements and References

• These resource are gratefully adapted from Justin Hsia’s CSE 333 20wi GitLab Setup handout.
• SSH Key Generation: https://gitlab.cs.washington.edu/help/ssh/README.md
• Basic Git Tutorial: http://courses.cs.washington.edu/courses/cse333/20wi/git/