Mar 09•10 min read
Now is a great time to get involved with Blockstack, and the main way to do that is through Github. There are three main organizations to pay attention to, as well as some of their repositories listed below.
Please note: This information is current as of 2020/03/09. For the most up-to-date information, please visit the individual organizations/repositories themselves.
Blockstack - the main development repo for Blockstack
Blockstackers - the community repo for Blockstack
Stacksgov - the community repo for Blockstack-related governance
Image Credit: XKCD #1597: Git
Before I dive into what worked for me, I want to share a few resources that helped along the way. There is a ton of information out there about contributing to open source repositories (and some fun ones, at that).
man
type of person)Also, my preference is to work from the command-line, however there are some resources for working directly from Github.com as well. Below are some great resources for learning what works best for you.
This article assumes you already have a Github account, a computer with a working git installation, and the basic configuration between the two already done. For my setup, I chose the following options:
noreply
email for commitsThere were a few terms that, looking back now, make a ton more sense if they are defined up front. Below are three words that deeply correlate to the rest of the instructions.
Note: the definitions above are focused on people who plan to fork a project and submit changes back through a pull request because they do not have rights to the original project. If you are working with your own project/repository or maintaining a repository for an organization then the upstream bit can likely be left out.
When working with a OSS project, this process works best for me so far. Please note that <
and >
represent placeholders for data, and the actual brackets are not used as part of the command.
bks-
or stacksgov-
)git clone <https/ssh address of fork> <local-folder>
cd ./<local-folder>
cd .\<local-folder>
git remote add upstream <ssh-address of upstream>
upd/resource-list feat/omni-auth fix/auth-flow
git checkout -b <branch-name>
Less reading = more happy
for most people.atom <filename>
<-- or editor of your choicegit add <filename> or git add -A
git commit -m "<commit-msg>"
origin
repository on Github (your fork)git push origin <branch-name>
upstream
repository when changes are completeSometimes a pull request will require extra steps before going into review, which may include signing an agreement, testing the code, testing server deployment, or similar. If all checks are passed, then the PR is ready for review by the project maintainer.
During the review, a project maintainer may suggest (or make) edits, and once accepted, the PR will be merged into the main repository. At this point, the upstream
repository (usually master
) has the changes from your local
branch (i.e. fix/bug-squash
), but your origin/master
and local/master
branches are out of date.
To sync up with the upstream repository, follow the instructions below to perform a fast-forward (more explanation here).
upstream
git status
<-- always check what branch you are on!
git checkout master
git fetch upstream master
git merge upstream/master
<-- updates local
repo based on upstream
git push origin master
<-- updates the origin
repo based on local
git push origin -d <branch>
<-- deletes branch on origin
git branch -d <branch>
<-- deletes branch on local
git checkout <branch>
git rebase master
<-- updates the local branch
based on local master
git push origin <branch>
<-- updates the origin branch
based on local branch
In addition to the workflow above, below is a list of tips, tricks, and commands that are very useful at various times throughout the contribution process.
master
, otherwise you will make a big messgit status
show current working tree statusgit log
show commit logsgit log --pretty=format:"%h %s" --graph
git branch -a
show all branchesgit remote -v
list remote repositoriesgit mv <old-file> <new-file>
move a file (change file name)git rm <file>
delete a filegit commit --amend
modify last commit messageWhile putting together this post I ran into the perfect opportunity to update an issue on the Blockstack website as an example. I originally filed Issue #1035 regarding a broken image and link in README.md, but I only updated the link from my PR as I could not find a source for the image.
Now, after reviewing and seeing that all other Blockstack repositories do not have an image, I am going to propose a fix for the second half of the issue using that will remove the broken image (and close out #1035).
First off, I already have a fork of the upstream
repository, but it is out of date.
upstream
repositoryorigin
repository)This branch is 12 commits behind blockstack:master.
I also have not set this up on my laptop before, so there is no local
version of the repository yet. Let's get started by cloning my fork (origin
--> local
), then updating both origin
and local
with the contents from upstream
.
Remember to start from a working directory where you want to create project folders! I use a folder on my USB drive after the encrypted contents are mounted.
i.e.cd /media/$USER/mobivault/Dev
git clone [email protected]:whoabuddy/bks-website.git bks-website
cd ./bks-website
git remote add upstream [email protected]:blockstack/blockstack.org.git
git fetch upstream master
git merge upstream/master
git push origin master
Now the status on Github.com shows: This branch is even with blockstack:master.
Remember to always check what branch you are working from, and to always create new branches from master!
git checkout -b upd/readme
(removed code for image at top of file, saved and closed)
atom README.md
git add README.md
git commit -m "removed image to match other repos"
git push origin upd/readme
After pushing the changes, Github.com should recognize the new branch and recommend creating a pull request. An image like the one will show above the origin repository.
Clicking the button allows you to choose how you want the information to flow, as well as gives you a place to add additional comments to the repository maintainers. In this case, I make a quick note to the issue number (which automatically links to the issue in that repository), as well as links to the other repositories that I made my judgement call from.
The best practice is to try and keep these updates as short and meaningful as possible, while minimizing the amount of work a maintainer/reviewer has to do in order to publish.
Finally, my last step is to click Create pull request and wait for a response!
Lo, and behold, the email notification arrived and my change was merged into the master branch!
Now, we could use the big Delete branch button now that changes are complete, but wait a minute, we were doing this from the command-line! Also, you will notice that the forked (origin
) repository is now out of date with the upstream
repository.
Let's get that updated by taking the steps below.
cd /path/to/project/directory
<-- always check what branch you're on!
git status
git checkout master
Note: at this point you will see some information that confused me the first time through.
Based on the terms defined in the beginning, this actually makes sense, both local
and origin
are up to date with each other.
upstream
(main repo on Github)origin
(forked repo on Github)local
(local repo on device)Our goal here is to update local
with upstream
, then push those updates to origin
.
git fetch upstream master
<-- performs a fast-forward if no conflicts
git merge upstream/master
git push origin master
Now the forked branch (origin
) is up to date with the original repo (upstream
), and all is well with the world.
For our final step, I no longer need the upd/readme
branch, so I am going to delete it from origin
and local
.
git push origin -d upd/readme
git branch -d upd/readme
And, that's it! Now we are ready to move on to the next project, contribution, or cup of coffee to keep the day rolling.