TGMC:Guide to contributing: различия между версиями

Материал из MassMeta
Перейти к навигации Перейти к поиску
ВизуальныйВики-текст
imported>Hughgent
Нет описания правки
imported>Novaepee
 
(не показано 40 промежуточных версий 4 участников)
Строка 1: Строка 1:
{{TGMC}}
{{TGMC}}


You poor poor soul.  
{{Speech
|name=The New "Coder"
|text=Hey, I want to put in this feature that will revolutionized the game! So where do I start?
|image=[[File:Generic_assistant2.png|64px|right]]
}}
 
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.
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.


Since you’re reading this you’re already on the Discord. Head on over to the #coding channel and look at the top for this link.
=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)
*<s>A BLOOD CONTRACT TO SELL YOUR SOUL</s>
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.
 
[[File:Magic_of_git.png|center]]
 
=Your own TGMC fork=
 
Once you are connected on github, go to https://github.com/tgstation/TerraGov-Marine-Corps and click on fork.  


[https://github.com/tgstation/TerraGov-Marine-Corps https://github.com/tgstation/TerraGov-Marine-Corps]
[[File:TGMC_bravemole_contributing_guidePicture1.png|center]]


[[Image:image24.png.png|top]]
This will give you your own copy of the TGMC code, where you test your stuff without interfering with the common repository.


This will take you to the Github page. You’ll need to make an account if you don’t have one already.
=Cloning the code=


[[Image:image14.png.png|top]]
Go to your repositories in GitHub and click on TGMC.


Signed up or in? Great!
[[File:TGMC_bravemole_contributing_guidePicture2.png|center]]


The first thing you need to do is “Fork” this Github. This is the fork button.
You want to copy the HTTPS address of your fork, so click on code, then HTTPS and copy the link.


('''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.)
[[File:TGMC_bravemole_contributing_guidePicture3.png|center]]


[[Image:image12.png.png|top]]
That’s everything we needed to do on the GitHub side, let’s switch to VSC (Visual studio code).


This will take a moment, then it will bring you to your own personal Fork of the TGMC “Repository”
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.


('''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.)
[[File:TGMC_bravemole_contributing_guidePicture4.png|center]]
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:


[[Image:image26.png.png|top]]
[[File:TGMC_bravemole_contributing_guidePicture5.png|center]]


With this done, we want to take a step back and get two outside programs.
The files will be saved in C:\user\bsouchu in this exemple.


# [https://www.gitkraken.com/git-client GitKraken]
After the cloning, click on open folder and find where the files were saved.
## This is for advanced users of Github.
## Allows for much greater control of branches.
## As the opening paragraph stated, ask for help with this program.
# [https://www.sublimetext.com/ Sublime]
## Fantastically powerful and highly recommended.
## Can search the entire folder structure and each files contents for words.


[[File:TGMC_bravemole_contributing_guidePicture6.png|center]]


With Gitkraken and Sublime installed. We’re almost ready to start making changes.
=Needed extensions=


We need to get our fork of the TGMC repository on our computer.
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.  


Since you installed Gitkraken, we’ve got an easy button to use in Gitkraken.
Go to extensions, then type @recommended in the search bar, and install everything there (Note: the list might change).


[[Image:image11.png.png|top]]
[[File:TGMC_bravemole_contributing_guidePicture7.png|center]]


[[Image:image31.png.png|top]]
Reboot your VSC so all the changes are considered.


This will download the Forked Repository to your computer all ripe for modifying.
=Adding the public remote=


You can decide where it is put on your computer, but the default Documents/Github/ is perfectly fine.  
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).


So we are ready to do some changes!
Go to source control, remote, this should look like this:
[[File:TGMC_bravemole_contributing_guidePicture8.png|center]]


Let’s do something simple. Let’s alter the lobby music.
And we want to add the upstream remote:
[[File:TGMC_bravemole_contributing_guidePicture9.png|center]]


First we need to find where the lobby music is. And to do that, we should set up Sublime. So open Sublime then open the folder where you downloaded the Repository.
[[File:TGMC_bravemole_contributing_guidePicture10.png|center]]


[[Image:image6.png.png|top]]
You now have access to the public repo.


[[Image:image19.png.png|top]]
''If in the weird situation that you do not see any branches at all like this:''


Now Sublime looks a little like this.
[[File:TGMC_bravemole_guide_Nada.png|center]]


[[Image:image32.png.png|top]]
''Hover your mouse over the upsteam to find the fetch button.''


We’re gonna use a super nice command called “Find in Files” CTRL+SHIFT+F
[[File:TGMC_bravemole_guide_Nada2.png|center]]


[[Image:image27.png.png|top]]
Let’s get the master branch from it (use the right click on master, chose switch to branch):


This will open up a search bar at the bottom
[[File:TGMC_bravemole_contributing_guidePicture11.png|center]]
And name it master upstream.


[[Image:image30.png.png|top]]
[[File:TGMC_bravemole_contributing_guidePicture12.png|center]]


Typing in the text we want to search for and hitting enter, we get a BIG amount of text with every instance of the word “music” highlighted, along with a small amount of the surrounding text to give it context.
This should look like something like this, click on the star to make it your preferred branch so it’s always at the top:


Scrolling down we see that the lobby music is selected in this file.
[[File:TGMC_bravemole_contributing_guidePicture13.png|center]]


[[Image:image5.png.png|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).


Time to get our edit on!
So right click on master, Delete Branch.


Let’s just remove clown.ogg from the available selection. Double clicking the yellow text opens the relevant file.
Rename your master_upstream to master; to do that, right click on master upstream, rename Branch.


[[Image:image15.png.png|top]]
=Making modification to the code=


We find the list of music files.
{{Speech
|name=The New "Coder"
|text=Finally! I can get to CODE NEW FEATURES! Is this the start?
|image=[[File:Generic_assistant2.png|64px|right]]
}}


[[Image:image23.png.png|top]]
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.


Remove clown.ogg from the list.
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).  


[[Image:image1.png.png|top]]
[[File:TGMC_bravemole_contributing_guidePicture14.png|center]]


And save our work. CTRL+S
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).


At this point, we can look at Github Desktop, and things have changed!
[[File:TGMC_bravemole_contributing_guidePicture15.png|center]]
'''Never make changes to the master branch'''


[[Image:image7.png.png|top]]
Every time you want to make a modification to the code, you must first make a new branch.


We can see that we’ve changed one file, and what the specific change was. Red for removal, green for addition.
[[File:TGMC_bravemole_contributing_guidePicture16.png|center]]


Oh boy! All done right?
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.


Wrong! These changes have only happened on your computer.
[[File:TGMC_bravemole_contributing_guidePicture17.png|center]]
Name your branch, press enter.


So I should just get this online right away?
[[File:TGMC_bravemole_contributing_guidePicture18.png|center]]


Wrong again! We have to TEST our changes to make sure they work.
Create branch and switch on it.


First. Open Byond as if you were going to play a game. We need to be logged into Byond.
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.


[[Image:image4.png.png|top]]
[[File:TGMC_bravemole_contributing_guidePicture19.png|center]]


Online? Good.
You can now make changes to the code!


Second, open this file via double click.
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.)


[[Image:image28.png.png|top]]
Do your changes and hit CTRL-s to save the file.


Third, Compile and run the game.
==Accidently saving in your master==


[[Image:image2.png.png|top]]
{{Speech
|name=The New "Coder"
|text=OH FUCK!! I SAVED IN MASTER! HOW DO I FIX!?
|image=[[File:Generic_assistant2.png|64px|right]]
}}


This will take a moment.
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.


[[Image:image21.png.png|top]]
[[File:Saving_in_master1.png|center]]


Not compiling? Make sure your Byond client is up to date with the Beta Branch.
This is not what you want the check mark to be.
No errors? Thank goodness, this has passed the first check.


[[Image:image9.png.png|top]]
[[File:Saving_in_master2.png|center]]


There are hundreds of these safety checks. Select yes once with your mouse. Then just hold down the enter key to accept all of them. You’ll have to accept them all every time you run the game.
This is definitely what you don't want your master to look like.


[[Image:image8.png.png|top]]
[[File:Saving_in_master3.png|center]]


Oh snap, you’re in game and you’re an admin! Hooray it works! Test your feature/game balance/thing you want.
Do not worry; this can be saved. Toggle down your master to see this UI.


(in our case, we would keep running and re-running the game to start the lobby music multiple times. Each time checking that the clown.ogg music doesn’t get played.)
[[File:Saving_in_master4.png|center]]


No need to keep Byond and dream maker open, back to Github Desktop.
Right click on the previous commit before the screw-up commit you made.


We need to make a “Branch” for our change. We don’t want to change our master if we can help it.
[[File:Saving_in_master5.png|center]]


('''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.)
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.


[[Image:image25.png.png|top]]
[[File:Saving_in_master6.png|center]]


[[Image:image3.png.png|top]]
You will see this under your source control. Right click and unstage.


[[Image:image29.png.png|top]]
[[File:Saving_in_master7.png|center]]


Our changes are good, but first, we need to “Commit” them to the branch.
After you've unstage, switch branch to the one that is not your master and not remake this mistake again.


Give your update a name and a brief description in the bottom left corner.
=Testing your code=


[[Image:image18.png.png|top]]
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).  


And hit that “Commit to No-Clown-Musak” button.
[[File:TGMC_bravemole_contributing_guidePicture20.png|center]]
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.


Next we need to publish the branch moving our changes online to our fork
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.


[[Image:image33.png.png|top]]
Hit the resume button (not present on this screenshot).


It’s now online! Let’s go to our Github fork on the Github website.
[[File:TGMC_bravemole_contributing_guidePicture21.png|center]]
 
Once you are happy with your tests, it’s time to make the PR.


We’ve even got a nifty button all ready for us.
=Committing, publishing, and making a pull request=


[[Image:image13.png.png|top]]
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).


Now is the time to give our “Pull Request” a proper name and description.
[[File:TGMC_bravemole_contributing_guidePicture22.png|center]]


('''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.)
Type a sensible commit message and commit your changes: 


[[Image:image16.png.png|top]]
[[File:TGMC_bravemole_contributing_guidePicture23.png|center]]


The title should be a one sentence summary, at most.
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.


The description should give detail, and ingame examples if possible via screenshots hosted on an image hosting website. I recommend [https://imgur.com/ imgur.com]
After that, you want to publish your branch (aka, put your branch on the internet).  


Hit the big green “Create pull request” button and jobs a good one!
[[File:TGMC_bravemole_contributing_guidePicture24.png|center]]


Bask in the glow of accomplishing something grand!
And push on origin.
You can now go to https://github.com/tgstation/TerraGov-Marine-Corps/pulls and make a PR (pull request)


[[Image:image22.png.png|top]]
[[File:TGMC_bravemole_contributing_guidePicture25.png|center]]
Fill out the pull request form, don’t forget to have a proper changelog:
[[File:TGMC_bravemole_contributing_guidePicture26.png|center]]


See it on Discord in the #github channel!
Hit pull request, and voilà! You’re done.


[[Image:image20.png.png|top]]
[[File:TGMC_bravemole_contributing_guidePicture27.png|center]]
It will also appear in the #github channel on discord:


Realize you’ve made a terrible mistake!
[[File:TGMC_bravemole_contributing_guidePicture28.png|center]]
The github server is now making some test on your code:


[[Image:image10.png.png|top]]
[[File:TGMC_bravemole_contributing_guidePicture29.png|center]]
If something is red, click on it to look at what the error is.


[[Image:image17.png.png|top]]
=Push modifications to a pull request=


Phew, integrity saved!
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.


And that’s the basics of Contributing to TGMC
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.


Remember, the #dev-general and #coding are the places to be for more in depth questions, moral support,
[[File:TGMC_bravemole_contributing_guidePicture30.png|center]]
<br>
[[File:TGMC_bravemole_contributing_guidePicture31.png|center]]

Текущая версия от 07:29, 29 июня 2023

Файл:DMCA Logo.png This page is a part of the TGMC wiki.

TGMC is a project based on the CM-SS13 codebase.


  		The New "Coder" говорит:
"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[править | править код]

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.

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" говорит:
"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" говорит:
"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.


Источник — https://massmeta.ru/index.php?title=TGMC:Guide_to_contributing&oldid=51521