Chapter 2 Setting up for this course

Learning Objectives: Create a repository on GitHub from our template; Clone the repository onto your local computer; Create a branch on your repository for the next assignment

2.1 Phase 1: Creating Your Repository from Template

You will need to use a template repository on GitHub that we made for this course to have all the necessary pieces.

2.1.1 Step 1: Access the Course Template

Navigate to the course sandbox template repository
Look for the
Use this template

green button at the top of the repository page

Important: Do NOT fork the repository - you must use the template option

2.1.2 Step 2: Configure Your New Repository

Click
Use this template

and select the “Create a new repository” option (if needed).
Fill out the repository creation form:
     Include all branches: Leave unchecked (we only need the main branch)
     Repository name: Choose a meaningful name (e.g., your-username-capstone-sandbox)
     Description: Add a brief description of your capstone project
     Visibility: Set to Public (required for the automated evaluation system to work)

2.1.3 Step 3: Create Your Repository

Click
Create repository


Wait for GitHub to finish creating your repository and verify completion
     • Note: You’ll be redirected to your new repository page
     Verify: The repository should show your username as the owner and contain all the template files

2.2 Phase 2: Local Setup and Cloning

For this course you may use whatever git client (GitHub Desktop, GitKraken, etc) you are most comfortable with, or no git client at all. If you need any recap on how to file pull requests remember you can return to the other courses in this series for reference. Particularly the Advanced Reproducibility course

2.2.1 Step 4: Clone Your Repository

Option A: Using GitHub Desktop

Open GitHub Desktop
Click “Clone a repository from the Internet”
Select your repository from the list or paste the URL you copied
Choose a local path where you want to store the repository
Click “Clone”

Option B: Using a command-line interface

Alternatively, you can use a command-line interface (e.g., Command Prompt, PowerShell, the Command Line) rather than GitHub Desktop. If you need to install Git, GitHub provides a guide for various platforms. Instructions within these command-line interface sections will be using “bash”.

  1. Copy the repository URL:
    On your repository page, click the

    Code

    green button
    Copy the HTTPS URL (should look like: https://github.com/yourusername/your-repo-name.git)

  2. Clone the repository, using the HTTPS URL you’ve just copied:

    # Navigate to where you want to store the project
cd ~/Desktop  # or your preferred location

# Clone the repository
git clone https://github.com/yourusername/your-repo-name.git

# Navigate into the repository
cd your-repo-name

2.3 Phase 3: Branch Creation and Workflow

2.3.1 Step 5: Create Your Branch for the Docker Assignment

You may name your working branch whatever you like for each assignment. The examples/instructions use the name docker-assignment for the first example.

Option A: Using GitHub Desktop

Click on the “Current branch” dropdown (shows “main”)
Click “New branch”
Name your branch: docker-assignment
Click “Create branch”

Option B: Using a command-line interface 
# Create and switch to a new branch for the docker assignment
git checkout -b docker-assignment

# Verify you're on the new branch
git branch
# The asterisk (*) should be next to "docker-assignment"

2.4 Phase 4: Completion

2.4.1 Step 6: Collect a workflow URL

Navigate to github.com, specifically your repository/copy of the capstone sandbox.
Navigate to the .github/workflows directory.
Click on one of the workflow files that are present there.
Copy the URL from your web browser for this workflow file.
     • The URL will look like: https://github.com/your-username/your-repository-name/blob/main(or-your-branch)/.github/workflows/file_name.yml

If you are taking the course on Coursera:

Submit your Coursera Quiz

Go to your Coursera Graded Assignment (“Setting Up”).
Paste the URL you copied in Step 6.
Submit the quiz to get credit for your work.

icons from icons8

2.5 Your Setup is Complete…. What are the Next Steps?

This setup process creates the foundation for the Docker and GitHub Action capstone assignments, which will follow a similar pattern:

Create a branch → Make changes → Commit changes → Push to GitHub → Open a PR → Receive evaluation (→ iterate if needed).

For each assignment, create a new branch. Then make edits to accomplish the task of the assignment. Optionally you may be able to test those edits locally (e.g., building a docker image locally). Git commit and push those edits and open a pull request (or check an existing pull request) to receive evaluation from automated assignment checks. Interpret the results. If you were not successful, troubleshoot and iterate this process as needed, checking your pre-existing pull request for new evaluation results after making additional changes. Or if you were successful in your assignment, submit the verification code to your coursera quiz (or move on to the next section if you are not using coursera or some certification method to take this course)

The automated evaluation system depends on this workflow, so following these steps precisely is crucial for getting your validation codes!

Note that the validation codes are really only needed if you are participating in this capstone as a part of the Coursera or Leanpub platforms (for certification). If you are not taking this course for certification, there is no structure in place to verify the validation code you receive.

2.5.1 Reminders of Best Practices for Success while Working with GitHub

  • Use one branch per assignment - keeps work organized
  • Write descriptive commit messages - helps track your progress
  • Regularly push your work - protects your work and enables evaluation
  • Use clear titles and descriptions for pull requests - will help you and your collaborators know what the work in the branch is
  • Don’t merge your pull request before you get the validation code - outside of this assignment, wait for approval from a team member or collaborator
  • Monitor automated feedback - respond to or handle issues identified by evaluation promptly

2.6 Troubleshooting Common Issues

2.6.1 “Repository not found” when cloning:

Check that the repository is public
Verify the URL you’ve copy/pasted is correct
Ensure you have access to the repository

2.6.2 “Permission denied” when pushing:

Check that you’re pushing to your own repository (not the template)
Verify your Git credentials are set up correctly
Try using a personal access token instead of password

2.6.3 Automated evaluation not running:

Ensure your pull request is against the main branch
Check that required files are in the correct locations
Verify the repository is public

All illustrations CC-BY.
All other materials CC-BY unless noted otherwise.