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.
[hr]
[size=14pt]Forking the official repository[/size]
The first step is to fork the official repository. This allows you to post changes to Github, with a minimal degree of hassle. It’s also a very simple step.
All you have to do is navigate to the official repository, and hit the “fork” button in the top-right corner. If you don’t have a Github account, you should be prompted to create one.
Once that’s done, you should have your very own Cataclysm: DDA repository on Github, ready for you to tinker with!
[size=14pt]Setting up git to track your fork[/size]
The next step is to set up git on your local machine, and tell it about the fork you’ve just made.
First, install git. The details of that will depend on your system, so you may want to follow the Github tutorial’s directions. If you’re on Windows, it’s a good idea to make sure you have access to a git command prompt, so that the Linux-based devs (i.e., the majority of us) can actually help you when you have questions.
Once you’ve installed git, you’ll want to configure a few local settings. Run the following commands, replacing the text inside the strings (“Your Name”, etc.) as appropriate:
git config --global user.name "Your Name Here"
git config --global user.email "your_email@example.com"Mind you that the email should be one that Github knows about.
After that, navigate into the directory that you want to work in, and enter the following (again, replacing “YourUsername” as appropriate):
git clone https://github.com/YourUsername/Cataclysm-DDA.gitAnd you’re done! (although you’ll need to move into the new directory that’s created, most likely)
[size=14pt]Making changes[/size]
So, you’ve got your fork, and you’ve probably got some changes you want to submit. How do you do that?
First, make sure you’re on a clean, fresh branch:
git checkout master
git branch whatever-you-want
git checkout whatever-you-wantObviously, you can replace “whatever-you-want” with… well, whatever you want. You should now be on a new branch, with a name of your choosing. If you want to switch branches, use the “git checkout” command again. It is highly advised that you do not make local changes to the master branch, because it makes it harder to get clean commit histories.
At this point, you Make some edits, and save the modified files. Once you’ve got a working set of changes, you’ll want to commit them. To commit all the modified files in the current directory (make sure you don’t have any extraneous modifications), run the following:
git commit .You’ll probably be prompted (somehow) for a commit message. Try to write a good, succinct summary. If you’ve added files, however, you’ll have to tell git you want to track them first. To do so, use the “git add” command. For instance, if you’ve made a bunch of changes AND added foo.h, foo.cpp, and bar.cpp:
git add foo.h foo.cpp bar.cpp
git commit .There’s also a way to have “git add” automatically add all files in the current directory to the project. However, before running that, be sure that you don’t have any user-specific junk files in your working directory. For example, temporary build files, or executables. Due to the risk of accidentally adding large files to the repository, I won’t put that command in this tutorial - better to read the docs.
[size=14pt]Submitting your changes[/size]
Once you’ve made one or more commits that you’re happy with, you’ll probably want to submit them for potential inclusion in the official Cataclysm: DDA repository. First, we need to get those changes pushed to Github, which we do with the “git push” command. First, make sure you’re on the branch with your changes (remember, use “git checkout”). Let’s assume you’re on the branch named “whatever-you-want”. To push your changes to your fork on Github, run the following command:
Now your changes should be on Github. In order to get it seen by the project maintainers, you need to submit a pull request.
In order to submit a pull request, go to your fork on Github. There should be a button near the top-right of the page that says “Pull request”. Click on it, and select the branch that has the changes you want to submit. Type a suitable message in the boxes, and hit the send button. You’ve just submitted a pull request, and the project maintainers should take a look at it when they’re next available.
[size=14pt]Grabbing new official changes[/size]
Sooner or later, you’ll want to update your local files to match the current official version. Probably sooner, if the current development pace is maintained. First, you should configure your local copy of git so that it knows about the official repository. Run the following:
The word “upstream” can be replaced with whatever you want, although “upstream” is a common choice.
Now, whenever you want to pull in changes from the official repository, run the following command:
[hr]
[size=14pt]Summary of the edit-submit-update-edit cycle:[/size]
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:
git checkout master
git pull upstream masterMake a new branch for some new changes:
git branch some-new-branch
git checkout some-new-branchEdit code. Then, commit it:
Push it to your Github fork:
Submit a pull request, so that people are aware of your changes.
Go back to step #1 :).
[hr]
[size=14pt]Q: Do I need to use git?[/size]
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.
[hr]
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.
[/URL]
[/URL]
Maybe it was a screw-up on my part after all.