Author Topic: Using Git and Github to contribute  (Read 15133 times)

Offline Soron

  • Code Wrangler
  • Survivor
  • *****
  • Posts: 480
    • View Profile
Using Git and Github to contribute
« on: April 27, 2013, 09:20:33 AM »
We use git and Github to manage changes to Cataclysm: DDA. Why? Because it makes it simple and easy to coordinate dozens of separate contributors all sending in patches for the same chunks of code.

Github is a site that stores our code for people to access, and also has a number of tools to assist us. Git is the actual tool itself, the bit that does the low-level file tracking and such.

However, not everyone knows how to use git, and there are a few minor gotchas that can make things messy. So, I'm hoping to provide enough instruction for people to be able to use git well, in the case of Cataclysm: DDA. The instructions will resemble the Github tutorial to some degree, albeit reordered and customized for Cataclysm: DDA.

This also assumes that you're comfortable with command lines, because git's origins are in the command line. If someone can get good GUI instructions for Windows users, that would be very much appreciated.



Forking the official repository

(click to show/hide)

Setting up git to track your fork

(click to show/hide)

Making changes

(click to show/hide)

Submitting your changes

(click to show/hide)

Grabbing new official changes

(click to show/hide)



Summary of the edit-submit-update-edit cycle:

Once you've gone through all those steps once, and configured everything, the general workflow is as follows.

Grab latest changes, on a clean master branch:
Code: [Select]
git checkout master
git pull upstream master

Make a new branch for some new changes:
Code: [Select]
git branch some-new-branch
git checkout some-new-branch

Edit code. Then, commit it:
Code: [Select]
git commit .
Push it to your Github fork:
Code: [Select]
git push -u origin some-new-branch

Submit a pull request, so that people are aware of your changes.

Go back to step #1 :).




Q: Do I need to use git?

If you're a programmer: almost certainly yes. Changes to the game's code can be messy, sometimes very messy, and it seems to be assumed that if you're capable of writing code, you're capable of learning how to use a version control system such as git.

If you're just modding data files: possibly not, because

In any case: the project maintainers are generally busy, and need to make effective use of their available time. The easier you make it for them to include your submission, the more likely your submission will be accepted. Using git to submit things makes it easier. So, use git, if you can.



I hope that was helpful!

EDIT: Kevin Granade: For further info, the Github help pages are EXTREMELY... helpful.
EDIT2: Kevin Granade: We use the GitHub Flow model of contributing.
« Last Edit: June 27, 2015, 08:04:49 PM by Kevin Granade »

Offline wad67

  • Survivor
  • ***
  • Posts: 356
    • View Profile
Re: Using Git and Github to contribute
« Reply #1 on: May 03, 2013, 07:25:48 AM »
Nice work Soron, Its good to know someone is making an effort in teaching us all the intricacies of version control.
Lets hope future contributors will find it easier to adjust to git-hub.

Offline uzername

  • Zombie Food
  • *
  • Posts: 74
    • View Profile
Re: Using Git and Github to contribute
« Reply #2 on: May 03, 2013, 09:10:27 AM »
Awesome thread! I have used this manual from github to learn git basics:
https://help.github.com/articles/fork-a-repo
I use such set of commands to get the latest version of Cataclysm:
Code: [Select]
git fetch upstream
git merge upstream master
What is the difference from
Code: [Select]
git pull upstream master
I heard that it is possible to revert your branch state to any commit you've made before. Is it so?

Offline Soron

  • Code Wrangler
  • Survivor
  • *****
  • Posts: 480
    • View Profile
Re: Using Git and Github to contribute
« Reply #3 on: May 03, 2013, 09:40:20 AM »
To the best of my knowledge, "git pull" just grabs the latest version of that particular remote branch and merges it into your current working branch. "git fetch" checks the remote repository, and updates a local copy of that repository with information about the various branches it has.

If you're only ever grabbing the upstream changes from the master branch, it's probably fine to just use git pull. If you start doing more complex stuff, it might be a good idea to get used to using fetch/merge instead.

It IS indeed possible to revert to previous commits, or grab previous commits and examine them. Use "git checkout hash" to checkout a particular commit based on its hash. If you want to keep that point, or continue work on it, you should then do "git branch some-branch" and then checkout that branch (if you checkout a commit by itself, and then do more work, it's easy for stuff to get lost in the ether).

If you want to actually revert to a previous, recent commit (e.g., if you screwed up), you probably want to use "git reset". To clear all current changes that you haven't committed, use "git reset --hard". To go back a certain number of commits but keep the changes in your working directory, use "git reset HEAD~n", where n is the number of commits that you want to undo. You can also combine the two, as "git reset --hard HEAD~n", which goes back n commits and wipes any changes that have happened since then. Obviously, use that one with care. Also, be careful about resetting changes that other people have grabbed (such as if you've submitted a pull request and had it approved) - it can make the history kinda gnarly.

There's also "git revert", which you can use if you want to undo the effects of a previous commit without removing it from the history.

What I've currently got up is meant as a beginner's guide, so I probably won't put potentially-dangerous stuff like "git reset --hard" in the same section of the OP. Once I get a feel for what kinds of stuff people want to see/need to know, I'll probably put it in a different section in the OP, or possibly in a different thread.

Offline vultures

  • Survivor
  • ***
  • Posts: 1645
  • Reticulating Splines.
    • View Profile
    • The Causeway
Re: Using Git and Github to contribute
« Reply #4 on: May 10, 2013, 02:06:31 PM »
I have found something very useful. It is a throughout guide written by a fellow countryman, Igor BaloŇ°.
He shows how easy it is to set up, use and contribute via msysgit

BeanStalk Guides - Working with Git on Windows
http://guides.beanstalkapp.com/version-control/git-on-windows.html

GoogleCode - up-to-date msysgit downloads
http://code.google.com/p/msysgit/downloads/list?q=full+installer+official+git

I believe that after one gets familiar with either PuTTy or SSH for win, can follow rest of the steps as Soron wrote them as msysgit respects the same old commands of UNIX origin.
"On Labor Day the vultures disappeared. Nobody could remember when they had not circled early dawn.  Death's falcons.  Turning miles above the arid northwest reaches of Tribeca tethered by scent."

The Absent Vultures of Tribeca
by Douglas Anthony Cooper

Offline utunnels

  • NPC
  • **
  • Posts: 166
    • View Profile
Re: Using Git and Github to contribute
« Reply #5 on: June 06, 2013, 10:18:21 AM »
I got one question.
Do I need to use a different directory for every new branch?
I see if I switch to another branch and pull, all files are changed to that branch.

Offline Soron

  • Code Wrangler
  • Survivor
  • *****
  • Posts: 480
    • View Profile
Re: Using Git and Github to contribute
« Reply #6 on: June 06, 2013, 10:55:20 AM »
Git branches can do some odd stuff if you're not expecting it, but you actually don't want to use separate directories for every branch. I think that works (and is even advised) for some version control systems, but with Git, it'll just confuse stuff.

What happens is that Git swaps out the files in-place when you change branches (or at least, all the *tracked* files). It keeps a record of all the differences it has to make in order to do that, and will restore the previous versions of those files when you switch back to your previous branch.

Offline utunnels

  • NPC
  • **
  • Posts: 166
    • View Profile
Re: Using Git and Github to contribute
« Reply #7 on: June 06, 2013, 12:43:32 PM »
Yeah, I see. Thank you.

Offline Shoes

  • Survivor
  • ***
  • Posts: 324
  • I maintain the body temperature mod.
    • View Profile
Re: Using Git and Github to contribute
« Reply #8 on: June 06, 2013, 01:19:37 PM »
I sometimes use

Code: [Select]
git pull upstream master:tinker-time
with the intent of pulling remote master into a new branch. However, whenever I do this, remote master also gets pulled into the current branch I am in. My work around is to create a dummy branch, pull, checkout to new branch, delete dummy branch. Is there an easier way to do this?

(I also can't think of an example as to why I do this... normally it's when I mess something up)

Offline Justice

  • Zombie Food
  • *
  • Posts: 89
  • Apostle of Light
    • View Profile
Re: Using Git and Github to contribute
« Reply #9 on: June 06, 2013, 01:51:09 PM »
I sometimes use

Code: [Select]
git pull upstream master:tinker-time
with the intent of pulling remote master into a new branch. However, whenever I do this, remote master also gets pulled into the current branch I am in. My work around is to create a dummy branch, pull, checkout to new branch, delete dummy branch. Is there an easier way to do this?

(I also can't think of an example as to why I do this... normally it's when I mess something up)

Lol, yea, git seems to get confused, possibly, because you didn't specify your local in your refspec.

Personally, I would use an alias to prevent accidents:

Code: [Select]
git config --global alias.nbwp '!sh -c "git branch $1 --track upstream/master && git checkout $1 && git pull"'
git nbwp tinker-time

nbwp = new branch with pull
« Last Edit: June 06, 2013, 02:32:50 PM by Justice »

Offline GlyphGryph

  • Administrator
  • Survivor
  • *****
  • Posts: 1488
  • Kreaaaaa
    • View Profile
Re: Using Git and Github to contribute
« Reply #10 on: June 06, 2013, 01:55:44 PM »
To the best of my knowledge, "git pull" just grabs the latest version of that particular remote branch and merges it into your current working branch. "git fetch" checks the remote repository, and updates a local copy of that repository with information about the various branches it has.

Although you can have multiple working directories hooked up to one git repo if you want multiple branches open at the same time, which I don't use for this project but I find invaluable at work. Git comes with the following script that will set that up for you:
git-new-workdir project-dir new-workdir branch

Offline utunnels

  • NPC
  • **
  • Posts: 166
    • View Profile
Re: Using Git and Github to contribute
« Reply #11 on: June 07, 2013, 01:18:27 AM »
Man, https it really slow here. I spent several hours last night to clone a repo but still failed at around 30mb.  :p

I'm using this instead on another PC and the speed seems normal (200kb/s).
git clone git@github.com:username/Cataclysm-DDA.git


--------------------

And it seems I'm having problem adding upstream.

git pull upstream master
fatal: 'upstream' does not appear to be a git repository

git remote add upstream git@github.com:CleverRaven/Cataclysm-DDA.git
fatal: remote upstream already exists.

I have to use this instead to change upstream url:
git remote set-url upstream git@github.com:CleverRaven/Cataclysm-DDA.git
« Last Edit: June 07, 2013, 01:24:28 AM by utunnels »

Offline KA101

  • Administrator
  • Survivor
  • *****
  • Posts: 6858
    • View Profile
Re: Using Git and Github to contribute
« Reply #12 on: June 11, 2013, 02:38:01 AM »
OK, just discovered that the browser-based & Windows Git clients don't automatically keep themselves updated.

Whoops.  X-(  What's the mainline-updating solution for someone who uses GUIs?

(Looked into the tutorial vultures posted, but it seemed full of how-to-SSH.  Not helpful for my problem, so far as I can tell.  Sorry.)

Offline Isylwin

  • Zombie Food
  • *
  • Posts: 20
    • View Profile
Re: Using Git and Github to contribute
« Reply #13 on: June 11, 2013, 04:24:50 PM »
Using Github app:

Github made an application for windows so you'd have a GUI instead of just a command prompt. So to make it easier for new people to use that GUI here's a little guide:


Setting up your Github, with Github application for Windows.
(click to show/hide)


Merging branches with Github
(click to show/hide)


Updating your repository with Github
(click to show/hide)



Any dev/moderator make take this text above this line and alter and copy it to their liking and if you place this on top of the post please spoiler or delete my whole post so it doesn't clog up the forum. If I find out more that's important I'll of course add it here. There's one important thing to note at the moment, as KA101 posted before me, Github app is a bit weird when it comes to updating. Specially because adding CleverRaven's git as an upstream results in error's (saying that the upstream exists). I'd like to work on this weirdness and see if there's a reliable workaround as I can't say for sure if anything works (though the replies here have great ideas/solutions)

I hope this could help some people out with github, as it is an awesome concept (and I've only discovered it yesterday) and also lower the wall for some people to start modding/contributing to this awesome awesome game. Furthermore I'd like to suggest something for The Lab (I know it's not the place to do suggestions like these but meh). A sticky saying that people should use Github if they want to help out (and link to this post ofcourse), so that people are aware that they should use github and not throw their changes into a .rar hehe. Also, I find, it's easy to not see the toolbox subforum so such a post could help some blind people see. I'd be happy to write it and pm it to an admin, just give me a call.

-Isy


(EDIT: I've added how you can update your repository and made the whole thing a little bit neater. Also, thanks to utunnels for the alternative way of setting your upstream, thanks man.
« Last Edit: June 12, 2013, 01:19:17 PM by Isylwin »

Offline EkarusRyndren

  • Survivor
  • ***
  • Posts: 2270
  • I will live forever because I am 45% preservative
    • View Profile
    • My Tumblr
Re: Using Git and Github to contribute
« Reply #14 on: November 16, 2013, 01:41:40 AM »
...So I went to lauch the merge whatever and... It seems like I broke it, all I did was change a few names from the cannibal expansion thing (I think?) and to my knowledge it should have merged fine?

...I don't really have the foggiest idea what I'm doing, I'm using some windows-launched program that the GitHub site has to do the merging, in the past it failed because of a typo in the json, but now the console output doesn't make any sense to me...

Code: [Select]
GitHub pull request #4371 of commit 5c4c9a85d5b0d7a5fbe1078434e0739e1e1600e1 automatically merged.
Building in workspace /var/lib/jenkins/jobs/Cataclysm-PullRequests/workspace

Deleting project workspace... done

Fetching changes from the remote Git repository
Fetching upstream changes from git://github.com/CleverRaven/Cataclysm-DDA.git
Checking out Revision bce1ad723c41429b3def1606ceeeac52745f4a18 (origin/pr/4371/merge)
Run condition [Boolean condition] enabling prebuild for step [Execute shell]
[Boolean condition] checking [true] against [^(1|y|yes|t|true|on|run)$] (origin token: ${CHECK_MAKEFILE})
Run condition [Boolean condition] enabling perform for step [Execute shell]
[workspace] $ /bin/sh -xe /tmp/hudson2840394629452856267.sh
+ diff -q /var/lib/jenkins/cataclysm-reference-repo/Makefile Makefile
Files /var/lib/jenkins/cataclysm-reference-repo/Makefile and Makefile differ
Build step 'Conditional step (single)' marked build as failure
Archiving artifacts
Finished: FAILURE

Can someone tell me what I did wrong? I just have the distinct feeling someone somewhere is going "Oh god fucking damn it Ekarus broke fucking everything.."
« Last Edit: November 16, 2013, 01:44:47 AM by EkarusRyndren »
But then deafness, yes. I forgot about deafness. It would be deafness with a :( face though.