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:

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.

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:

Determine what branch you’re currently on:
```
git branch
```
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.
Create a copy of your current branch:
```
git branch <branch-name>
```
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:

Determine what files have been created, deleted or edited:
```
git status
```
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.
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.

What to do if the repo is hosted on Jason’s Web Site.

You have four different options. For your first patch I recommend choosing the first one.
- Easiest: git-bundle
  1. Remember the name of the branch you created before. If you don’t remember it off of the top of your head, then you can run
    git branch
    to get a list of branches.
  2. Create a bundle that contains your changes:
    git bundle create <your-branch>.bundle main..<your-branch>
    That command is a little bit tricky. It creates a bundle file named “<your-branch>.bundle”. The last part of the command tells Git what to put into your bundle. “main..<your-branch>” means “every commit that’s in <your-branch>, but isn’t in main yet”.
  3. Email me the bundle. (If that links doesn’t work on your system, send it to “jason@jasonyundt.email”).
- Easy: git-format-patch + compression
  1. Remember the name of the branch you created before. If you don’t remember it off of the top of your head, then you can run
    git branch
    to get a list of branches.
  2. In your clone’s root directory, create a folder named “patch-v1”.
  3. Generate patch files:
    git format-patch \ -o patch-v1 \ --to='jason@jasonyundt.email' \ --subject-prefix='PATCH <repo-name>' \ main..<your-branch>
    
    If you’re interested in what that command does, then click here.
    
    \
    At the end of every line (except for the last one) is a backslash. Those backslashes allow me to break up the command over multiple lines. The last line doesn’t have a backslash, so Bash interprets the final newline as the end of the command.
    git format-patch
    This tells Git to create a series of patch files. Git will convert each commit that is specified into a patch file. A commit is a snapshot, it contains everything that was in the repo at the time it was taken. A patch file is a diff, it only contains information about what was changed. I’ll be able to (approximately) recreate your commits using the patch files that you generate.
    -o patch-v1
    This part is optional. It tells Git to put the patch files into a folder named “patch-v1”. I like to do this to stay organized.
    --to='jason@jasonyundt.email'
    This part is optional. It’s only really useful when sending patches using git-send-email. All it does is add a “To” field to each of the patch files. I include it because I think that it’s a good habit.
    --subject-prefix='PATCH <repo-name>'
    This part is optional. It’s only really useful when sending patches using git-send-email. This changes what goes in front of the patch files’s “subject line”. It’s useful for making sure that the recipient knows what repo the patch files are for.
    main..<your-branch>
    This part specifies which commits should be turned into patch files. “main..<your-branch>” means “every commit that’s in <your-branch>, but isn’t in main yet”.
  4. Compress the patch-v1 folder. You can do so by running this command:
    tar -cf patch-v1-compressed.tar.zst --zstd patch-v1
    or you can use another method that you’re more familiar with.
  5. Email me the compressed archive. (If that links doesn’t work on your system, send it to “jason@jasonyundt.email”).
- Medium: git-request-pull
  
  This strategy is good for people who already have some experience with Git. It’s not recommended for new users.
  1. If you don’t already have one that you want to use, create a public remote repository. If you’re not sure how or where to do this, then follow this guide to create a new repo on Codeberg.
  2. If you haven’t already, tell your local clone about your remote repo:
    git remote add pr <remote-repo-URL>
    Make sure that <remote-repo-URL> is a publicly accessible URL (use HTTPS, not SSH).
  3. Remember the name of the branch you created before. If you don’t remember it off of the top of your head, then you can run
    git branch
    to get a list of branches.
  4. Make sure that an up-to-date copy of your branch is available on the remote:
    git push pr <your-branch>
  5. (Optional) Resize your terminal to 78 characters wide.
  6. Generate the pull request message:
    git request-pull main pr <your-branch>
  7. Copy the pull request message and email it to me. (If that links doesn’t work on your system, send it to “jason@jasonyundt.email”).
- Hard: git-format-patch + git-send-email
  
  Patches should be sent to “jason@jasonyundt.email”. If you don’t already know how to use git-send-email, then check out git-send-email.io. I’ll give you some advice that git-send-email.io doesn’t mention: you can generate patch files using git-format-patch (don’t compress them), and then send them using git-send-email:
```
git send-email <directory-that-contains-patch-files>
```
  Most of the options that you can pass to git-send-email (like --to, --cc or -v2) can also be passed to git-format-patch.
What to do if the repo is hosted on pagure.io.
1. If you don’t already have one, create a fork of the upstream project.
2. If you haven’t already, tell your local clone about your fork by adding it as a remote:
```
git remote add pr <your-fork’s-URL>
```
  “pr” is just a name. You can call your remote whatever you want.
3. Remember the name of the branch you created before. If you don’t remember it off of the top of your head, then you can run
```
git branch
```
  to get a list of branches.
4. Push your local changes from your local repo to your remote fork:
```
git push pr <your-branch>
```
5. On the upstream repo’s page, create a pull request.
What to do if the repo is hosted on gitlab.com.
1. If you don’t already have one, create a fork of the upstream project.
2. If you haven’t already, tell your local clone about your fork by adding it as a remote:
```
git remote add pr <your-fork’s-URL>
```
  “pr” is just a name. You can call your remote whatever you want.
3. Remember the name of the branch you created before. If you don’t remember it off of the top of your head, then you can run
```
git branch
```
  to get a list of branches.
4. Push your local changes from your local repo to your remote fork:
```
git push pr <your-branch>
```
5. On the upstream repo’s page, create a merge request.
What to do if the repo is hosted on github.com.
1. If you don’t already have one, create a fork of the upstream project.
2. If you haven’t already, tell your local clone about your fork by adding it as a remote:
```
git remote add pr <your-fork’s-URL>
```
  “pr” is just a name. You can call your remote whatever you want.
3. Remember the name of the branch you created before. If you don’t remember it off of the top of your head, then you can run
```
git branch
```
  to get a list of branches.
4. Push your local changes from your local repo to your remote fork:
```
git push pr <your-branch>
```
5. On the upstream repo’s page, create a pull request.

How to Submit Patches to Jason’s Projects

Get a copy of the repository on your system

Try out the project on your system

Create a branch that contains your proposed changes

Send your patch to me