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.git
And 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-want
Obviously, 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 master
Make a new branch for some new changes:
git branch some-new-branch
git checkout some-new-branch
Edit 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.
