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: Culture as Data.

## 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

AI Chat Log Notes

When an assignment asks you to document your AI use, include a file named ai-chat-log.md in the assignment folder. This file should be a record of the relevant chatbot conversation for that assignment, including the prompts you wrote and the AI responses that shaped your work.

If you used an AI chatbot, include the important exchanges where you asked for help, debugged, revised, tested, or learned something. You do not need to include unrelated chatter or every failed detour, but the file should be more than a summary. If you did not use AI, you do not need to include a file.

Your ai-chat-log.md does not need to follow a fixed template, but it should be readable as a record of the relevant AI conversation and your decisions about how to use, revise, or reject that output.

Do not include personal information, API keys, passwords, private data, or unrelated chatbot conversation.

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.

For the semester project, your group will also use GitHub history as data about collaborative labor. Commits, issues, pull requests, reviews, and file histories will not capture every kind of work, but they can help make revision, testing, coordination, and documentation more visible. Try to commit regularly with descriptive messages so that your process is legible later.

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: Culture as Data.

## 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