Working with GitHub: Commits, Issues, and Pull Requests

Commit

Commit messages consist of brief summaries of what changes were recently made to the codebase. To be of use to multiple people, commit messages should be relatively descriptive and adequately state what changes were made to the code and why they were made. For future commits, please be sure to include in your commit message the following information:

1. A one-line descriptive title
2. A brief description of what changes were made (this doesn't need to be elaborate)
3. A description of why those changes were necessary

One Commit. One Change to the Codebase.

A commit should encompass one idea, but no more. If you are making a change to a module and notice a syntax error, those two changes should be separated into different commits

Example (taken from How to Write a Git Commit Message):

Derezz the master control program

MCP turned out to be evil and had become intent on world domination.
This commit throws Tron's disc into MCP (causing its deresolution)
and turns it back into a chess game.

The title should never end with punctuation, and a single blank line should follow the title for visual white space.

Under NO circumstance should your commit message read "Update file_name" and nothing else. This is not helpful to anyone who wants to know what the updates were or why they were necessary.

Issue

GitHub Issues allows for users to submit problems, errors, or bugs they find within the codebase and keeps a log of those problems for the codebase authors (us) to review and fix. This is particularly helpful when dealing with individuals working on the codebase remotely (which several of us do regularly). As such, it is important for all posted issues to be descriptive and provide the following information, so that those tasked with fixing the issues have a reliable way of recreating and remedying the problem:

1. A short descriptive title
2. Thoroughly describe the problem
3. Add the stack trace when available
4. Provide context as to under what circumstances it comes up
5. Provide a list of steps (preferably terminal commands) to reproduce the issue
6. State what the expected output or outcome of the command should be
7. Tag the most relevant user in the repository (this will alert them that there is a new issue)
8. Add a Status label, a Priority label, and a Type label

A few other notes when posting new issues:

• Always assign a user to the issue (even if its yourself)
• Do NOT reply to issues via email (or if you do, be sure to remove your email footer before sending)
• Issue titles should be remain relatively small (ie. run_operations.py should be rewritten is too big for one issue)

Pull Request