How do I get patches to github?

[Laie]

First, where I'm coming from: I'm a resonably experienced Linux admin. My current experience with git and patch will handsomely fit on a teaspoon, and diff is a tool to compare configuration files. Still, I don't expect to run into any problems with the tools. What I don't know is the whole process, what I need to do. Basically, I change stuff on my end, then let git do it's magic which eventually leads to patches being uploaded to the repo. The maintainer then decides whether he merges them or not. Is this correct so far?

From what I read, it seems that I need a github account and fork things there before I can start commiting patches. Is this so or is there a more direct route?

More generally, what's best practice for maintaining stuff on my end? Is it a good idea to tamper with things in my own Gameplay folder (I need to try them first anyway) and directly commit from there?

And... does the nature of my questions imply that I'm missing something important?

[Yski]

Right, let's see how well I can explain this. Before we begin, I should probably add that I don't claim to be an expert, so if you disagree with something I said, it's entirely possible I'm wrong.

After writing this, I realize it's a bit of a wall of text, so I added quick TL;DR bullet points to the beginning, if that's all you were looking for. You'll find a more detailed explanation below, and feel free to ask if something's still unclear.

Let's assume you want to fix a bug on mod X.

• Fork it. That's your own version of the mod you can make the changes on, before sending a pull request so that they can be added to the original.
  
• Clone the fork to your computer.
  
• Make a new branch for the fix.
  
• Every time you change something, make a new commit.
  
• Push the changes from your computer to your fork.
  
• Send a pull request to merge the changes you made on your fork on the new branch to the original repository.
  
• It's now up to the modder whether they accept your changes or not.
  

First you'll need to fork it on your GitHub account. What this basically means is, you need to have your own version of mod X on GitHub where you do the changes, before you send a pull request to ask the original modder to make those changes part of the official repository. I imagine the idea is that you can branch away from the original if need be without making things messy, but thanks to the shared history it's easy enough to merge changes as well.

Once you have your repository on GitHub, it's time to clone it on your computer. Copy the clone URL on the right of your fork, then use

git clone url/to/fork.git

to make your local version.

By default your local copy only knows where to find the fork you cloned it from. You'll probably want to update your fork when the original mod gets updated, so it's worth telling it where to find the original repository as well. Use

git remote -v

to see existing remotes (=repositories on GitHub), and

git remote add name URL

to add new ones. In this case, the URL you'd want is the clone URL for the original repository you forked.

While you're at it, if it's your first time using git on that computer, set up your user name and email so that they show up correctly on your commits.

git config --global user.email "yourEmail@email_place.com"

git config --global user.name "Your user name"

Now, to the interesting stuff. The way git works is that everything you work on should have its own branch, so that it's sort of isolated from everything else that's going on. It's especially important when you want to contribute more than one change on someone else's project - pull requests ask them to merge all the changes made on that branch, and if you made all your changes on the same branch, they'll either have to accept or deny all of them instead of being able to choose which ones they actually want.

In case you find branches difficult to understand, think of them as alternate universe versions of you code. No changes made in one branch affect the others until you merge them back together again. When you hop between branches, git replaces all the files with their correct "alternate universe" versions, then switches them back again when you return to the original branch.

To create a new branch, use

git checkout -b branchName

To switch to branch branchName, use

git checkout branchName

To see a list of all your branches, use

git branch

To merge changes made on branchName to the current branch, use

git merge branchName

That little bug you were planning to fix on X? You'd want to make a new branch for it. Now, if you are safely on your new bug fix branch, it's time to do the actual coding. But first, let's talk about commits.

Every time you change something, you should make a new commit, so that you can easily keep track of what changed and when, as well as revert those changes if need be. It's the same rule of thumb as with functions: your commit message should tell exactly what you changed, and if you had to use an "and", it should probably be two separate commits.

So, once you've made your changes and saved them, use either

or
git add fileName

git add -i

to stage the files, in other words add them to be committed. If you just give git a file to add, it'll add all the changes to that file. Add -i on the other hand lets you pick files as well as specific chunks of code you changed that you want to stage, so that's what I'd recommend you use. If you accidentally added something you didn't mean to, use

git reset fileName

to un-add it.

Once that's done, use

git commit -m "Your commit message."

to commit your changes. You can then use

git log

to see your commits, and

git diff

to see what changed between them.

Once you've made and committed all the changes you want, it's time to push them to your repository. That just means you upload your changes to GitHub. When pushing from a new branch for the first time, go to that branch and use

git push -u origin branchName

It tells git to push changes on branchName to where the repository was cloned from, in other words your fork on GitHub, as well as to push there by default from now on. After that just

git push

will do the trick.

If you need to do the opposite and pull changes from GitHub, use

git pull remoteName branchName

,where remoteName is one of those remote repositories I had you tell Git about earlier. By default, origin points to the GitHub repository you cloned your local copy from. branchName is the branch you wish to update. Note that it'll only pull the changes made to that branch on the GitHub repo.

Now it's time to send a pull request. Go to the branch you want to merge to the official version on your GitHub repository, and make a pull request. Explain what you changed and why, and wait until the requests gets accepted. Once that's done, you can safely delete the branch.

Oh, and as for the second question, it's probably best to keep the project and your GameData folder separate. I'd just copy the relevant files to GameData as need be, feels more organized.

Edited September 12, 2015 by Yski

[NathanKell]

Personally I make a symlink from, say, (repo for RP-0)/GameData/RP-0 to KSP/GameData/RP-0, so changes appear in GameData but the excess repo stuff does not.

Note that RP-0, and perhaps some other mods but RP-0 seems most relevant has a build script. Run make from the repo root if you change tree.yml any; that will generate the (git-ignored) Tree.cfg that actually is used by KSP.

Also worth mentioning that most mods don't include built dlls in their repos, so you may have to build from source, depending on what you want to do (for my stuff, RO, RSS, and most others do have dlls in git, but RealFuels does not).

Oh! Almost forgot. There is an easier way for making small changes.

Open the target repo in your web browser, and be logged into your Github account. Browse to the file you want to edit. Click the pencil icon (upper right corner of the file display) and you can make changes in the web editor.

When done, type in a commit message (and, if >30char, an extended commit message in the big box below). Then click "Suggest Change". Then keep click the green boxes to actually make a pull request (there's at least one more, on the next screen; there might be a third, I don't recall).

If you want to add more changes to that PR, open *your* fork of the repo (that was just created by the steps above) and go to the branch that has the changes (patch-1 if it's the first time, else patch-something). Then edit the files same as above, but choose "commit directly" when committing. Your PR will automatically update.

Edited September 12, 2015 by NathanKell

[Yski]

Oh! Almost forgot. There is an easier way for making small changes.

Nice, I didn't know that one. Learned something new today