Now is a great time to <a href="https://community.blockstack.org/" target="_blank">get involved with Blockstack</a>, 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.<h3>Github Organizations / Repositories</h3><a href="https://github.com/blockstack" target="_blank">Blockstack</a> - the main development repo for Blockstack<ul><li><a href="https://github.com/blockstack/blockstack-core" target="_blank">blockstack-core</a> (The Stacks 2.0 blockchain implementation)</li><li><a href="https://github.com/blockstack/blockstack-browser" target="_blank">blockstack-browser</a> (The Blockstack Browser allows you to explore the Blockstack internet)</li><li><a href="https://github.com/blockstack/gaia" target="_blank">gaia</a> (A decentralized high-performance storage system)</li><li><a href="https://github.com/blockstack/radiks" target="_blank">radiks</a> (A client-side framework for building model-driven decentralized applications)</li><li>(and many, many more tools)</li></ul><a href="https://github.com/blockstackers" target="_blank">Blockstackers</a> - the community repo for Blockstack <ul><li><a href="https://github.com/blockstackers/contribute-blockstack" target="_blank">contribute-blockstack</a> (the go-to resource for all Blockstack community projects)<a href="https://github.com/blockstackers/biz-model_pm" target="_blank"></a></li><li><a href="https://github.com/blockstackers/biz-model_pm" target="_blank">Business Model Project Management</a><a href="https://github.com/blockstackers/pox_pm" target="_blank"></a></li><li><a href="https://github.com/blockstackers/pox_pm" target="_blank">Proof of Transfer (PoX) Project Management</a></li></ul><a href="https://github.com/stacksgov" target="_blank">Stacksgov</a> - the community repo for Blockstack-related governance<ul><li><a href="https://github.com/stacksgov/resources" target="_blank">resources</a><a href="https://github.com/stacksgov/updates" target="_blank"></a> (Resources related to governance of the Stacks blockchain)</li><li><a href="https://github.com/stacksgov/updates" target="_blank">updates</a><a href="https://github.com/stacksgov/survey" target="_blank"></a> (Regular updates on project status for the community)</li><li><a href="https://github.com/stacksgov/survey" target="_blank">survey</a><a href="https://github.com/stacksgov/pm" target="_blank"></a> (Stacks governance community survey)</li><li><a href="https://github.com/stacksgov/pm" target="_blank">project management</a> (Project management related to stacks governance)</li></ul><h3>General git/Github Resources</h3><img src="https://gaia.blockstack.org/hub/1LZM5Ujeip9wYcr3UbUpXqcxmcesHSLgyB/photos/s0zMy6UW3cTOfR-Lm9dCg/QpVnRjK33AGXaH5qYfubc-xkcd-git.png" />Image Credit: <a href="https://xkcd.com/1597/" target="_blank">XKCD #1597: Git</a>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).<ul><li><a href="https://git-scm.com/doc" target="_blank">Git Manual</a> (the go-to for command and examples, unless you're the <code>man</code> type of person)</li><li><a href="https://dangitgit.com/" target="_blank">Dangit, git!</a> or its more unrefined counterpart <a href="https://ohshitgit.com" target="_blank">Oh Shit, Git!?!</a> (with real problems and solutions)</li><li><a href="https://gist.github.com/Chaser324/ce0505fbed06b947d962" target="_blank">Gist: GitHub Standard Fork &amp; Pull Request Workflow</a> (Chaser324)</li><li><a href="https://www.digitalocean.com/community/tutorials/how-to-create-a-pull-request-on-github" target="_blank">Digital Ocean - How To Create a Pull Request on GitHub</a></li></ul>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.<ul><li><a href="https://opensource.guide/how-to-contribute/" target="_blank">How to Contribute to Open Source</a> (opensource.guide)</li><li>also, from the above: <a href="https://opensource.guide/how-to-contribute/#how-to-submit-a-contribution" target="_blank">How to Submit a Contribution</a></li><li><a href="https://guides.github.com/" target="_blank">Github Guides</a> (short tutorials on specific topics)</li><li><a href="https://lab.github.com/" target="_blank">Github Learning Lab</a> (interactive exercises to reinforce concepts)</li></ul><ul><li>Individual repositories also (usually) contain a <a href="https://help.github.com/en/github/building-a-strong-community/setting-guidelines-for-repository-contributors#adding-a-contributing-file" target="_blank">CONTRIBUTING.MD file</a> to help with guidelines specific to that project. A few examples are linked from <a href="https://github.com/atom/atom/blob/master/CONTRIBUTING.md" target="_blank">Atom</a>, <a href="https://github.com/rails/rails/blob/master/CONTRIBUTING.md" target="_blank">Ruby on Rails</a>, and <a href="https://github.com/opengovernment/opengovernment/blob/master/CONTRIBUTING.md" target="_blank">Open Government</a></li></ul>This article assumes you already have <a href="https://github.com/join" target="_blank">a Github account</a>, a computer with <a href="https://git-scm.com/downloads" target="_blank">a working git installation</a>, and <a href="https://help.github.com/en/github/getting-started-with-github/set-up-git" target="_blank">the basic configuration between the two already done</a>. For my setup, I chose the following options:<ul><li><a href="https://help.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh" target="_blank">Using SSH instead of HTTPS </a></li><li>Using the <code>noreply</code> <a href="https://help.github.com/en/github/setting-up-and-managing-your-github-user-account/setting-your-commit-email-address" target="_blank">email for commits</a></li><li><a href="https://help.github.com/en/github/authenticating-to-github/managing-commit-signature-verification" target="_blank">Signing commits</a> with a GPG key</li></ul><h3>Terms and Definitions</h3>There 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. <ul><li>upstream: the original repository the fork was created from (on github.com) i.e. <a href="https://github.com/stacksgov/resources" target="_blank">stacksgov/resources</a></li><li>origin: the forked repository (on github.com) i.e. <a href="https://github.com/whoabuddy/stacksgov-resources" target="_blank">whoabuddy/stacksgov-resources</a></li></ul><ul><li>local: the local repository (on the computer) i.e. /path/to/the/file/on/disk (or c:\path\to\file on Windows)</li></ul>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.<h3>The Full Project Flow</h3>When working with a OSS project, this process works best for me so far. Please note that <code>&lt;</code> and <code>&gt;</code> represent placeholders for data, and the actual brackets are not used as part of the command.<ol><li>On github.com, <a href="https://help.github.com/en/github/getting-started-with-github/fork-a-repo" target="_blank">fork the repository</a></li><li>(optional) Rename the repository from the Settings tab, I prefer a prefix similar to the org name (i.e. <code>bks-</code> or <code>stacksgov-</code>)</li><li>Clone the repository from Github to your PC <code>git clone &lt;https/ssh address of fork&gt; &lt;local-folder&gt;</code></li><li>Change to the local directory Mac/Linux: <code>cd ./&lt;local-folder&gt;</code> Windows: <code>cd .\&lt;local-folder&gt;</code></li><li>Add the remote upstream repository to track changes <code>git remote add upstream &lt;ssh-address of upstream&gt;</code></li><li>Create and checkout new branch to make changes - <a href="https://allenan.com/git-branch-naming-conventions/" target="_blank">one opinion on naming branches</a>, several others available through search, I settled on a structure of "verb/intent" i.e. <code>upd/resource-list feat/omni-auth fix/auth-flow git checkout -b &lt;branch-name&gt;</code></li><li>Make changes and add simple commit messages - <a href="https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html" target="_blank">one opinion on commit messages</a>, several others available through search, I believe short, sweet and informative is the goal. <code>Less reading = more happy</code> for most people. <code>atom &lt;filename&gt;</code> &lt;-- or editor of your choice <code>git add &lt;filename&gt; or git add -A git commit -m "&lt;commit-msg&gt;"</code></li><li>Push the changes to the <code>origin</code> repository on Github (your fork) <code>git push origin &lt;branch-name&gt;</code></li><li>On github.com, <a href="https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests" target="_blank">submit the pull request (PR)</a> to the <code>upstream</code> repository when changes are complete</li></ol>Sometimes 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 <code>upstream</code> repository (usually <code>master</code>) has the changes from your <code>local</code> branch (i.e. <code>fix/bug-squash</code>), but your <code>origin/master</code> and <code>local/master</code> branches are out of date.To sync up with the upstream repository, follow the instructions below to perform a fast-forward (<a href="https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging" target="_blank">more explanation here</a>).<ol><li>Once the PR is accepted, or the upstream code changes, update the master branch from <code>upstream git status </code>&lt;-- always check what branch you are on!<code> git checkout master git fetch upstream master git merge upstream/master </code>&lt;-- updates <code>local</code> repo based on <code>upstream git push origin master </code>&lt;-- updates the <code>origin</code> repo based on <code>local</code></li><li>From here, you have two options: a. Delete the branch used for submitting the PR <code>git push origin -d &lt;branch&gt;</code> &lt;-- deletes branch on <code>origin</code> <code>git branch -d &lt;branch&gt; </code>&lt;-- deletes branch on <code>local</code> b. Update the branch based on master for future use <code>git checkout &lt;branch&gt; git rebase master </code>&lt;-- updates the <code>local branch</code> based on <code>local master git push origin &lt;branch&gt; </code>&lt;-- updates the <code>origin branch</code> based on <code>local branch</code></li></ol><h3>Other Useful Tips and Commands</h3>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.<h3>Tips / Tricks</h3><ul><li>Take your time, especially when working from the command-line</li><li>Always create new branches from <code>master</code>, otherwise you will make a big mess</li><li>Don't be afraid to test and learn, remember FAIL = First Attempt In Learning</li><li>It is common to chat with the community or create issues before submitting PRs</li><li>A branch for a PR can be submitted early as a Work in Progress (WIP), letting others know an issue is being worked on</li></ul><h3>Commands</h3><ul><li><code>git status</code> show current working tree status</li><li><code>git log</code> show commit logs or: <code>git log --pretty=format:"%h %s" --graph</code></li><li><code>git branch -a </code>show all branches</li><li><code>git remote -v </code>list remote repositories</li><li><code>git mv &lt;old-file&gt; &lt;new-file&gt;</code> move a file (change file name)</li><li><code>git rm &lt;file&gt;</code> delete a file</li><li><code>git commit --amend </code>modify last commit message</li></ul><h3>A Complete Walk-through</h3>While putting together this post I ran into the perfect opportunity to update an issue on the <a href="https://github.com/blockstack/blockstack.org" target="_blank">Blockstack website</a> as an example. I originally filed <a href="https://github.com/blockstack/blockstack.org/issues/1035" target="_blank">Issue #1035 regarding a broken image and link</a> in README.md, but I only <a href="https://github.com/blockstack/blockstack.org/pull/1036" target="_blank">updated the link from my PR</a> 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 <code>upstream</code> repository, but it is out of date.<ul><li><a href="https://github.com/blockstack/blockstack.org" target="_blank">blockstack/blockstack.org</a> &lt;-- <code>upstream</code> repository</li><li><a href="https://github.com/whoabuddy/bks-website" target="_blank">whoabuddy/bks-website</a> &lt;-- my fork (<code>origin</code> repository) Status (on Github.com): <code>This branch is 12 commits behind blockstack:master.</code></li></ul>I also have not set this up on my laptop before, so there is no <code>local</code> version of the repository yet. Let's get started by cloning my fork (<code>origin</code> --&gt; <code>local</code>), then updating both <code>origin</code> and <code>local</code> with the contents from <code>upstream</code>.<h3>Setting up the Local Environment</h3>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.<code>cd /media/$USER/mobivault/Dev</code><code>git clone git@github.com:whoabuddy/bks-website.git bks-website cd ./bks-website git remote add upstream git@github.com:blockstack/blockstack.org.git git fetch upstream master git merge upstream/master git push origin master</code>Now the status on Github.com shows: <code>This branch is even with blockstack:master.</code><h3>Making the Changes</h3>Remember to always check what branch you are working from, and to always create new branches from master!<code>git checkout -b upd/readme atom README.md </code>(removed code for image at top of file, saved and closed)<code> git add README.md git commit -m "removed image to match other repos" git push origin upd/readme</code><h3>Submitting the Pull Request</h3>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.<img src="https://gaia.blockstack.org/hub/1LZM5Ujeip9wYcr3UbUpXqcxmcesHSLgyB/photos/s0zMy6UW3cTOfR-Lm9dCg/Rb5uAq6q2Ahu_9v9f1Iaf-2020-03-09 13.03.27 github.com 508c98007ffe.png" />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. <img src="https://gaia.blockstack.org/hub/1LZM5Ujeip9wYcr3UbUpXqcxmcesHSLgyB/photos/s0zMy6UW3cTOfR-Lm9dCg/6iqUCWHmFSrR11rpRFWaW-2020-03-09 13.11.05 github.com 5817587dfba8.png" />Finally, my last step is to click Create pull request and wait for a response!<h3>Update 2020/03/11 - Pull Request Accepted!</h3>Lo, and behold, the email notification arrived and my change was merged into the master branch!<img src="https://gaia.blockstack.org/hub/1LZM5Ujeip9wYcr3UbUpXqcxmcesHSLgyB/photos/s0zMy6UW3cTOfR-Lm9dCg/3ntd0MY7Z0eMGgpoRy1sx-2020-03-11 09.28.54 github.com f65256e205ca.png" />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 (<code>origin</code>) repository is now out of date with the <code>upstream</code> repository.<img src="https://gaia.blockstack.org/hub/1LZM5Ujeip9wYcr3UbUpXqcxmcesHSLgyB/photos/s0zMy6UW3cTOfR-Lm9dCg/UJWxzW5Jm9YVp9HT0VxKQ-2020-03-11 09.31.41 github.com b866b74d992d.png" />Let's get that updated by taking the steps below.<code>cd /path/to/project/directory git status </code>&lt;-- always check what branch you're on!<code> git checkout master</code>Note: at this point you will see some information that confused me the first time through.<img src="https://gaia.blockstack.org/hub/1LZM5Ujeip9wYcr3UbUpXqcxmcesHSLgyB/photos/s0zMy6UW3cTOfR-Lm9dCg/wtBo4RpareYyWxIS4KpG5-Screenshot from 2020-03-11 09-33-46.png" />Based on the terms defined in the beginning, this actually makes sense, both <code>local</code> and <code>origin</code> are up to date with each other.<ul><li><code>upstream</code> (main repo on Github)</li><li><code>origin</code> (forked repo on Github)</li><li><code>local</code> (local repo on device)</li></ul>Our goal here is to update <code>local</code> with <code>upstream</code>, then push those updates to <code>origin</code>. <code>git fetch upstream master git merge upstream/master </code>&lt;-- performs a fast-forward if no conflicts<code> git push origin master</code>Now the forked branch (<code>origin</code>) is up to date with the original repo (<code>upstream</code>), and all is well with the world.<img src="https://gaia.blockstack.org/hub/1LZM5Ujeip9wYcr3UbUpXqcxmcesHSLgyB/photos/s0zMy6UW3cTOfR-Lm9dCg/bqusrfIW2NsVzfPT6IZsM-2020-03-11 09.41.39 github.com eeec5756dd0b.png" />For our final step, I no longer need the <code>upd/readme</code> branch, so I am going to delete it from <code>origin</code> and <code>local</code>.<code>git push origin -d upd/readme git branch -d upd/readme</code>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.

A basic outline of the Blockstack Github resources as well as instructions to work with Github repositories from the command-line.

Blockstack: How to -git- Involved