TGMC:Guide to contributing

This page is a part of the TGMC wiki. TGMC is a project based on the CM-SS13 codebase.

The New "Coder" says: "Hey, I want to put in this feature that will revolutionized the game! So where do I start?"

You poor, poor soul.

Let’s get you on your way to contributing. This isn’t the guide for hardcore coders. This is for the guy who just wants a thing tweaked. If you’re really into making big feature changes, talk in the #Dev-General channel and get the people there to help you.

Prerequisite

• A GitHub account (https://github.com/)
• Visual studio code ( https://code.visualstudio.com/ )
• Git (https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
• Dream maker (already installed if you have BYOND)
• Coder socks (https://www.scientificworldinfo.com/2021/11/know-all-about-programmer-socks.html)
• A BLOOD CONTRACT TO SELL YOUR SOUL

GitKraken is old; throw it away and embrace the light that is Visual studio code.

Terms

Fork

A fork is a personal copy of another user's repository that lives on your account. Forks allow you to freely make changes to a project without affecting the original. Forks remain attached to the original, allowing you to submit a pull request to the original author to update with your changes. You can also keep your fork up to date by pulling in updates from the original.)

Repository

A repository is the most basic element of GitHub. They're easiest to imagine as a project's folder. A repository contains all of the project files (including documentation), and stores each file's revision history. Repositories can have multiple collaborators and can be either public or private.

Branch

A branch is a parallel version of a repository. It is contained within the repository, but does not affect the primary or master branch allowing you to work freely without disrupting the "live" version. When you've made the changes you want to make, you can merge your branch back into the master branch to publish your changes.

Pull Request

Pull requests are proposed changes to a repository submitted by a user and accepted or rejected by a repository's collaborators. Like issues, pull requests each have their own discussion forum.

Your own TGMC fork

Once you are connected on github, go to https://github.com/tgstation/TerraGov-Marine-Corps and click on fork.

This will give you your own copy of the TGMC code, where you test your stuff without interfering with the common repository.

Cloning the code

Go to your repositories in GitHub and click on TGMC.

You want to copy the HTTPS address of your fork, so click on code, then HTTPS and copy the link.

That’s everything we needed to do on the GitHub side, let’s switch to VSC (Visual studio code).

This should be the starting window on VSC, click on clone git repository, paste the repo link on the command line that appeared, and press enter. (Note: if you don't see the "Clone Git Repository" button it means that you have not installed git yet. See how to do that here)

It will ask you where to save the cloned files, so choose whatever folder you want (like My documents, or whatever).

If for some reason you don’t have clone git repo in the start menu, you need to open a new terminal, and type git clone the_url like so:

The files will be saved in C:\user\bsouchu in this exemple.

After the cloning, click on open folder and find where the files were saved.

Needed extensions

Now that you have access to your private version of the code, you need some VSC extensions to be able work on the code properly.

Go to extensions, then type @recommended in the search bar, and install everything there (Note: the list might change).

Reboot your VSC so all the changes are considered.

Adding the public remote

A remote is a git repository. In VSC, you want to have access to your private fork (which we will name here origin) to make changes to your version to the code, but also have access to the common public repo (the upstream) so you can pull the latest version of the code (AKA, always have the updated version).

Go to source control, remote, this should look like this:

And we want to add the upstream remote:

You now have access to the public repo.

If in the weird situation that you do not see any branches at all like this:

Hover your mouse over the upsteam to find the fetch button.

Let’s get the master branch from it (use the right click on master, chose switch to branch):

And name it master upstream.

This should look like something like this, click on the star to make it your preferred branch so it’s always at the top:

You then want to delete your master branch that is coming from origin (Never ever use this master, you ONLY need the master from upstream).

So right click on master, Delete Branch.

Rename your master_upstream to master; to do that, right click on master upstream, rename Branch.

Making modification to the code

The New "Coder" says: "Finally! I can get to CODE NEW FEATURES! Is this the start?"

You first want to make modification on the latest version of the code; having an outdated code means you’re surely have merge conflicts as soon as your PR is opened, which is pain.

You want to fetch (ask what the updates are) on the master branch (this is the upstream one, so it will directly fetch the latest server code version).

If your master version is out of date, the branch will change color. You now must pull to apply those new changes to your master (In this example, the master branch is 3 commits behind upstream master).

Never make changes to the master branch

Every time you want to make a modification to the code, you must first make a new branch.

Make sure you are making a branch from master, if you are not, click on the arrow pointing to the left to chose which branch to branch out.

Name your branch, press enter.

Create branch and switch on it.

Switching to a branch means your modification will apply to this branch and not the others. You can always switch to another branch by right clicking on it in the branch menu.

You can now make changes to the code!

Let’s say I want to make the tp44 fire with a 2 second delay (nerfing the revolver is a tradition on TGMC). Let’s go to revolvers.dm (Use the shortcut CTRL-e, then type revolver, then chose the guns/revolvers.dm one.)

Do your changes and hit CTRL-s to save the file.

Accidently saving in your master

The New "Coder" says: "OH FUCK!! I SAVED IN MASTER! HOW DO I FIX!?"

We have all made mistakes when we save changes in the master. Always double check if you are switch in the correct branch by looking at where the check mark is at.

This is not what you want the check mark to be.

This is definitely what you don't want your master to look like.

Do not worry; this can be saved. Toggle down your master to see this UI.

Right click on the previous commit before the screw-up commit you made.

On the top of VSC, it will pop up a new menu. Click on soft reset. If you click on hard reset, you will lose out on all the work you have done.

You will see this under your source control. Right click and unstage.

After you've unstage, switch branch to the one that is not your master and not remake this mistake again.

Testing your code

You can now test your modifications. That is very easy, you just need to hit F5! (or got to run and debug and click this button).

This will compile (the first compilation takes some time) and automatically launch the game; you’ll be able to join/observe with full access to admin/host powers.

With VSC come a very powerful debugger which allows access to all variables of the call stack (if you don’t understand those terms, that’s fine). Just keep in mind that if the game freezes, it’s not a crash; it’s a runtime, AKA an error/exception. To resume the game from such a freeze, you must go back to VSC and use the control panel.

Hit the resume button (not present on this screenshot).

Once you are happy with your tests, it’s time to make the PR.

Committing, publishing, and making a pull request

You’ll notice a blue 1 on source control, this means that you have a changed file that was not committed to the branch (A commit is like a snapshot of your code in a branch at a given moment, you can go back and forth between commits like you can go back and forth between branches).

Type a sensible commit message and commit your changes:

Note that it is a very good habit to commit every time you made a consequent change. If your PR is adding 3 features, it’s maybe a good idea to have 3 commits. That way, if your 2 first features are working but the third is breaking everything, you can go back to a version where at least 2 features are working.

After that, you want to publish your branch (aka, put your branch on the internet).

And push on origin. You can now go to https://github.com/tgstation/TerraGov-Marine-Corps/pulls and make a PR (pull request)

Fill out the pull request form, don’t forget to have a proper changelog:

Hit pull request, and voilà! You’re done.

It will also appear in the #github channel on discord:

The github server is now making some test on your code:

If something is red, click on it to look at what the error is.

Push modifications to a pull request

Maintainers will now be able to review your pull request. Be patient, this make takes a while, a pinging them will not result in a faster review.

If your PR has review requests, or if you just want to make changes to it, you just need to make new commits and push them.