Difference between revisions of "Guide to Contributing"

From Paradise Station Wiki
Jump to navigation Jump to search
(I have unkind words for whoever formatted this, but I am very thankful that this page was created so I'm indifferent. :))
m (Protected "Guide to Contributing": Protecting outdated contribution pages until we fully delete em ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite)))
 
(37 intermediate revisions by 9 users not shown)
Line 1: Line 1:
This guide is modified from TGstation's "Setting up TortoiseGit guide". It is intended to be a one-stop guide for newbie contributing to Paradise Station.
This is outdated. It's recommended you use the Paradise Contributor Documentation, which can be found here. https://devdocs.paradisestation.org/
 
Before you contribute to Paradise, you will have to set up the following:
* Git (Mandatory)
* Some sort of Git Client (Optional, less powerful than command line Git, but make it easier to use)
* A proper text editor with highlighting, searching, etc. (Optional, you can use DM's native IDE, but it sucks)
 
Now let me explain all those terms briefly - Git is a distributed version control system we use so that multiple developers can work on the same project with minimized conflicts. You will '''NEED''' it to contribute to Paradise effectively, because our code is hosted on Github and also uses the git systems (That's where terms like "pull requests" "push" etc. come from). Because Git is operated through the command line (Git Bash), it can get a bit overwhelming for beginners, so I personally recommend installing a Git Client or two to make it easier to get started, and then you can learn the command line later.
 
Finally, the native editor for DM (The language games on BYOND are mostly written in), DreamMaker, is rather primitive, no ability to search files, search for definition of proc, multiple split windows etc. As a result, I highly recommend you use Atom or Visual Studio Code as your IDE, both of which have DM Plugins/Package, made by generous contributors in the SS13 community, that will make life much easier for you.
 
This guide will contain multiple guides collapsed into one. In the future they might be split into more. But first, let's start with getting Git and Github up.
 
==If you are having trouble==
Watch this video guide if you are having difficulty with any step below. [http://www.youtube.com/watch?v=Z5tTCo6IHLg]
 
==Installing Git & Setting up Github==
This part is about setting up Git and setting up your Github account.
 
<div class="toccolours mw-collapsible" style="width:99%">
<span style="font-size:1.2em;">'''Install Git'''</span><br>
* Go here: http://git-scm.com/downloads
* Download the Windows Git program. The appropriate, newest one for your operating system
* It should look something like 'Git-2.18.0-64-bit.exe'
* Install it and leave everything on default (just keep clicking next).
* Wait till the installer has finished.
* Done!
</div>
 
<div class="toccolours mw-collapsible" style="width:99%">
<span style="font-size:1.2em;">'''Register On Git'''</span><br>
(Skip if you already have an account, duh)
You'll need a github account to contribute to our repository (The place where the code is stored) properly.
* Head over here: https://github.com/
* Click '''Signup and Pricing''' in the top right-hand corner.
* Click the ''Create free account button'''.
* Create an account with your username and email.
* Done!
</div>
 
<div class="toccolours mw-collapsible" style="width:99%">
<span style="font-size:1.2em;">'''Hide your Email (Optional, Recommended)'''</span><br>
Some of you might want to show on your resume you worked on a spessman fart simulator. Or more practically, SS13 community is dark and full of terrors, and you would want to protect your email-address (Or use a disposable one in the first place).
Oh and, you might want to contribute to ERP servers under alternative account name.
* Log into your account on Github
* Go to the upper right, click your user profile
* A bar should pop up. Click settings
* Go to Email
* Set your email to private. Github will now use a noreply email address for web operations.
* Now you're somewhat more protected!
</div>
 
<div class="toccolours mw-collapsible" style="width:99%">
<span style="font-size:1.2em;">''' Configure Git (Optional)'''</span><br>
* Head here: https://help.github.com/articles/set-up-git/#setting-up-git
* Follow the guide above from steps 2 to 4, you can install Git for Windows if you want however it's not recommended
* Now you have Git all setup, but if you're command line illiterate like me, you'll wanna have some fancy graphics!
</div>
 
<div class="toccolours mw-collapsible" style="width:99%">
<span style="font-size:1.2em;">''' Set up Github Dark Theme'''</span><br>
A bright white theme may not be to your taste, so try this out:
* Read the guide here: https://github.com/StylishThemes/GitHub-Dark
</div>
 
<div class="toccolours mw-collapsible" style="width:99%">
<span style="font-size:1.2em;">'''Enrichment (Optional)'''</span><br>
These videos can help you understand Git better and switch over to command line one day:
 
https://www.youtube.com/watch?v=ZDR433b0HJY
 
Some further videos that are recommended watching for any git user:
 
https://www.youtube.com/watch?v=MYP56QJpDr4 - Git from bits up
 
https://www.youtube.com/watch?v=4XpnKHJAok8 - Linus Torvalds (yes that linus) (The guy who invented Linux, and Git) on git
</div>
 
==Setting up a Git IDE==
This part is about setting up an IDE to interface with Git more easily.
 
<div class="toccolours mw-collapsible" style="width:99%">
<span style="font-size:1.2em;">''' Using Git Command Line (STUB)'''</span><br>
</div>
 
<div class="toccolours mw-collapsible" style="width:99%">
<span style="font-size:1.2em;">'''Setting up & Using TortoiseGit'''</span><br>
* Go here: http://code.google.com/p/tortoisegit/wiki/Download
* Download the right TortoiseGit for your system.
* When installing, click '''OpenSSH''' rather than TortoisePLink
* Finish installing.
* '''RESTART YOUR COMPUTER THIS IS NOT A DRILL.'''
</div>
 
<div class="toccolours mw-collapsible" style="width:99%">
<span style="font-size:1.2em;">'''Forking Code'''</span><br>
* Head over to: https://github.com/ParadiseSS13/Paradise
* Click the '''Fork''' button in the top right corner.
* The page you'll be directed to is now your fork. You'll be pushing updates here, and making pull requests to have them merged the main (master) repository.
* Copy the HTTP URL. It's next to the '''HTTP''' '''GIT''' and '''Git Read-Only''' buttons. It'll look something like: https://github.com/NAME/Paradise
</div>
 
<div class="toccolours mw-collapsible" style="width:99%">
<span style="font-size:1.2em;">'''Downloading the Code'''</span><br>
* Find a place you don't mind the code sitting.
* Right click and choose '''Git Clone...'''
* The URL field should be filled with the URL of your Fork. If not, paste it in.
* Click Next and watch flying tortoises bring you your code.
</div>
 
<div class="toccolours mw-collapsible" style="width:99%">
<span style="font-size:1.2em;">'''DSetting up TortoiseGit'''</span><br>
* Right click '''on the folder that was created''' (usually called Paradise), and go to '''TortoiseGit''' and then click on '''Settings'''.
* Click on '''Remote''' under '''Git'''.
* There should be one thing on the list of remotes, with the name: '''origin'''.
* You're now adding the main repository as a source you can pull updates from.
* In the '''Remote''' box type in '''upstream'''.
* In the '''URL:''' box put: https://github.com/ParadiseSS13/Paradise.git
* Click '''Add New/Save'''.
* Click '''Ok'''.
* Almost done!
</div>
 
<div class="toccolours mw-collapsible" style="width:99%">
<span style="font-size:1.2em;">'''Updating your Repository'''</span><br>
* Updating your repo with the master should be done before trying anything.
* Right-click the folder your repo is in and select '''TortoiseGit''' then '''Pull'''.
* Click the radial button next to '''Remote''' and make sure '''upstream''' (or whatever you called it) is selected next to it.
* The '''remote branch''' should be set to '''master'''.
* Then click '''Ok'''. This will pull the latest changes from the master repo.
</div>
 
<div class="toccolours mw-collapsible" style="width:99%">
<span style="font-size:1.2em;">'''Making a Branch'''</span><br>
* '''Branching your repo is very important for organising your commits, you should have a different branch for each unrelated code change (e.g. if you wanted to make some new sprites for one item and change the properties of another these should be in seperate branches), as Pull requests work off branches rather than commits this will allow you to make a seperate Pull Request per change. Doing this streamlines the whole process and will save everyone a bunch of headaches.'''
* Right-click in your working folder. Then choose '''TortoiseGit''', and '''Create Branch...'''
* Type in your new branch name
* (Optional) Tick '''Switch to new branch'''
* Press '''Okay''' and your new branch is created
 
'''To switch between Branches:'''
* Right-click in your working folder. Then choose '''TortoiseGit''', and '''Switch/Checkout...'''
* Choose your Branch then press '''Okay'''
</div>
 
<div class="toccolours mw-collapsible" style="width:99%">
<span style="font-size:1.2em;">'''Making a Commit'''</span><br>
* A commit is confirmed change of the files in your repo, it's how you make changes permanently to the files in your repo, so try not to commit without making sure it works (though subsequent commits can fix it).
* As said before, you should use different branches to separate your commits/changes.  Don't commit to master.  It should be clean, so you can fall back on it if needed.
* To make your commits, you need to edit the files using BYOND's inbuilt editing tools. Make sure to follow coding standards when making your changes! When you're finished, right click the folder you're working with and choose '''Git Commit -> "[Your Branch Name]"''' (Example: Git Commit -> "My_First_Branch")
* You can then select only the files you want to be committed by ticking or unticking them. You should also write a detailed commit summary, detailing what happened in that commit.
* Click '''Ok''' and the commit will be committed to your local repo!
</div>
 
<div class="toccolours mw-collapsible" style="width:99%">
<span style="font-size:1.2em;">'''Making a Pull Request'''</span><br>
* Right-click in your working folder. Then choose '''TortoiseGit''', and '''Push...'''
* Set '''Local''' and '''Remote''' to the name of the branch you committed before. (e.g. My_First_Branch)
* Under Destination, set Remote: to '''origin'''.
* Click '''Ok'''. This'll upload your changes to your remote repo (the one on GitHub).
* Head to your GitHub repo e.g https://github.com/NAME/Paradise
* Click '''Pull Request''' at the top right.
* Fill out a summary and then create the pull request.
* You're done! In many cases there will be issues pointed out by other contributors, unfortunate merge conflicts, and other things that will require you to revisit your pull request.
* Optionally, view Clean Commits for a guide on cleaner commit logs, '''cleaner commits help maintainers review!'''
</div>
 
<div class="toccolours mw-collapsible" style="width:99%">
<span style="font-size:1.2em;">'''Clean commits / Squashing commits(Optional)'''</span><br>
* Your commit logs are filthy, full of one or two line commits that fix an error that makes you look bad, and the commit is called "Whoops" or "oops"
* Navigate to your '''local version of the branch'''
* Ensure it is up to date with the '''remote'''
* Go to '''Show log'''
* Select all the commits associated with this change or PR
* Right click and choose '''Combine to one commit'''
* This will open up the standard commit interface for TortoiseGit, with the commit logs of the selected commits merged together
* Perform the normal routine for a commit
* Go to '''push''' your branch to the '''remote branch'''
* Ensure '''Force Overwrite Existing Branch (may discard changes)''' is selected to make sure the PR/Remote updates to contain just this squashed commit
</div>
 
<div class="toccolours mw-collapsible" style="width:99%">
<span style="font-size:1.2em;">'''Setting up & Using GitKraken (STUB)'''</span><br>
</div>
 
<div class="toccolours mw-collapsible" style="width:99%">
<span style="font-size:1.2em;">'''Setting up & Using Github Desktop'''</span><br>
* Go here: http://https://desktop.github.com/
* Download the Github Desktop for your system.
* Wait till the installer is done and you're done installing!
* Follow the steps to sign into github.
</div>
 
<div class="toccolours mw-collapsible" style="width:99%">
<span style="font-size:1.2em;">'''Forking Code'''</span><br>
* Head over to: https://github.com/ParadiseSS13/Paradise
* Click the '''Fork''' button in the top right corner.
* The page you'll be directed to is now your fork. You'll be pushing updates here, and making pull requests to have them merged the main (master) repository.
* Copy the HTTP URL. It's next to the '''HTTP''' '''GIT''' and '''Git Read-Only''' buttons. It'll look something like: https://github.com/NAME/Paradise
</div>
 
<div class="toccolours mw-collapsible" style="width:99%">
<span style="font-size:1.2em;">'''Downloading the Code'''</span><br>
* Open Github Desktop
* Select "File", "Clone repository.."
* Select your forked Paradise repository.
* Select a suitable path of where the repository will be cloned into.
* Press Clone and wait till it's done.
</div>
 
<div class="toccolours mw-collapsible" style="width:99%">
<span style="font-size:1.2em;">'''Updating your Repo'''</span><br>
* Updating your repo with the master should be done before trying anything.
* Open Github Desktop and select your repository
* Click on the branch selection dropdown. And select your master
* Click on Choose a branch to merge into <b>master</b>
* Find the upstream/master branch and select it.
* Press the Merge <b>upstream/master</b> into <b>master</b>
</div>
 
<div class="toccolours mw-collapsible" style="width:99%">
<span style="font-size:1.2em;">'''Making a Branch'''</span><br>
* '''Branching your repo is very important for organising your commits, you should have a different branch for each unrelated code change (e.g. if you wanted to make some new sprites for one item and change the properties of another these should be in seperate branches), as Pull requests work off branches rather than commits this will allow you to make a seperate Pull Request per change. Doing this streamlines the whole process and will save everyone a bunch of headaches.'''
* Open Github Desktop and select your repository
* Click on the branch dropdown and click New branch.
* Give it a suitable name and then click Create branch
</div>
 
<div class="toccolours mw-collapsible" style="width:99%">
<span style="font-size:1.2em;">'''Switching between branches'''</span><br>
* Open Github Desktop and select your repository
* Click on the branch dropdown and select the branch you want to switch to.
* If you have open changes then it might fail. Either stash, commit or discard the open changes and try again.
</div>
 
<div class="toccolours mw-collapsible" style="width:99%">
<span style="font-size:1.2em;">'''Making a Commit'''</span><br>
* A commit is confirmed change of the files in your repo, it's how you make changes permanently to the files in your repo, so try not to commit without making sure it works (though subsequent commits can fix it).
* As said before, you should use different branches to separate your commits/changes.  Don't commit to master.  It should be clean, so you can fall back on it if needed.
* To make your commits, you need to edit the files using BYOND's inbuilt editing tools or any other editing tool such as Visual Studio Code. Make sure to follow coding standards when making your changes!
* Open Github Desktop and select your repository
* Check the changes once more over in the application.
* Give in the commit message
* Optional, give in a Description
* Press Commit to BRANCH NAME
</div>
 
<div class="toccolours mw-collapsible" style="width:99%">
<span style="font-size:1.2em;">'''Making a Pull Request'''</span><br>
* Open Github Desktop and select your repository
* Press the Public branch button
* Head to your GitHub repo e.g https://github.com/NAME/Paradise
* Click '''Pull Request''' at the top right.
* Fill out a summary and then create the pull request.
* You're done! In many cases there will be issues pointed out by other contributors, unfortunate merge conflicts, and other things that will require you to revisit your pull request.
</div>
 
==Text Editors==
Now your git client / git is set up, it is time to install a text editor to make editing DM code easier! Pick one, or both, if you like
<div class="toccolours mw-collapsible" style="width:99%">
<span style="font-size:1.2em;">'''Setting up & Using Atom (STUB)'''</span><br>
</div>
 
<div class="toccolours mw-collapsible" style="width:99%">
<span style="font-size:1.2em;">'''Setting up & Using Visual Studio Code'''</span><br>
=== Installing VScode ===
 
* Go to VSCode's website: https://code.visualstudio.com/
* Download the appropriate build for your system and install it.
 
=== Installing VSCode's plugins===
* Go to VScode's website and download the following plugins
* Clicking install will redirect you to VSCode where you can click install and reload it.
* Syntax highlighting: https://marketplace.visualstudio.com/items?itemName=gbasood.byond-dm-language-support
* Symbol seach: https://marketplace.visualstudio.com/items?itemName=platymuus.dm-langclient
* These plugins are extremely useful for coding in DM and should be considered essential
</div>
 
 
{{Template:Contribution Guides}}
 
[[Category:Guides]]

Latest revision as of 01:25, 19 October 2024

This is outdated. It's recommended you use the Paradise Contributor Documentation, which can be found here. https://devdocs.paradisestation.org/

Retrieved from "https://paradisestation.org/wiki/index.php?title=Guide_to_Contributing&oldid=48495"