03-10-2016, 01:23 PM (This post was last modified: 03-10-2016, 01:24 PM by Marquesas. Edited 1 time in total.)
In order to make this go as smooth as possible, we'd like to have admissible git patches.
The simplest way for someone new to version control to create a git patch is as follows:
- Register on https://github.com
- Fork https://github.com/goonstation/goonstation-2016 into your account by pressing the Fork button in the top right. You should note that now the URL changed to https://github.com/<your_account_name>/goonstation-2016
- Create a new branch from master. To do this, click the Branches button in the top left of the source files and ensure that master is selected. Then type a branch name (eg. 'some-dumb-feature') into the branch name box and click the Create Branch button. You should note that the branch dropdown box now says Branch: some-dumb-feature. This is where you should place your work.
- The easiest way you can modify code is by opening a file and pressing the pencil (edit) button in the top right. Always ensure that you are working into the branch that you previously created. You can verify this by scrolling to the button and checking the name next to the 'Commit directly to the branch-name branch' radio button.
- When you are done editing a file, make sure that 'Commit directly to the branch-name branch' is selected at the bottom and type any message into the first box.
- In order to test changes that you did on this branch, you can use the Download ZIP button in the file browser on the top right (make sure the appropriate branch is selected in the branch dropdown box) to download the revision.
- When you believe you're done, press the New Pull Request button. This will take you to a new screen. Here, there will be either two or four dropdown boxes. If there are two boxes, click the Compare across forks link at the top. If there are four boxes, you are okay. The base fork selected should be 'goonstation/goonstation-2016'. The base that should be selected is master. The head fork that should be selected is '<your-account-name>/goonstation-2016'. The head that should be selected is '<your-branch-name>'. If all four boxes show the correct selection, copy the URL and append it to the end of your patch post.
If you do this, you give us an easy and painless way to merge your changes into our repository.
03-22-2018, 10:29 AM (This post was last modified: 02-21-2023, 04:41 PM by Mordent. Edited 3 times in total.
Edit Reason: Removing some PII
)
Going to put this here, as penance for spending a bunch of time writing it up for one player when he'd already done the right thing. Below is some information that should help you work on a patch locally (i.e. on your own machine) with a Git command-line tool.
While you're still going to need to fork the main repository on GitHub to do your changes, you may well want to use an actual command-line interface for some of the Git work, or if you get your repository in a bit of a weird state. You'll need a command line that supports `git`; my go-to is Git-Bash, but Windows Powershell, Cmndr, or others will work. All of the below assumes you're working on Windows 10, some things might be a tiny bit different if using a different OS.
Open up your command-line-that-supports-git and navigate to where you want your code to be. You can do this via use of the `cd` command (change directory). `cd ..` means go up one, `cd directoryName` means go into that directory. Depending on which tool you're using, it's either `ls` or `dir` to see the contents of your current directory. If you picked Git Bash, you can open the terminal via your normal File Explorer's right-click ("Git Bash Here") to save you bouncing around trying to find it.
I've stuck spoiler tags around the rest of the stuff, so while it flows like a document as it's quite long you can drill down into one bit if you want.
Convention
Commands you should type into your command line will be presented like:
Code:
> git status
You should type in everything after the greater-than-sign, so in this case: git status.
Forking the Repository
Including this here for completeness, you still need to fork the public release repository to get your own version of it that you have permission to work on. This is achieved via the "Fork" button (top-rightish), which will create a copy of the repo (short for repository, for any other uses throughout this post) tied to your GitHub account that you can work on.
Still got your command line open? Great. Once you're in the directory you want to put the code, (and replacing the placeholder with your username) type:
Most command-line tools will recognise that you're in a git repository, so will tell you what branch you're on. This will default to "master". We don't want to be on master, as that branch is useless for our particular codebase. Let's go and get on to the correct branch.
Code:
> git checkout master
It's a mouthful, but the branch we want is that long name above. This is the most up-to-date branch that should include any small patches that have been released to make it work with later versions of BYOND.
Repository Review
I described a bunch of different repositories above (and will continue doing so below), so let's actually discuss those a bit.
local, working: these refer to the current copy you have on your machine, the one that you make changes to and test.
These three repositories can be in entirely different states.
Branch Review
Let's talk about branches! I'll be using the word a lot. The following is not a technical definition and misses a lot of key details, but should give you an idea of what you should care about.
Above we switched from the "master" branch to the "master" branch. Imagine a tree trunk. This is "master".
In our particular case, when the tree trunk reaches its end, a branch "master" comes off of it. If you followed that branch back down, you'd get all of the things that are on that branch, plus everything that's on "master" at the point where it joins (in our case, we join at the top of the tree trunk).
This is your polite reminder that the release repository is set up a bit differently from most. For our purposes, we only care about the "master" branch, we don't give a damn about "master" as it's useless to us. As far as we're concerned, our "tree trunk" is the "master" branch.
Let's say I want to work on a cool new feature. I could extend the "master" branch by putting my work at the end of it, but what if I want to go and work on a different feature? I can't (easily) go back down the branch to grow out of, which means I'd be working on top of the other completely unrelated feature I was working on earlier.
In some cases, this might not matter, but let's say you finish up your first feature and want to put it up in the Patches forum. You tell us to look at your branch, but it's got all of this other unrelated stuff in it! This is where branching comes in. We will treat "master" as an untouchable branch that acts as the foundation for any features we want to add. We add those features in separate branches, all sprouting from the end of "master". So let's do that.
Feature Branch
You have a cool feature idea, and because you read the "Branch Review" section above you know that you want to make a "feature branch" to put your changes on. So that we can understand our current state:
Code:
> git status
If we're not on the "master" branch, let's go there.
Code:
> git checkout master
We want to make a new branch here. For the sake of using non-placeholders, I'm going to pretend this is a real branch and call it "feature/erp-stuff". The convention here is to prefix new stuff with "feature/", and bug fixes with "bugfix/". If you're working on Goonstation code, those two categories should make up most everything you need to do a patch for. Example branch names: feature/erp-stuff, bugfix/cyborg-skins, feature/pathology-rework, bugfix/monkey-hair-sprite-positionining.
If you're working on something that would be suited for the Ideas subforum, it's probably a feature. If you're working on something in Bug Reports, it's probably a bugfix. Let's create our feature/erp-stuff branch.
Code:
> git checkout -b feature/erp-stuff
The "-b" bit here is a convenient shortcut on the "checkout" command to a) create a new branch with the name we give it, and b) then checkout that branch (rather than stay on our current branch). We're now on our feature/erp-stuff branch.
This is the point where you'd want to make your changes, test them out, and then come back to the next step.
Committing Changes
So you've made your changes, tested them, and want to now share your greatness.
Code:
> git status
In here will be a combination of changes to existing files, and a list of untracked files/directories, depending on whether you changed existing files or added new files. You will likely see a bunch of files that you don't remember changing, with names like goonstation.int, goonstation.dme, goonstation.rsc. These are built by Dream Maker while compiling your changes, and aren't (quite) part of what we want. Because of this, we probably want to manually "stage" our changes for a commit, rather than do them all.
Code:
> git add some/path/to/my/changed/file.dm
Repeat this for all of the files that are part of your change. If you don't see the file in the list but see the new directory you put it in, it's because git doesn't know about that directory yet so cant' check its contents. You can simply add the directory (the same way you did the file) and it will work out what new stuff is in there.
Code:
> git status
Just confirm that all of the files that you want included in your patch are in here in green. If they're not, go and add them. If you've accidentally included a file you didn't mean to, you can unstage it using the below:
Code:
> git reset HEAD some/path/to/incorrectly/added/file
Check the status again to make sure it's now in the state you want. If you're feeling particularly diligent, you can actually revert any changes to any files that you don't want to include, add the rest, then check it still works before committing.
Careful with this one, as you'll lose work if you accidentally pick the wrong file! Once you've done this, you should go and make sure your changes still work, then...
Code:
> git commit -m "Description of what I did here."
This adds a commit to the end of your feature branch containing all of your changes.
Pushing Changes
Your feature branch has a commit (or several) on the end of it that has your changes. This commit is, currently, only part of your local repository. We need to get these changes up to your forked ("origin") repository. Replacing with your relevant branch name, of course:
Code:
> git push origin feature/erp-stuff
You'll probably need to put some credentials in here, like your GitHub username and password. There are a few ways of simplifying this, I'm not going over it right now.
Once that command completes, check your fork. Navigate to https://github.com/yourGitHubUsername/go.../erp-stuff (replacing with your branch name) and see if your commits are there. If so, great. If not... come bug me on #imcoder.
Switching Branches
So let's say you're on your feature branch, and you've had this great idea for a quick change to something else. You can't put it on your current feature branch, because it'll be wrapped in with all of your current changes. The "best" way of dealing with this is to commit your current changes, then go back to the master branch, then create your new feature branch from that. You can then switch between the two.
When switching branches, it's a good idea to see what your current state is.
Code:
> git status
If you have changes you want to keep, make sure to commit them (follow the steps above).
Now let's get back to our main branch.
Code:
> git checkout master
From here, we can create our new feature branch.
Code:
> git checkout -b feature/make-me-an-admin
We can make changes to this new idea, commit them, then go back to the branch we were working on.
Code:
> git checkout feature/erp-stuff
Undo Changes to master
If you've committed changes to your master branch, not all is lost. Firstly, let's make sure we keep those changes (assuming you want to).
We can push that branch (see Pushing Changes) or keep it to later work on. Now we need to go fix up our master branch and get it back to where it was.
Code:
>git checkout master
The above is important, as this is the branch that we will be resetting. If you've not pushed the changes to your master branch to your forked repository yet, you can reset your local repo to the state of your forked one.
If you instead have already pushed your incorrect commit, you can go get the state from the upstream repository (the public release, not your fork) instead.
The last line here pushes up your (now reset) master branch to your forked repository. It's important that you use the --force bit, as otherwise it won't accept it as your forked repository thinks it's more up-to-date.
Goonhub
