Sharing on GitHub

Now that we've got everything squared away on our own computer, its time to share it with the world. The main avenue we'll use to share the code is GitHub, a code hosting site that is very popular with open source projects and developers. Once that is setup, we'll set up ReadTheDocs integration so that our documentation is hosted and automatically updated. We'll set up Travis CI so that our code is automatically checked by mpy-cross and that releases have mpy files on them.

GitHub

GitHub is the bees knees. They offer free project hosting including code, issues, wiki and website for open source projects. It is extremely popular for good reason. They integrate with git to host your code.

So, the first step to sharing your project is creating the GitHub git repository.

The repository name can be anything but we're sticking to Adafruit_CircuitPython_{name} for official Adafruit libraries and suggest CircuitPython_{name} for community libraries. Fill in the description with a short, informative sentence about your library. DO NOT check the Initialize box. We'll do that with our existing files in the next step.

On the next page click SSH and copy the text to the right of it starting with [email protected]. We're going to follow the second set of instructions because we've already created our local git repository (repo for short). The first step makes our local repo aware of the GitHub repo and names it tannewt rather than origin because I find it clearer to match the GitHub repository name. The second step pushes the commit we made before to the GitHub repository and makes the code public.

git remote add <your username> <the repo url>
git push -u <your username> master
For others who have used another version control system, this is the point where you shouldn't change your commits. Before this they were private to you. At this point they are public and others may build on them.

At this point, you may have been prompted for your GitHub password. If you entered it correctly it should work. I use GitHub Desktop to manage my login and recommend it.

Now we can verify our code is live by refresh our browser tab.

Woohoo! We're live! While we're here. Lets add the circuitpython topic to our repo by clicking Add topics, typing in circuitpython and clicking Done.

Better README

Now if we scroll down, we'll see our README. This is the single most important document for the whole project. It should be concise but contain basic description of the library, what it depends on, how to use it, how to contribute and where to find more detailed documentation.

Since our README doesn't have that information we'll do a quick edit to add some more information. I use Atom (created by GitHub) for file editing. It has good git integration including highlighting edited lines and files in orange.

Now that the file is up to date, I do a quick commit and push to make it live.

And if we refresh the repo page we see our new and improved README.

Ok! We're up and rolling. The code we've written is public, we've learned how to update it further and have a good README. We can click Commits on the front page to see a list of all our public commits on the front page. Next up is getting our docs on ReadTheDocs.

This guide was first published on Jul 31, 2017. It was last updated on Jul 31, 2017. This page (Sharing on GitHub) was last updated on Apr 03, 2019.