↓Skip to main content
  1. Posts/

Showing Off Your Work on GitHub

··12 mins

So you’ve written a cool thing. Maybe it’s a game that you like and want to let other people play. Maybe it’s a library that you think other people could use. Maybe you want to show off your code to potential employers.

Whatever the reason, there are a few options for showing off your code online, but the most popular one is an online code-hosting platform called GitHub. GitHub lets you present your code in a nice web-accessible manner, allows you to write a snazzy README to explain what the project is about, and even lets you upload pre-built binaries, so that people can download and try out your code without having to install all the tools you used to build the code.

An example GitHub page. Users can browse the code in a web environment, look at a prettified README.md, and even download the program, all from the web interface and without having to install any development tools.

This post will walk you through the process of getting your project uploaded to GitHub and the steps you should take to make sure your code makes the best possible impression on people who are looking at your work.

Creating a GitHub Account and Downloading GitHub Desktop
#

If you haven’t already done so, you’ll need to create a GitHub account. Go to github.com/signup to create your account. Once you’ve completed all the sign-up steps and have an account, you’ll need to download the GitHub Desktop application from desktop.github.com and install it. Once you’ve opened it, select “Sign in to GitHub.com” and log in to GitHub from within the app. I suggest setting the app to use your GitHub account name and email address. Once you’ve done this, you should be greeted by a screen that says “Let’s get Started!” along with a few options along the left side of the window.

The GitHub Desktop application once you've logged in to your account. On the right are your current repositories on GitHub (your list might be empty), while on the left are actions you can take. We'll be using the last button on the left hand side to import your existing code to a new repository.

Creating Your Repository
#

Very roughly, Git works by taking snapshots of your project whenever you tell it to. These snapshots are called commits. Git will let you revert to any commit you’ve made in the past, which is great for undoing mistakes. Any set of commits that form a timeline is known as a repository. In order to get get your code onto GitHub, you’ll need to turn your project into a repository.

To do this, click on the button that says “Add an Existing Repository from your Hard Drive”. This will open a file browser. Navigate to the folder that contains all your project files. At this point, you should see an alert that says “This directory does not appear to be a Git repository. Would you like to create a repository here instead?”

The dialogue that will pop up when we try to add an existing folder. Click on the text that says "create a repository" in the alert message, then create your repository using the default settings.

Click on the button that says “Create a Repository”. This should open up a new dialogue box that has several fields. Ignore these for now—we can change them later if we want. Go ahead and click on the “Create Repository” button.

Checking Your Project and Uploading
#

At this point, you should see a new screen that has a bunch of information about your project. You should also see an empty “Changes” tab. This is because GitHub Desktop automatically commits (snapshots) all the files in your project directory when you create the project. To check that this worked, click on the “History” button near the top left of the window. You should see a commit message that says “Initial commit”, and the files in your project in the window to the right.

The "History" tab after we create our repository. Here, we can see that GitHub Desktop added both our project files to the repository and committed (snapshotted) them as part of making a new repository. Note that we are in the "History" tab here (outlined in red).

Go back to the “Changes” tab. In the main panel, you should see a box that says “Publish your repository to GitHub”. This will take the current commit of your project and make it available on GitHub. Click on the “Publish Repository” button.

The "Changes" tab after we create our repository. We will use either of the "Publish repository" buttons to make our project visible on the GitHub website.

You should see a popup box. The “Name” and “Description” field will be what’s shown on GitHub: try to pick a short name and description that still convey what your code does. Then, uncheck the box that says “Keep this code private” (it’s hard to show off your work if only you can see it!) and hit the “publish repository” button.

The dialogue box that pops up once we hit "Publish repository." Make sure to uncheck the box outlined in red, or nobody will be able to see your project!

Once you’ve done this, you should be able to click on the “View on GitHub” button in the main panel to see the web version as everyone else will see it. You’ve published a GitHub project!

Adding a README.md
#

You may notice that the web version of this project doesn’t have a pretty README. This is because we haven’t added one! Go to your project on your local machine (whatever directory you’ve stored it in) and create a new file called README.md.

The README.md is a special file that GitHub will automatically display on the web version of your project. For now, open the file in a text editor (Notepad, TextEdit, Visual Studio Code, etc.) and add the following contents to it:

# My Awesome Project

This is a demo readme for my project!
The "Changes" tab after we've create the README. We can see on the left that the README.md file is flagged as a change, and that the lines we've added will be added into the repository.

Save the file, and then go back to GitHub Desktop. In the “Changes” panel, you should see that GitHub Desktop has detected that you’ve added a new file. In the bottom left corner, there’s a box for you to enter some data for your commit message. Whenever you make a commit (snapshot), Git lets you enter a short message to describe what that commit does. This is useful if you ever need to come back and revisit your commit.

Where to enter your commit message. Use the blue button below the textbox (yours may say something slightly different) to make a commit, which will snapshot your README.md and store it into the repo.

For now, just enter “Create README.md” in the main box and leave the description empty, and then click on “Commit to main”. This creates a new commit which captures the README.md. However, this commit is only local: if you navigate to the website, you won’t see the README.md yet. To fix this, click on the “Push origin” button on the main panel (or in the top bar of the interface). This will push the commit containing your README.md to GitHub, so that it’s visible on the web.

The commit we just made is still stored only on our computer. We need to use one of the two push buttons (outlined in red) to make these changes visible on the GitHub website.

The Cycle: Edit, Commit, Push
#

Congratulations! You’ve now got a project on GitHub, complete with a README.md. The cycle you just used to create your README.md and get it displayed on GitHub is going to be the same one you use for almost all your changes. In short:

  1. Make a change to your project.
  2. Commit the change to your local repository using GitHub Desktop.
  3. Push the change to GitHub using GitHub Desktop.

This cycle is the core of Git and GitHub. It’s also what makes Git so powerful: every time you commit, Git will snapshot your repository, and you can always go back to a previous commit if you screwed something up.

The changes we just made, available on the GitHub web interface. Remember, this won't show up unless you **both** commit your changes locally **and** push them to the web!
GitHub will let you (as the repository owner) edit files directly in the web interface. This is almost always a bad idea, since it allows the copy on your computer and the one on the web to go out of sync, which can cause errors in the future. Until you get much better at Git, I recommend only editing files on your local computer and then publishing the changes using the procedure described above.

Making a Pretty README.md
#

Now that you know how to make commits, you should go back and make your README.md look nice. The README.md file is a markdown file, which is a special type of plaintext file that can be turned into the fancy stuff you see on GitHub. If you’re not used to Markdown, you can check out GitHub’s guide to Markdown for an idea of how to get started.

At the very least, your README should contain the following elements:

  1. A short description of what your project does. What does it do? If you wrote it to solve a problem, what problem does it solve? Why should people check it out?

  2. How to use/run your project. It’s very important that the instructions here work, since, if they don’t, most people are going to immediately abandon trying to use your project. If you’re using something like Processing or Node.js, which not everyone might have installed, place a link to the website so people know how to install it. If you need to install a third-party library, add step-by-step instructions for how to install it, or link to the library’s instructions.

    Don’t assume that everyone trying to install your project knows as much about the tooling as you do—in fact, most people trying out your project will know way, way less than you do! If you’re using something like Processing, they might not even know that it exists. Be as explicit as you can.

  3. You should have some sort of example of what people should expect once you’ve downloaded your code. If it’s a game, or application, include a screenshot. If it’s a library, include a code snippet or two that demonstrates what the library can do or what it’s capable of. Ideally, you should have full documentation for the project, but this won’t always be possible. However, you should have something that shows off what your project can do. This way, not only can someone get an idea of what your code is capable of without having to go through all the installation steps, but if they’re unsure if the installation worked, they have something to reference to see if things are working correctly.

And with all this, congratulations! You have all the elements of a good GitHub repository. There are a few more optional steps you can take if you really want to maximize your impact, but they are definitely optional.

Optional: Adding a License
#

Even though your code is now published on the internet, it’s still your code. As of right now, your code is “All Rights Reserved”, which means that no one can use your code without your permission. This is fine if you’re just showing off your stuff. However, if you have a library, or want people to be able to use and modify your code, you should add an open source license to your project. This gives other people permission to use your code, as long as they follow the rules of the license.

In general, there are two types of license:

  • Copyleft licenses require that anyone who uses your code also make their code available under the same license. This is the “pay it forward” type of license. If you want to use this type of license, I recommend using the GNU GPLv3.
  • Permissive licenses let people do whatever they want with your code, usually with the only restriction being that they have to reproduce the license notice somewhere in their program. If you want a license of this kind, I recommend the MIT License.

There are tons of licenses out there that hybridize between these approaches, and you can read all about them at choosealicense.com To license your project, simply create a file called LICENSE in your repository and copy the text of the appropriate license text into it.

Optional: Making a Release
#

If you have a project that’s a game or an application, it you might want to make releases so that people can download the application without having to go through the steps of downloading the language tooling and libraries, and building the project. This is especially helpful if you’ve made e.g. a game and want people to be able to play it right away.

To do this, go to your GitHub page and click on “Create a new release” in the right hand side. This will take you to a page where you can create a new release.

What you'll see after starting a release. You can upload programs to GitHub so that people can download and use them without having to go through the build process (which can often be fragile and easily broken).

You can add whatever you want to the title and description of the release, but the big point here is the box below the description that lets you attach binaries. If you have a game or application, you can attach the executable here. For Processing, you can create these by going to “File > Export Application” in the menu and creating standalone applications. Upload these to GitHub (with the appropriate names for each operating system) and voila, people can download your game without having to install Processing first!

Conclusion
#

Congratulations! You now have a copy of your code on the web that you can show off to friends, family, potential employers, and the squirrels on campus. Git is much, much more powerful than what we’ve gone over in this activity, and I highly recommend learning it if you plan to work on software in the future, but what you have here is more than enough serve as a demo.