Contribution Primer

General
1

For my personal account, I do the following, which i think is standard practice and makes creation of a PR easy:

Initial enlistment

click to expand

  1. Goto the Github repository you want to submit a PR for (e.g., GitHub - DangerousPrototypes/BusPirate5-firmware: Bus Pirate v5 Firmware)

  2. Click on the “Fork” button to create a fork of the repository under your own account.

  3. Enlist your copy of the repository. e.g., using the gh cli, a single command will clone and setup both origin and upstream remotes:

~$ gh repo clone henrygab/BusPirate5-firmware
~$ cd BusPirate5-firmware
~/BusPirate5-firmware/$ git remote -v

Similar results with slightly more commands needed:

~$ git clone https://github.com/henrygab/BusPirate5-firmware.git
~$ cd BusPirate5-firmware
~/BusPirate5-firmware$ git remote add upstream https://github.com/DangerousPrototypes/BusPirate5-firmware.git
~/BusPirate5-firmware$ git remote -v

You should have two remotes for your enlistment. Convention would be:

~/BusPirate5-firmware$ git remote -v
origin  https://github.com/henrygab/BusPirate5-firmware (fetch)
origin  https://github.com/henrygab/BusPirate5-firmware (push)
upstream        https://github.com/DangerousPrototypes/BusPirate5-firmware.git (fetch)
upstream        https://github.com/DangerousPrototypes/BusPirate5-firmware.git (push)

Terminology

click to expand

  • origin – by convention, this is the name of your fork on the remote server (e.g., https://github.com/henrygab/BusPirate5-firmware)
  • upstream – by convention, this is the name of the place where you will be submitting PRs to … it’s “upstream” of origin, which I think folk means to imply that origin is downstream and takes all the changes made upstream?
  • commit – often represented by seven hexadecimal digits (the first seven of the full hash … meant to uniquely identify a set of file contents. Each commit (except the first) has a prior commit that it was based on … this soon gives rise to a tree analogy…
  • branch – Just know that a branch in these examples has a base commit that it started at, and then may have additional commits that are only part of this branch. Note: main is a branch; by convention, it is often the trunk.
  • merge – Most commonly refers to taking changes from one branch and adding those changes to another branch.

Creating a branch to do work in

click to expand

First, ensure your depot is up-to-date:

git switch main
git pull --all
git merge --ff-only upstream/main

Then, create a branch and switch to it, and publish it on GitHub. Although you can give the branch a different name on GitHub than used locally, to avoid confusion it’s typically the same name.

git switch -c my_branch
git push --set-upstream origin my_branch

Keeping my main branch clean…

click to expand

There is no absolute rule here.

I periodically sync my main branch to the upstream branch, and ALWAYS use --ff-only for the main branch. This ensures that my main branch is 100% identical to the upstream main branch.

I find this is helpful in reducing problems later, and it also makes a number of commands simpler (by allowing me to avoid typing upstream/repeatedly).

Periodically updating the main branch (including just before a PR):

git swich main
git pull --all
git merge --ff-only upstream/main

Note that, because it’s kept identical to upstream, this update should NEVER fail or have merge conflicts. Hooray!

Building binaries … using GitHub

click to expand

git switch my_branch
git push

Then, go into GitHub, enable Actions for the depot, and manually run the GitHub action to build. This is free for public repositories, so if you don’t have a dev environment setup, you can still build and test your changes.

Once the build completes, look into the logs, and expand the “Artifacts” section. There’ll be a line saying the artifacts were saved, and giving a URL to download the ZIP file with the .UF2 binaries generated.

Neat!

Generating your first PR

click to expand

I recommend searching for better instructions online. :slight_smile:

Head to the github website, and specifically your fork.
For me, that is https://github.com/henrygab/BusPirate5-firmware/. Replace with your username…

The website will often show a large banner saying you’ve just pushed an update, with a quick link to start a PR. That makes it easy…

/details>

7 Likes