Github

At its core level, Github is a website that allows developers to host their code (public or private). Each project is called a repository (repo), and within each repository Github provides a plethora of tools to help you maintain your and collaborate with others. It's also a great place to host your documentation, allowing for project specific wikis.

Example: SMAPI Repository

YouTube Explanation: Git It? How to use Git and Github

Why use Github?

Version-Control

Github keeps track of all the changes you've made to your repository, meaning you can view or revert back to older version. Anytime you change something, the changes are stored as a commit, which you can think of as "saving" your changes.

Example: SMAPI Commit History

Open-Source

When you make your repository public, your project is what's known as open-source. By doing this you help other struggling developers by offering your code as an example. On top of that other developers to find and fix bugs for you!

Other developers can create a fork of your repository, which means they make a copy of your repository. Their copy is still linked to yours, but the fork allows them to make edits to their version without those changes being made to the official repository.

Once they're done with their changes, they can send in a pull request, or a request for you to "pull" their changes from their fork, to the main repository. You'll be given a full view of every line changed and be able to approve, or disapprove their pull request. If you had made changes to your code after they forked your repository, Github will manage the conflicts and merge the two copies with both changes.

This means if someone finds a bug, they can fix it, send a pull request, and with a click of a button you'll have their changes!

Github repositories also provide an issues page in which people can submit issues. Each issue can be given tags, assignees, closed, and you can have a full conversation under each one.

Example: SMAPI Pull Requests

Example: SMAPI Issues

Collaboration

Github also provides features for multiple people working on the same project. On top of merging conflicts that might occur of two people make edits to the same code, Github also allows you to create branches in your repository.

Most developers have a main branch, or the code that is currently live (on Nexus). On top of that they'll have a develop branch. The "develop" branch might not be stable, and have ongoing work. But because it's separate from the main branch, any commits you make to the develop branch will not be reflected on the main branch. Once you're ready to make your changes official, you can create a pull request to pull all the changes from the develop branch, into the main branch.

Branches also help teams of developers work on the same code, ensuring while they commit changes, they're not stepping on each others toes. Conflicts are then handled when a pull request is made to merge the two branches together.

Example: SMAPI Branches

YouTube Tutorial: GitHub Pull Request in 100 Seconds

Getting Started

Creating an Account

To create an account you'll want to visit the Sign Up page on Github. Github is created by and maintained by Microsoft, so you can trust it!

You'll need to confirm your email via a code they'll send you, and don't worry about any of the Specific Features they offer. Everyone uses the Free plan and there aren't any noticeable pay-wall features you'll be missing out on.

Monorepo or Multirepo

One of the first choices you have to make is how you want to organize your code. Some developers prefer to keep all their mods in one repository (monorepo), some like to make a repository for each project (multirepo).

Monorepo

Pathoschild has one large repository for all his mods. Pathoschild/StardewMods. This has its downsides as your commit history, issues and pull requests are all throw together. Pathoschild states that because he spends more time maintaining and less time needing commit history, it's his preferred method.

Multirepo

Other big developers like spacechase0 use multirepo. spacechase0/JsonAssets, spacechase0/BiggerBackpack, spacechase0/GenericModConfigMenu. This allows for better use of the tools Github offers.

I'm very bias in this topic and prefer multirepo. For developers who have other projects and wish to maintain a portfolio for jobs, it would make more sense to have monorepo to avoid cluttering up your Github. Pathoschild has stated that most SMAPI developers use monorepo.

Create a Repository

Once you're ready to start a new project, you'll want to click the green button in the top-left that says Create repository, or click the plus button in the top-right.

Naming Conventions

Give your repository a name, keep in mind spaces will be removed. Most people either like to use upper camel case in which you capitalize the first letter of all words and use no spaces, or hyphenated lowercase in which you type in all lower-case letters and separate words with "-" dashes.

Upper Camel Case: SturdySpoon

Hyphenated Lowercase: sturdy-spoon

This really comes down to preference. I personally use the latter, Pathoschild and most other SMAPI developers I see use upper camel case.

Public or Private

Whether your repository is public or private is up to you. I'm very opinionated here.

Starting Rant:

Open-source code helps the community and allows others to help you grow as a developer and your mod improve. Have a question? Send them a link to the exact line on your repository. Have a bug? Allow others to fix it for you while you sit back and click merge on their pull requests. Have documentation? Add it to your repository or make a wiki for your repository (built into Github). Someone find a bug? They can submit an issue and let you know instantly. Stop updating your code? Other people can take over the project and keep it going. You'll go down in history. Downsides, people are shy, people are worried about intellectual property. By not being shy you can get feedback and grow as a developer! The modding community is kind and feedback is available if you ask. If you're worried about intellectual property, Github has a whole feature that helps you pick out a license for your code! You can sue people to your hearts content.

Ending Rant.

Once you're ready hit that Create button and you're good to go!

Adding Your Project

You will see a bunch of scary code on your empty repo with how to add files via command line. If you're interested, I'd suggest looking up a tutorial.

For anyone else, there's a blue link that says upload an existing file that will let you drop and drag your files in! You can drag your whole project folder directly into the window it provides to upload it. It will maintain the folder structure.

Once you've added your files, there's a green button at the bottom Commit changes which will save your changes. There are two text-fields above the green button. You should enter a brief 3-8 word summary of the changes you made. This will be the official name of the commit you make.

Making Changes

There are a few ways to make changes to your code. You can use command line as mentioned previously, you can use Github Desktop which makes it easier, but still involves a learning curve and is basically a fancy UI wrapped around the command line tool. For absolute beginners with no interest in learning much coding, you can edit the files directly in the browser.

To do this you first need to get the file you want to edit. Once you click your way to the file you want to edit, there's a small button at the top right of your file's text with the icon of a pen. Clicking that puts you in edit mode.

You can either make your changes here, or copy and paste what you've been working on locally. From there it's the same Commit changes button from before. Be sure to add a message!

Download your Repository

If you ever need to download your repository, navigate to your repository's main page. From there, there's a green button at the top-left labeled Code. Open that and you'll see a dropdown with one of the options being Download ZIP. Clicking that will start your download, and you'll have to unzip the file. You can do this by right-clicking the file and selecting Extract All...

Can't Find my Repository

If you lose your repository, just click on your profile picture in the top-right, and then click Your repositories. You should be able to find your repository from there.

More Resources

YouTube Tutorial: Git and GitHub for Beginners - Crash Course