how2contribute4dummies (#5)

* yayayayyaa

* whitespace

* blahbalbhahasl

* fuck microsoft

Author: corresp0nd

src/SUMMARY.md

@@ -7,7 +7,11 @@ General Help
 ====
 
 ---
-- [Getting Started](contributing/getting-started.md)
+- [Introduction](contributing/introduction.md)
+ - [Getting Started](contributing/getting-started.md)
+ - [Local Hosts](contributing/local-hosts.md)
+ - [Branching](contributing/branching.md)
+ - [Pull Requests](contributing/pull-requests.md)
 
 Design
 ===============

src/contributing/branching.md

@@ -0,0 +1,63 @@
+# What Next?
+So you've got a nice and updated local host, then obviously you want to jump in and figure out coding and your changes. However... you're not quite there yet! 
+
+If you make changes now, you'll be doing so on your *master branch.* Your PR will automatically be closed if it comes from your master branch, so first, you need to figure out how to use Git and make a new *branch.*
+
+If you want a more in depth explanation of Git, please see Wizden's [Git for the SS14 Developer](https://docs.spacestation14.com/en/general-development/setup/git-for-the-ss14-developer.html). This also has some information on how to use TortoiseGit and SmartGit, if you prefer those over Git Bash. 
+
+```admonish warning
+DO NOT SUBMIT PRS FROM YOUR MASTER BRANCH. 
+
+Your PR will be closed automatically if you submit from your master branch. 
+
+It can also cause issues for you later, so don't do it! PLEASE!!
+
+```
+# What is a Branch?
+
+A branch another copy of your codebase, which you make your changes onto. You are "branching" off of the main tree in order to develop and test your changes. When these changes are done, we can then merge them into the main branch--also known as a *pull request.* 
+
+We do this in order to help organize development. If you end up doing multiple projects at once, or even something like a minor bug fix while you are working on something else, branches help keep everything neat and separate. If you prefer to see things visually, there are many resources online explaining branches with visual guides. 
+
+# Working with Git
+Now, you have to actually make a branch. To get started, open Git Bash in your directory (the /funkystation/ folder created prior). Unless you've worked with Git Bash before, this will open it on your master branch. You can tell what branch Git Bash is currently on by the cyan text in parenthesis, it should say "(master)."
+
+
+The first command you need to know is `git checkout`. This is how you move between branches, you are checking out from one to the other. To make a new branch, you can simply do:
+
+- `git checkout -b branch-name`
+
+The -b tag means you want to make a new branch. You can replace `branch-name` with anything you want, just make sure it's unique. 
+
+After that... You're on a new branch! You can actually start coding now. After you finish your work, or need to save your work, you'll need to do two commands to *commit* your changes:
+
+- `git add -A`
+
+This "stages" the files to be committed. Basically you're telling Git that these are the files you edited and *want* to commit. The -A tag means all files, but you can remove it and individually add files for staging if you prefer.
+
+- `git commit -m "commit message here"`
+
+A commit basically an entry in your log of changes. The -m tag is so Git knows that you're attaching a message to the commit. If you don't add the tag, Git will probably open VIM (or whatever command line text editor you have installed. If you don't know what that is, it's probably VIM). 
+
+The message is so you know what was edited at a glance, but Git helpfully saves detailed information about what was edited in a commit. 
+
+```admonish warning
+HELP IT OPENED VIM!!
+VIM looks like some yellow text on top, a bunch of blue text, and a fuck ton of ~s everywhere. 
+
+It's terrible to use and you'll probably struggle to use it without someone telling you how to.
+
+First, see if it says "---INSERT---" at the bottom. If it does, great, if it doesn't, press `i`.
+
+Then type your commit message, press escape, and then type `:x`. Then boom! VIM is gone!
+```
+
+
+After you've finished all of your changes and committed them, the last step is to push them to your origin, GitHub:
+
+- `git push origin branch-name`
+
+Origin refers to Github, and `branch-name` would be the name of your current branch. After you do this, go to Github's website find your forked repository (you can click your PFP and then "My Repositories"). 
+
+Usually a nice little popup that says that the branch you were just working on had new changes. You can click "make a pull request" from there, or navigate to your branches and do the same thing. 
+Then, you can make a pull request!

src/contributing/getting-started.md

@@ -2,8 +2,6 @@
 
 ```admonish warning
 If you get some strange issues with Windows regarding Python, be sure to check these two during your Python install.
-
-If this doesn't work, understand that Microsoft sucks, and wants you to install Python through the Microsoft Store. Google can help you.
 <img src="/assets/getting-started/python_for_windows.png" width=512 style="margin-left:auto;margin-right:auto;display:block"/>
 ```
 
@@ -24,4 +22,13 @@ In your terminal window, type `git clone <your repo url here> .` (without the <>
 
 After it's done (you'll know when), type `python RUN_THIS.py`. Let that work, if it errors, reread the guide and make sure you followed all the steps.
 
-Congratulations, it's completed. To open a development build of Funky Station, you can now run the `runclient.bat` file, as well as the `runserver.bat` file to get a local server and client up.
+Congratulations, it's completed. To open a development build of Funky Station, you can now run the `runclient.bat` file, as well as the `runserver.bat` file to get a local server and client up.
+
+```admonish warning
+If you are using Windows and you get the following error:
+"Python was not found; run without arugments to install from the Microsoft Store,
+or disable this shortcut from Settings > Apps > Advanced app settings > App execution aliases"
+
+Fuck Microsoft. Go into the settings it tells you to and disable the duplicate execution alias. 
+Or just double click RUN_THIS.py. Whatever works. 
+```

src/contributing/introduction.md

@@ -0,0 +1,7 @@
+# What is This?
+This is meant to be both a guide of how to get started contributing for SS14 and an introduction to development as a whole. The end goal is that you not only have successfully made a pull request (PR), but that you also have a decent understanding of what, why, and how you do so. 
+
+People with any sort of development experience may find sections of this guide redundant; please keep in mind that it is written with new developers in mind. 
+
+# What's in This Guide?
+ This primarily focuses on introducing the tools you will be using to create a PR, rather than the nitty gritty of developing as a whole. Please consider looking at WizDen's [developer docs](https://docs.spacestation14.com/index.html) if you want to learn more about the finer details.

src/contributing/local-hosts.md

@@ -0,0 +1,63 @@
+# Why not use Github's Web Editor?
+I know it's tempting. Especially if you know that the change you want to make doesn't deal with actual C# code; maybe you want to fix a typo or rewrite one of the guidebook pages. Something small. 
+
+**PLEASE DON'T!!!!!!!!!!!**
+
+Part of this is for future proofing--learning how to use these tools on a small change helps prepare you to do larger changes later. Just because your changes are small now doesn't mean they will be later. 
+
+The web editor, and Github in general, can not handle large changes. Plus, changes you might think are small might be larger than you think. As an example, try to open the 'Files Changed' tab of a PR that changes maps. Usually it crashes. 
+
+Github also likes to fuck up files if you try to upload them through Github, rather than setting up a local host and doing all of this. Things like images getting lossy, audio getting bit crushed, et cetera. It sucks.
+# Creating a Local Host
+Please see Getting Started for information on how to get a local host on your computer. If you have an issues with this guide, you are always free to ask us in the Discord!
+
+Similarly, if you want a more detailed version of the same guide, consider reading WizDen's [Setting up a Development Environment](https://docs.spacestation14.com/en/general-development/setup/setting-up-a-development-environment.html)
+
+```admonish warning
+If you are using Windows and you get the following error:
+"Python was not found; run without arugments to install from the Microsoft Store,
+or disable this shortcut from Settings > Apps > Advanced app settings > App execution aliases"
+
+Fuck Microsoft. Go into the settings it tells you to and disable the duplicate execution alias. 
+Or just double click RUN_THIS.py. Whatever works. 
+```
+# Running a Local Host
+At the end of Getting Started, you run `runserver.bat` and `runclient.bat` to run your local host. This works fine, but sometimes issues arise with these default settings. 
+
+Most commonly, these two files open your local host in *Debug*. There are other .bat files to open your local host in different configurations (modes), however, there are other ways to do this that are generally a little better.
+
+The most common way is to use your IDE (integrated developer environment, the program you use to code) of choice. Use your IDE to open `SpaceStation14.sln` and then navigate to the build button. In Jetbrains Rider, it's in the top right. 
+
+If you don't have an IDE, you can also use command line to run and configure a local host. Git Bash works for this, just make sure you are in the correct directory. Then run:
+
+- `dotnet build`
+- `dotnet run --project Content.Server`
+- `dotnet run --project Content.Server`
+
+If you want to run your local host in a different configuration, add `--configuration Release/Debug/Tools` at the end of the two run commands. 
+# Updating a Local Host
+
+Assuming you followed the guide in Getting Started, you can just press the "Sync Fork" button on Github's website. Then it updates your fork! Yay! 
+
+If you prefer to update things manually, then you can also add a *remote* to fetch and merge into your local version. Make sure you are on your master branch while doing this. 
+
+A remote is a way for Git to know to go to that specific repository (a codebase) and grab changes and code from there. In this case, you'll need to add a remote for Funkystation's Github. You can do this in Git Bash by running:
+
+- `git remote add funkystation https://github.com/funky-station/funky-station.git`
+
+You can change `funkystation` to anything you want. This is just the name of the remote, so pick something you can remember easily! 
+
+If you need to add a remote for a different repository (such as Wizden or Goobstation), you can run the same command with the name and link changed. The link you want can be acquired by going to the repository's Github page, clicking the green "Code" button and then copying the link there. 
+
+After this, you need to *fetch* the remote. Fetching something means you are telling Git to go get everything on the remote and hold onto it:
+
+- `git fetch funkystation`
+
+Git Bash will spit out a lot of lines at you, assuming it's been a little while since you last updated your local host. This is good! If you get nothing, then that's also fine. It means whatever Git Bash is holding onto is up to date with Funkystation's repository. 
+If you get an error, usually the error message is pretty obvious with what's wrong. If it's something like "Remote not found!" then make sure you typed in the name correctly. 
+
+Then, you need to *merge* the remote into your local code:
+
+- `git merge funkystation/master`
+
+Notice the addition of `/master`! This just means that you are telling Git to merge specifically the master branch (the main code) of Funkystation into your code. There are other branches in Funkystation's repository, which we generally don't want. Git Bash will tell you it's updating, and then it's done! 

src/contributing/pull-requests.md

@@ -0,0 +1,27 @@
+# Pull Requests
+
+A *pull request* is a way for you to showcase your changes and ask for them to be merged into the main codebase. You are *requesting* that your changes be *pulled.* A little bit of a confusing term if you don't know the prerequisite jargon. 
+
+The last section of *Branching* tells you how to navigate Github and start your actual pull request. From here, you can select which branch you are PRing to. By default it is Funkystation's master branch, and you usually want to keep that the same. 
+You can also see the *diff* (the difference in files between your changes and the original codebase) here. Please make sure to review this, as you don't want any other changes sneaking into your PR. 
+
+Similarly, you'll want to fill out the description of your actual PR. Each section has an explanation in its comments, which are the sections enclosed with `<!-- -->`. PRs are more likely to be reviewed and merged if these sections are properly filled. 
+# Changelog Formatting
+
+Enclosed in comments is a sample changelog for your usage. Please make sure your changelog is formatted completely correctly, otherwise it won't appear in game.
+
+The format is as follows: 
+```
+🆑Username
+- add: 
+- remove: 
+- tweak: 
+- fix: 
+```
+
+For the username section, please make sure there are no special characters at all. Hyphens and exclamation points will break the changelog. You can also leave it blank if you prefer it to autofill your Github username. 
+# Reviews
+
+Once we receive a properly made PR, the maintainers will review your PR! We first look at things like test fails (CRLF check, YML linter, Content.Integration tests). Any related test fails will have to be corrected prior to being merged. 
+
+If the tests pass, great! We then review the code, discuss how it would impact the server, and then we either request changes, merge the PR, or close the PR. If you would like to know more about why or why not a PR was merged, please see our Design Principles.