GitHub Style Guide

Welcome to the GitHub Style Guide! This guide is designed to help you understand the expectations for your GitHub repositories and how to structure your work for the semester. This guide will be updated throughout the semester as we learn more about GitHub and how to use it effectively for our projects. You will be graded on your use of GitHub and the quality of your repositories, so please make sure to follow these guidelines carefully, though we will also discuss them in class and provide feedback on your work.

Note

This style guide will be updated as we progress through the course and cover new topics, so please refer back to this. The instructors will let you know when there is additional guidelines.

Repositories

These guidelines for your is310-coding-assignments repository and your group repository available on the CultureAsData-UIUC organization. We will cover all of these in class but this guide is here for your reference.

General Guidelines

Specific Guidelines

.gitignore and No Private Files or Keys

Please make sure that you have a .gitignore file in your repository. This file should include any files that you do not want to be tracked by Git. This includes any files that contain private information or keys. If you are using an API key or any other sensitive information, please make sure that you are not committing this information to your repository.

Also ensure that sensitive or unnecessary files (such as temporary files, IDE config files, and large data files) are not pushed to the repository. Some common files to include in .gitignore are:

  • IDE files (e.g., .vscode/, .idea/)
  • OS-specific files (e.g., .DS_Store for macOS)
  • Log files (e.g., *.log)
  • Data or configuration files with sensitive information (e.g., .env, .json with API keys)

Example content for a .gitignore file:

# IDE files
.vscode/
.idea/

# OS-specific files
.DS_Store

# Log files
*.log

# Sensitive data files
*.env
*.json

README.md File

Your repository should have a README.md file that provides an overview of the contents of the repository. This file should include the following information:

  • A brief description of the repository and its purpose.
  • Instructions on how to run any code or scripts in the repository.
  • Any dependencies that are required to run the code.
  • A brief description of the files and directories in the repository.
  • Any other relevant information that would help someone understand the contents of the repository.
  • Contributors to the repository.

Here is an example of a README.md file:

# IS310 Coding Assignments

This repository contains the coding assignments for IS310: Computing in the Humanities.

## Repository Structure

Each folder in this repository corresponds to a different assignment. You can find a list of assignments on the course website.

## Running the Code

To run the code in this repository, you will need to have Python installed on your machine. You can install all dependencies by running the following command:


`pip install -r requirements.txt`


### Contributors

- @student1

Commit User Configuration

Please make sure that your commits are associated with your GitHub account. This will help us track your contributions to the repository and ensure that you receive credit for your work.

If you are seeing a different username or email address in your commits, you can update your Git configuration with the following commands:

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

You can check your current Git configuration with the following command:

git config --list

Folder Structure

Please make sure that your repository has a clear and organized folder structure. This will help you and others navigate the repository and find the files they need. You should create separate folders for different types of files or different assignments. For example, in your is310-coding-assignments repository, you need to have a folder for each assignment that corresponds to the correct name from the assignment.

For your project repository, you might have folders for data, code, documentation, and other relevant files. Make sure that the folder structure is logical and easy to understand. You can also include a README.md file in each folder to provide more information about the contents of that folder, as well as document the structure in your main README.md file at the root of the repository.

For example, your is310-coding-assignments repository might look like this:

is310-coding-assignments/
├── .gitignore
├── README.md
├── init-is310-homework/
│   ├── images/
│   └── README.md
└── command-line-maze/
    ├── command_line.zip
    └── README.md

And so your README.md file might look like this:

# IS310 Coding Assignments

This repository contains the coding assignments for IS310: Computing in the Humanities.

## Repository Structure

- `init-is310-homework`: Initial homework assignment.
- `command-line-maze`: Command line maze assignment.

Issues & Projects

These guidelines are primarily for your group repository, but you can also use them for your individual repositories. We will cover these in class but this guide is here for your reference.

General Guidelines