From af7ce2d73716d1dbde1d3e48858c61d1ddac316d Mon Sep 17 00:00:00 2001
From: Aidan MacKenzie <102439396+aidanmackenzie@users.noreply.github.com>
Date: Thu, 2 Nov 2023 15:05:36 -0400
Subject: [PATCH 1/5] Update git-for-the-ss14-developer.md
Adding into doc.
---
.../setup/git-for-the-ss14-developer.md | 16 ++++++++--------
1 file changed, 8 insertions(+), 8 deletions(-)
diff --git a/src/en/general-development/setup/git-for-the-ss14-developer.md b/src/en/general-development/setup/git-for-the-ss14-developer.md
index 724e9da32..51a17a67f 100644
--- a/src/en/general-development/setup/git-for-the-ss14-developer.md
+++ b/src/en/general-development/setup/git-for-the-ss14-developer.md
@@ -1,22 +1,22 @@
# Git for the SS14 Developer
-If you've ever followed a hackily written guide to Git or opened up one of the many incredibly bloated modern git GUIs like GitKraken, you probably recognize that Git can be *really confusing*. The purpose of this guide is to give you just the information you need to develop properly for SS14 and give you the resources to learn more if necessary.
+If you've ever attempted to follow a written guide to Git or opened up one of the many modern git GUIs like GitKraken that often suffers from bloat, you probably recognize that Git can be *really confusing*. The purpose of this guide is to give you just the information you need to develop properly for SS14 and give you the resources to learn more if necessary.
Here are some more resources for learning about Git:
- [The Git-SCM online book](https://git-scm.com/book/en/v2)
-- [Atlassian's git guides](https://www.atlassian.com/git/tutorials/setting-up-a-repository). Good guides for some more advanced stuff
-- [Oh shit, Git?!](https://ohshitgit.com/), a list of solutions to common git problems. This one will come in handy.
+- [Atlassian's git guides](https://www.atlassian.com/git/tutorials/setting-up-a-repository). Good guides for some more advanced aspects of Git.
+- [Oh shit, Git?!](https://ohshitgit.com/), A list of solutions to common git problems, very handy to have available.
- [Learn Git Branching](https://learngitbranching.js.org/). This one is interactive, and very in-depth, but you **will have learned Git by the end of it**. Recommended for intermediate Git users.
## 1. Setting up Git itself
```admonish danger "DO NOT USE GITKRAKEN"
-For the love of god do not install GitKraken or GitHub Desktop. I have felt nothing but endless CBT trying to help people using either of them. I know GitKraken looks all professional and GH Desktop is nice and simple but please do not use either of them unless you know what you are doing.
+For the best results, please avoid using GitKraken or GitHub Desktop. While GitKraken certainly comes across as a very polished product, both it and GitHub Desktop have a series of confusing aspects. These should be left alone unless you're already comfortable with GitHub. This guide will not cover their use.
```
-If you were following our **"Setting up a Development Environment"** guide, you probably already have Git installed. If not, go to [their website](https://git-scm.org) and install it now. This will install the Git backend, as well as Git Bash (if you select that option)--one of the many ways you can actually use Git.
+If you were previously following our **"Setting up a Development Environment"** guide, you probably already have Git installed. If not, go to [their website](https://git-scm.org) and install it now. This will install the Git backend, as well as Git Bash (a command line interface or CLI for interacting with Git) if you select that option-- it's one of the many ways you can actually use Git.
-If you're on Linux, you'll probably just be using Git through your terminal or whichever IDE you've chosen, and chances are you have it installed already.
+If you're on Linux, you'll probably just be using Git through your terminal or whichever IDE you've chosen, and chances are you have it installed already. If not, feel free to head to (https://git-scm.com/download/linux) and find your distribution's instructions for installation.
I highly recommend at least trying Git Bash (as will a lot of our developers), but there are friendlier alternatives many use that I'll be showing steps for here as well:
@@ -28,7 +28,7 @@ I won't have steps for these (I'm recommending these after I initially wrote thi
- [Fork](https://git-fork.com/) -- fast and extremely ergonomic GUI, my personal favorite. "Non-free", but it's WinRAR-level non-free, so it's basically free. Has support for partial staging of
- [Sublime Merge](https://www.sublimemerge.com/) -- very similar to Fork, looks and feels great and I've gotten a lot of recommendations for it, though I haven't used it much. Also has support for partial staging.
-Most IDEs have some form of Git integration aswell. [Jetbrains Rider](https://www.jetbrains.com/rider/)'s Git integration is really good (and I personally recommend Rider for everything SS14-development related). I don't recommend Visual Studio's Git integration, because it's.. not very good.
+Most IDEs have some form of Git integration aswell. [Jetbrains Rider](https://www.jetbrains.com/rider/)'s Git integration is really good (and I personally recommend Rider for everything SS14-development related). Visual Studio has an integration as well, more info on it can be found at (https://learn.microsoft.com/en-us/visualstudio/version-control/git-with-visual-studio?view=vs-2022).
While you're here, install `Python 3.7+` as well if you don't have it already. You can do that [here](https://www.python.org/) for Windows and Mac, and if you're on Linux you almost certainly have Python installed already. If you don't, figure it out yourself, dork!
@@ -771,4 +771,4 @@ git fetch [username]
git checkout [username]/[branch name]
```
-This also lets you make PRs to their remote branch, if you so desired.
\ No newline at end of file
+This also lets you make PRs to their remote branch, if you so desired.
From 6e7e30ef1c0b424d657b4757ce52f79005e3822e Mon Sep 17 00:00:00 2001
From: Aidan MacKenzie <102439396+aidanmackenzie@users.noreply.github.com>
Date: Thu, 2 Nov 2023 15:17:41 -0400
Subject: [PATCH 2/5] Update git-for-the-ss14-developer.md
Section 1.0 Updated
---
.../setup/git-for-the-ss14-developer.md | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/src/en/general-development/setup/git-for-the-ss14-developer.md b/src/en/general-development/setup/git-for-the-ss14-developer.md
index 51a17a67f..3ae66c1f5 100644
--- a/src/en/general-development/setup/git-for-the-ss14-developer.md
+++ b/src/en/general-development/setup/git-for-the-ss14-developer.md
@@ -16,7 +16,7 @@ For the best results, please avoid using GitKraken or GitHub Desktop. While GitK
If you were previously following our **"Setting up a Development Environment"** guide, you probably already have Git installed. If not, go to [their website](https://git-scm.org) and install it now. This will install the Git backend, as well as Git Bash (a command line interface or CLI for interacting with Git) if you select that option-- it's one of the many ways you can actually use Git.
-If you're on Linux, you'll probably just be using Git through your terminal or whichever IDE you've chosen, and chances are you have it installed already. If not, feel free to head to (https://git-scm.com/download/linux) and find your distribution's instructions for installation.
+If you're on Linux, you'll probably just be using Git through your terminal or whichever IDE you've chosen, and chances are you have it installed already. If not, feel free to head to [Git for Linux](https://git-scm.com/download/linux) and find your distribution's instructions for installation.
I highly recommend at least trying Git Bash (as will a lot of our developers), but there are friendlier alternatives many use that I'll be showing steps for here as well:
@@ -28,15 +28,15 @@ I won't have steps for these (I'm recommending these after I initially wrote thi
- [Fork](https://git-fork.com/) -- fast and extremely ergonomic GUI, my personal favorite. "Non-free", but it's WinRAR-level non-free, so it's basically free. Has support for partial staging of
- [Sublime Merge](https://www.sublimemerge.com/) -- very similar to Fork, looks and feels great and I've gotten a lot of recommendations for it, though I haven't used it much. Also has support for partial staging.
-Most IDEs have some form of Git integration aswell. [Jetbrains Rider](https://www.jetbrains.com/rider/)'s Git integration is really good (and I personally recommend Rider for everything SS14-development related). Visual Studio has an integration as well, more info on it can be found at (https://learn.microsoft.com/en-us/visualstudio/version-control/git-with-visual-studio?view=vs-2022).
+Most IDEs have some form of Git integration aswell. [Jetbrains Rider](https://www.jetbrains.com/rider/)'s Git integration is really good (and I personally recommend Rider for everything SS14-development related). Visual Studio has an integration as well, more info on it can be found at [Visual Studio Git](https://learn.microsoft.com/en-us/visualstudio/version-control/git-with-visual-studio?view=vs-2022).
-While you're here, install `Python 3.7+` as well if you don't have it already. You can do that [here](https://www.python.org/) for Windows and Mac, and if you're on Linux you almost certainly have Python installed already. If you don't, figure it out yourself, dork!
+While you're here, install `Python 3.7+` as well if you don't have it already. You can do that [here](https://www.python.org/) for Windows and Mac, and if you're on Linux you almost certainly have Python installed already. If you don't or you're not quite sure, a guide to installing Python on Linux can be found here [Python Linux Guide] (https://docs.python-guide.org/starting/install3/linux/).
-Now that you have Git installed, I recommend you read up a bit on the basics of it first and get acquainted with whatever git client you're working with, whether its just command-line (Git Bash) or anything else.
+Now that you have Git installed, I recommend you read up a bit on the basics of it first and get acquainted with whatever git client you're working with, whether its just command-line (Git Bash) or anything else. For instance, a guide to GitBash can be found here [Git Bash Guide](https://www.atlassian.com/git/tutorials/git-bash).
-We're going to run through the process of setting up a Git environment for Space Station 14 so that you can **contribute code through pull requests, create your own codebase**, or just **check out the history of the project.**
+Now that you're feeling a bit more comfortable with the basics of Git, let's talk about utilizing it here. We're going to run through the process of setting up a Git environment for Space Station 14 so that you can **contribute code through pull requests, create your own codebase**, or just **check out the history of the project.**
### 1.1 Why are we even using Git?
From 8c675022fefa4757d7e1749e7ed1fc6cbd681ae1 Mon Sep 17 00:00:00 2001
From: Aidan MacKenzie <102439396+aidanmackenzie@users.noreply.github.com>
Date: Thu, 2 Nov 2023 15:26:34 -0400
Subject: [PATCH 3/5] Update git-for-the-ss14-developer.md
Making progress. Onto cloning.
---
.../setup/git-for-the-ss14-developer.md | 14 +++++++-------
1 file changed, 7 insertions(+), 7 deletions(-)
diff --git a/src/en/general-development/setup/git-for-the-ss14-developer.md b/src/en/general-development/setup/git-for-the-ss14-developer.md
index 3ae66c1f5..b0218d596 100644
--- a/src/en/general-development/setup/git-for-the-ss14-developer.md
+++ b/src/en/general-development/setup/git-for-the-ss14-developer.md
@@ -38,9 +38,9 @@ Now that you have Git installed, I recommend you read up a bit on the basics of
Now that you're feeling a bit more comfortable with the basics of Git, let's talk about utilizing it here. We're going to run through the process of setting up a Git environment for Space Station 14 so that you can **contribute code through pull requests, create your own codebase**, or just **check out the history of the project.**
-### 1.1 Why are we even using Git?
+### 1.1 Why are we using Git?
-Git is **version-control software**--basically, it's an easy way to track changes to the code, and manage those changes without headaches. It's an invaluable tool for software development, because it easily lets you make new changes, view different changes, see who made changes, etc. without having to coordinate and tabulate everything yourself.
+Git is **version-control software**--basically, it's an easy way to track changes to the code, and manage those changes without giving yourself and others headaches. It's an invaluable tool for software development, because it easily lets you make new changes, view different changes, see who made changes, etc. without having to coordinate and tabulate everything yourself.
GitHub is an online service that hosts Git **repositories** (codebases) for easy collaboration. It's perfect for a codebase like SS14, with lots of contributors and lots of history. It also means that we're *open-source*--anyone can go to our GitHub and download the code!
@@ -48,23 +48,23 @@ GitHub is an online service that hosts Git **repositories** (codebases) for easy
Like I said before, a repository is just a codebase. Repositories contain some **branches**, and those branches contain different **commits**. You might have heard of both of these--I'll talk more about them in depth later.
-A **remote** repository is just a repository's that's on GitHub. A **local** repository is one that's actually on your computer.
+A **remote** repository is just a repository's that's on GitHub. A **local** repository is one that's actually stored on your computer.
### 2.1 Creating your remote repository
-First, let's make our own remote repository fork of Space Station 14. You'll need a GitHub account for this, of course. 'Forking' it like this just means you're copying all of the repository's history and changes into your own remote repository so that you can do stuff freely to the code.
+First, let's make our own remote repository fork of Space Station 14. You'll need a GitHub account for this, so feel free to make an account [GitHub](https://github.com/). 'Forking' it like this just means you're copying all of the repository's history and changes into your own remote repository so that you can do stuff freely to the code.
-Your remote repository doesn't automatically update with changes from the original SS14 repo--you'll have to do that yourself, which I'll talk about later.
+Your remote repository doesn't automatically update with changes made to the original SS14 repo--you'll have to do that yourself, which I'll talk about later.
Navigate to the [Space Station 14 repository](https://github.com/space-wizards/space-station-14) and click here:
![](https://i.imgur.com/lAHNHdD.png)
-From there, it'll ask you where to fork it and what to name it--just to your regular account, and name it whatever you please! I'd stick with `space-station-14` if you just want to help out with development, though.
+From there, it'll ask you where to fork it and what to name it--just to your regular account, and name it whatever you please! For the sake of keeping things organized though I'd stick with `space-station-14` if you're looking to help out with development, though.
### 2.2 Creating your local repository
-Now, we'll need to download our remote repository onto our computer (**cloning**) so we can add ~~20 pairs of clown shoes to every locker~~ some changes to it. You *can* technically change your remote repository (GitHub has some nice tools), but having it on your computer means you use IDEs like Visual Studio or Rider to build the game and run tests, as well as handle Git stuff easily.
+Now, we'll need to download our remote repository onto our computer (**cloning**) so we can start adding some changes to it. You *can* technically change your remote repository (GitHub has some nice tools), but having it on your computer means you use IDEs like Visual Studio or Rider to build the game and run tests, as well as handle Git stuff easily.
For every step, there will be screenshots and instructions for Git Bash, SmartGit, and TortoiseGit on Windows.
From 7ffcca72c27e29e9e8e90cc5a6b03e4e3d576d86 Mon Sep 17 00:00:00 2001
From: Aidan MacKenzie <102439396+aidanmackenzie@users.noreply.github.com>
Date: Thu, 2 Nov 2023 16:43:31 -0400
Subject: [PATCH 4/5] Update git-for-the-ss14-developer.md
Just need to add conclusion.
---
.../setup/git-for-the-ss14-developer.md | 86 +++++++++----------
1 file changed, 42 insertions(+), 44 deletions(-)
diff --git a/src/en/general-development/setup/git-for-the-ss14-developer.md b/src/en/general-development/setup/git-for-the-ss14-developer.md
index b0218d596..45aa95166 100644
--- a/src/en/general-development/setup/git-for-the-ss14-developer.md
+++ b/src/en/general-development/setup/git-for-the-ss14-developer.md
@@ -73,7 +73,7 @@ Navigate to somewhere on your computer where you want to put the local repositor
TortoiseGit
-Right click to see TortoiseGit's context menu stuff:
+Right click to see TortoiseGit's context menu:
![](https://i.imgur.com/QGmrQmH.png)
@@ -135,27 +135,27 @@ Every Git command will look something like this--`git` and then a keyword like `
-After this completes, you have a local repository that you can now modify! There's still some more setup to go through, though.
+After this completes, you have a local repository that you can now modify! There's still some more setup to go through though.
### 2.3 Submodule woes
-**Pay attention to this!** If you don't do this, you'll get a lot of weird errors about stuff not being available when you actually try to build the game.
+**Very important, please pay attention to this!** If you don't do this, you'll get a lot of undesireable errors about things not being available when you actually try to build the game.
Space Station 14 has a *lot* of submodules--most notably our engine, RobustToolbox. Submodules are just repositories inside a repository, and they need to be updated manually by you. Or do they?
We have an automatic submodule updater so you don’t have to worry about running `git submodule update --init --recursive` (the command for manually updating submodules) all the time.
-Run `RUN_THIS.py` inside the repo you downloaded with Python. Preferably from a terminal too (`python RUN_THIS.py` or `python3 RUN_THIS.py`). This should take a few seconds so if it instantly stops you probably aren’t using Python 3.7+ or something.
+Run `RUN_THIS.py` inside the repo you downloaded with Python. Preferably from a terminal too (`python RUN_THIS.py` or `python3 RUN_THIS.py`). This should take a few seconds so if it instantly stops there's a reasonable chance you aren’t using Python 3.7 or greater.
If you are on Windows and get redirected to the Microsoft Store or encounter a message in your terminal claiming that Python is not installed when you attempt to run the above command, you will need to disable the Microsoft shortcut that might be causing this issue. You can do this by searching for `Manage App Execution Aliases` in the Windows search and then turning off the two Python references.
If you do want to modify the engine directly however, or you want to update the submodule manually (the auto updating can be a pain occasionally), make a file called DISABLE_SUBMODULE_AUTOUPDATE inside the BuildChecker/ directory.
-If you ever need to manually update RobustToolbox for whatever reason you can use `cd RobustToolbox; git checkout v0.4.87`(replace `v0.4.87` with the latest RobustToolbox release) then you can use `cd..\` to get back into your SS14 repo. This is also an example of using `cd` to navigate files from the comfort of your command line.
+If you ever find yourself needing to manually update RobustToolbox you can use `cd RobustToolbox; git checkout v0.4.87`(replace `v0.4.87` with the latest RobustToolbox release) then you can use `cd..\` to get back into your SS14 repo. Note that this is also an example of using `cd` to navigate files from the comfort of your command line.
## 3. Setting up remotes
-When you cloned your remote repository, a **remote** was automatically added to your local repository. **Remotes** are just named URLs to remote repositories that Git keeps track of so you can do stuff like download (pull) new changes to the code or upload (push) code to your forked repository.
+When you cloned your remote repository, a **remote** was automatically added to your local repository. **Remotes** are just named URLs to remote repositories that Git keeps track of so you can download (pull) new changes to the code or upload (push) code to your forked repository.
In this case, the remote automatically added is called`origin` and it points to `https://github.com/[username-here]/space-station-14` (or whatever you named the remote repository).
@@ -193,19 +193,19 @@ One issue: we don't have a reference to the original `space-wizards/space-statio
All this does is add a new remote named `upstream` that points to the original `space-wizards/space-station-14` repository. Now we can receive updates from the main repository whenever we want! (see below on how to do that).
-The convention is to call the remote pointing to the original repository `upstream` but you can technically call it whatever you like. I'll be referring to it as 'the upstream', though, and it's terminology Git guides use as well.
+The convention is to call the remote pointing to the original repository `upstream` but you can technically call it whatever you like. From here on out we'll be referring to it as 'the upstream', as it's terminology Git guides often use as well.
## 4. Branching & Commits
-Branches and commits are two of the most important concepts in Git, and most of the work you do will revolve around them.
+Branches and commits are two of the most important concepts in Git, and the majority of the work you do will revolve around them.
### 4.1 Whats a commit?
-Like I mentioned before, **commits** are just packaged up changes to the code. As the developer, you choose which changes go into a commit and when to commit those changes. **Committing** refers to creating a commit, and it essentially makes a save point that you can go back to at any time.
+Like I mentioned before, **commits** are just packaged up changes to the code. As the developer, you choose which changes go into a commit and when to commit those changes. **Committing** refers to creating a commit, and the core idea behind it is that it makes a save point that you can go back to at any time.
Commits have an author, timestamp, a message, and some code changes attached to them. They also have a really long 'commit hash', a unique identifier used to refer to different commits.
-Commits are how history is built up--you can actually view the history of every single commit made to the SS14 repository from the beginning, which is pretty cool:
+Commits are how history is built up--you can actually view the history of every single commit made to the SS14 repository from the beginning, which can give you an intersting timeline into the game:
![](https://i.imgur.com/HQDdw6h.png)
@@ -213,17 +213,17 @@ Commits are how history is built up--you can actually view the history of every
### 4.2 What's a branch?
-**Branches** are very, very important. They're basically just a list of changes to the code (commits). The default branch is 'master', and all of our servers use that branch to compile the code.
+**Branches** are an absolutely vital concept. At their core, branches are separate copies/versions of the code (commits) that branch off of the main code. The default branch is 'master', and all of our servers use that branch to compile the code.
You're pretty much always 'on a branch' when you're working with your code, and you can switch which branch you're working on easily.
Generally, branches are named for whatever you're going to be working on in them, but it doesn't *really* matter what they're named.
-You can make as many branches as you like. When you create a branch, it 'branches out' (no shit, really?) from the current branch you're on and becomes its own independent thing you can add commits to.
+You can make as many branches as you like. When you create a branch, it 'branches out' from the current branch you're on and becomes its own independent thing you can add commits to.
![](https://i.imgur.com/ByMugxu.png=500x300)
-In this diagram, each little node is a different commit, and each color is a different branch.
+In this diagram, each little node is a different commit, and each color is a different branch. As you can see, enough branches and you start to get a proper code tree!
#### Branch merging
@@ -240,15 +240,15 @@ Pull requests show all this info very well:
In this pull request, Swept started out by creating a new branch. Since he now had a fresh branch free of interference to work with, he started working on the feature and created commits to 'save his progress' whenever he felt it was necessary. These commits were added to the branch sequentially, and you can see the evolution of the branch as more code was written. We'll talk more about pull requests later.
-#### But whyyy?
+#### But why branch?
-Okay, technically, sure, you can just do all of your work on the `master` branch and pull request from there. But, creating different branches makes it easy to understand where you are, how many changes you've made, and it makes it possible to work on multiple features at once.
+Sure, you can just do all of your work on the `master` branch and pull request from there. But, creating different branches makes it easy to understand where you are, how many changes you've made, and it makes it possible to work on multiple features at once.
-Also we'll close your PR if it's from your `master` branch (it can very easily cause issues) so don't do it.
+Also, as a note, we'll close your PR if it's from your `master` branch (it can very easily cause issues) so avoid doing it.
### 4.3 Making and working with branches
-Making branches is pretty easy. Let's make a new branch called `funny-feature`:
+Making branches is quite simple. Let's make a new branch called `funny-feature`:
TortoiseGit
@@ -284,7 +284,7 @@ The `-b` in `git checkout` here means 'checkout this branch, and create it if it
Now, you can work freely with this branch as you please without fear of messing up your all-important master branch.
-Switching between branches is pretty easy: it's called **checking out** a branch. When you do this, your files and folders locally will be changed to match the branch, so Git will yell at you if you have local changes and you try to check out.
+Switching between branches is also quite easy: it's called **checking out** a branch. When you do this, your files and folders locally will be changed to match the branch, so Git will warn you if you have local changes and you try to check out.
Checking out a branch:
@@ -314,13 +314,13 @@ Checking out a branch:
-Then, make whatever local changes you want! It doesn't really matter. Make a new file, delete everything, change one line in a file, etc. It won't affect your `master` branch, because this is`funny-feature` land now!
+Then, feel free to make whatever local changes you want! It won't have a direct impact on your `master` branch. Make a new file, delete everything, change one line in a file, etc. It won't affect your `master` branch, because we're in the `funny-feature` branch!
### 4.4 Staging and committing changes to your branch
One more important thing: Before you can `commit` your changes, you have to `add` your changes to the **staging area**. All this means is that you're specifying which files you want to commit. This is helpful, because you *almost never* want to commit submodule changes, so you avoid that by not adding them to the staging area.
-As mentioned before, commits always come with a message, which is just a short, imperative description of what's being done in that commit. Or you can be a chad and name every commit "changes stuff", up to you.
+As mentioned before, commits always come with a message, which is just a short, imperative description of what's being done in that commit.
If you want to see what you've currently changed, and what's in the staging area, it's pretty easy:
@@ -329,7 +329,7 @@ If you want to see what you've currently changed, and what's in the staging area
![](https://i.imgur.com/xmZKKWJ.png)
-TortoiseGit also shows changed files/folders (a red icon in the bottom right) in the Windows Explorer which is really nice and why I have it installed in the first place.
+TortoiseGit also shows changed files/folders (a red icon in the bottom right) in the Windows Explorer which is very user friendly and why I have it installed in the first place.
@@ -339,7 +339,7 @@ TortoiseGit also shows changed files/folders (a red icon in the bottom right) in
![](https://i.imgur.com/ROsurs1.png)
-This is assuming you installed SmartGit with the option that the main window shows diffs and status. If you didn't, I don't really know where it is.
+This is assuming you installed SmartGit with the option that the main window shows diffs and status.
@@ -384,11 +384,11 @@ Now that you've verified that all of these changes look good, we'll add them to
-Woo, we've committed our changes to a branch! Now that they're committed, they're in the history of the branch forever (sort of). We can do a lot of things now: merge our `funny-feature` into our local `master` branch (if we wanted, for some reason), upload (push) our `funny-feature` branch to our remote repository, or nuke the branch entirely (among other things). We'll opt for pushing the branch and making a pull request now.
+Great news, we've committed our changes to a branch! Now that they're committed, they're in the history of the branch forever (sort of). We can do a lot of things now: merge our `funny-feature` into our local `master` branch (if we wanted), upload (push) our `funny-feature` branch to our remote repository, or delete the branch entirely (among other things). We'll opt for pushing the branch and making a pull request now.
## 5. Pushing and making a PR
-A **pull request** is a GitHub-specific thing. It just means that you want a codebase to merge your changes on one of your branches into one of their branches--usually to their `master` branch. Before we can do this, our remote GitHub repository (origin) needs to know about the beautiful branches and commits we've created locally, so we upload or **push** those changes to the remote.
+A **pull request (PR)** is specific to GitHub. It just means that you want a codebase to merge your changes on one of your branches into one of their branches--usually to their `master` branch. Before we can do this, our remote GitHub repository (origin) needs to know about the branches and commits we've created locally, so we upload or **push** those changes to the remote.
### 5.1 Pushing commits
@@ -428,7 +428,7 @@ Selecting 'push all branches' does what it says on the tin. Can be useful.
### 5.2 Making a pull request
-Now, the fun part. We'll go to GitHub now and make a pull request for our funny feature.
+Now, the fun part. We'll go to GitHub now and make a pull request for our funny feature branch.
![](https://i.imgur.com/YNmEMtG.png)
@@ -438,9 +438,9 @@ Add a description, a nice title, some screenshots, and hopefully it gets merged.
Maybe it's been a while, a week or two, since your last pull request, and you'd like to make another. Before you do anything, you need to download (**pull**) the code changes from the main SS14 repository into your local repository. If you don't, you'll have out-of-date code and your local changes may not be accurate to how the game will actually run--you might even get **merge conflicts** when you try to PR.
-There are two ways to update your repository. Both methods assume you have the `upstream` remote set up properly--if not, go back to earlier in the guide.
+There are two ways to update your repository. Both methods assume you have the `upstream` remote set up properly--if not, go back to earlier in the guide in order to get that set up.
-The first method, **fetch+merge**, gives you more control but can be confusing. The second method, **pulling**, is simple and easy but doesn't give you much control. However, pulling is usually all you need.
+The first method, **fetch+merge**, gives you more control but can be confusing. The second method, **pulling**, is simple and easy but doesn't give you much control. However, pulling is usually all you need.
### 6.1 Fetch + merge method
@@ -467,7 +467,7 @@ Make sure you select `upstream` and not origin!
![](https://i.imgur.com/CNFFJJ8.png)
-I think smartgit fetches from all remotes when you click this?????
+I believe smartgit fetches from all remotes when you click this.
If it doesn't and it just fetches from origin, go to the bottom left and do this:
@@ -559,20 +559,20 @@ First, checkout your `master` branch. We covered this earlier. Then,
-If either method went well, you've successfully updated your master branch (or whichever branch you chose to update)! Do this regularly, and always before you start work on a new branch.
+If either method went well, you've successfully updated your master branch (or whichever branch you chose to update)! Do this regularly, and always before you start work on a new branch. For a bit of a deeper dive into pulling versus fetching, see here [fetch/pull](https://www.theserverside.com/blog/Coffee-Talk-Java-News-Stories-and-Opinions/Git-pull-vs-fetch-Whats-the-difference).
# Addendums
## 1. Things to keep in mind
-You've more or less learned the workflow for developing features for SS14 Git-wise, but here's some things I'd really like to hammer into your mind:
-- When creating a new feature, *always always always* create a new branch off of `master` before committing anything. If you accidentally commit your physics changes to your bike horn branch, you're not in for a fun time, but it is fixable (see Oh Shit, Git?! above)
-- **Never, ever commit RobustToolbox or any submodules like Lidgren.Network** unless you know what you're doing. In the top-level local repository, these submodules are considered 'files', so it's easy to accidentally stage and commit them. Do not do this. See below for how to fix your fuckups if it happens.
+You've more or less learned the workflow for developing features for SS14 Git-wise, but here's are key points I'd really like to hammer home:
+- When creating a new feature, *always* create a new branch off of `master` before committing anything. If you accidentally commit your physics changes to your bike horn branch, you're not in for a fun time, but it is fixable.
+- **Never, ever commit RobustToolbox or any submodules like Lidgren.Network** unless you have absolute confidence you know what you're doing. In the top-level local repository, these submodules are considered 'files', so it's easy to accidentally stage and commit them. Do not do this. See below for how to fix your mistakes if it happens.
- If you need further help with Git, feel free to ask in the SS14 Discord in #howdoicode.
## 2. A quick example workflow
-To get everything in your head and to summarize it all, here's an example workflow for making several pull requests using Git Bash commands.
+To get everything nicely lined up and to summarize it all, here's an example workflow for making several pull requests using Git Bash commands.
```python
git checkout master # Before we create a new branch, we should be on master.
@@ -647,7 +647,7 @@ Just for reference, here's a little glossary of Git concepts and terms explained
- **'Pull requests'** are a GitHub-specific action that allow you to request that your local branch and all of its changes is merged into another repository's branch.
- **'Pushing'** is the act of integrating your local changes into a remote repository.
-There are way more commands and concepts than this, but this is all you *really* need to know for basic development work.
+There are way more commands and concepts than this, but this will serve as the core you need to know for basic development work.
# Appendix A: Helpful tips and tricks
@@ -656,18 +656,16 @@ There's some stuff I didn't cover, but you'll almost inevitably have to do at so
One note since it comes up a lot here: **`HEAD` is a fancy name for the commit that you're currently on**. Nothing more than that. Branches are also technically fancy names for commits, but you don't need to know that yet.
-A lot of these can be found probably more eloquently in Oh Shit, Git?! (see resources above)
+A lot of these can be found probably more eloquently in the resources at the top of the page.
## Resolving merge conflicts
-*WIP i'll write a better guide for this later because it's important*
-
-A nasty little maintainer has told you to 'resolve conflicts' or your PR 'wont be merged'. What an asshole! Thankfully, it's not too hard.
+A nasty little maintainer has told you to 'resolve conflicts' or your PR 'wont be merged'. Uh oh! Thankfully, it's not too hard.
First, you're going to want to update your local `master branch`. See above for how to do that.
-When you run `git merge master [local branch]`, it'll either do it cleanly (woohoo) or tell you you have to resolve conflicts (wahhhh).
+When you run `git merge master [local branch]`, it'll either do it cleanly or tell you you have to resolve conflicts.
All you need to do to resolve conflicts manually is go into the files that are conflicting, remove all the `>>>>HEAD` and `===== <<<
Date: Thu, 2 Nov 2023 18:12:42 -0400
Subject: [PATCH 5/5] Update git-for-the-ss14-developer.md
Brief conclusion added.
---
.../general-development/setup/git-for-the-ss14-developer.md | 4 ++++
1 file changed, 4 insertions(+)
diff --git a/src/en/general-development/setup/git-for-the-ss14-developer.md b/src/en/general-development/setup/git-for-the-ss14-developer.md
index 45aa95166..530453175 100644
--- a/src/en/general-development/setup/git-for-the-ss14-developer.md
+++ b/src/en/general-development/setup/git-for-the-ss14-developer.md
@@ -770,3 +770,7 @@ git checkout [username]/[branch name]
```
This also lets you make PRs to their remote branch, if you so desired.
+
+# Conclusion
+
+All in all, that should provide you with a solid starting foundation for Git so that you can start to make your own contributions to SS14! Feel free to to take a look at some of the linked resources for more advanced Git when you feel ready. Beyond that, feel free to reach out to the community for more help with Git and getting started coding in general. Good luck and have fun!