How to Submit Patches to Jason’s Projects

First of all, thank you for taking an interest in contributing to my projects. While every project is different, the process generally looks like this:

  1. Get a copy of the repository on your system.
  2. Try out the project on your system.
  3. Create a branch that contains your proposed changes.
  4. Send your patch to me.

The entire process is centered around Git. If you’re new to Git, then this process will probably be overwhelming. If you already have experience with Git, then you’ll probably want to skim through this document and only read the parts that look unfamiliar to you.

Get a copy of the repository on your system

The first thing you’ll need to do is clone the project’s repo. Run this command in a terminal:

git clone <repo-URL>

Here’s where you can find a project’s repo’s URL

Try out the project on your system

Eventually, you’re (probably) going to want to test out your changes. Before you do, it’s a good idea to test out an unchanged version of the project. Every project is different, so open up the repo you just cloned and start looking through the README. You should be able to figure out how to run or use the project by reading the README or by reading files that the README references. If you can’t, then please email me questions because the project’s documentation should probably be improved.

Create a branch that contains your proposed changes

In Git, a branch is like a timeline. Each branch contains a sequence of snapshots. Each of those snapshots is a single event in the branch’s history.

Open a terminal in your clone’s directory, and run this command:

git branch

Git will then tell you what branch you’re currently on. It will also list any other branches that you add to your clone. Your current branch will probably be named “main” (I think that the default branch for most of my repos is named “main”). To stay organized, it’s a good idea to create a new branch for each of your patches. To do so:

  1. Determine what branch you’re currently on:
    git branch
  2. If you’re not on the default branch, the switch to it:
    git checkout main

    If the repo doesn’t have a branch named “main”, then adjust that command accordingly.

  3. Create a copy of your current branch:
    git branch <branch-name>
  4. Switch to your new branch:
    git checkout <branch-name>

At this point, you’ve created your own branch but haven’t added anything to it yet. At the moment, your branch is identical to the main branch. Now it’s time to get to work. Create new files, delete old files or edit existing files. Don’t worry too much about making an unwanted change because Git is already holding onto multiple snapshots of the files in the repo. Every so often, you should create one of these snapshots. To do so:

  1. Determine what files have been created, deleted or edited:
    git status
  2. Before you can take a snapshot, you have to “stage” your changes. Changes that aren’t staged won’t make it into the snapshot.
    • If you created or edited a file, then run:
      git add <path-to-file>
    • If you deleted a file, then run:
      git rm <path-to-file>
    • If you renamed or moved a file, then run:
      git mv <old-path> <new-path>
    You can run git status again to see what changes are staged and unstaged.
  3. Take the snapshot:
    git commit
    This will create a new commit and put it at the tip of your current branch. In Git, snapshots are called “commits”.

Send your patch to me

Once you’ve created one or more commits, it’s time to turn those commits into a patch and send them to me.