I’ve added the following text to the guide for 1st time modders. Please review and tell me if this makes any sense to you. I know how git
works, so it makes sense to me, but communication is tricky.
A brief introduction to git
and github
CDDA’s data and code files are stored in the cloud on github.com
using a version control system called git
.
A version control system is a program that keeps of a bunch of files and records changes to them. It can provide the text of the changes, send those changes to someone else, apply someone else’s changes, or revert the files to a previous version.
A repository or repo is the entirety of a program’s files and recorded changes. The CDDA primary repo is stored at https://github.com/CleverRaven/Cataclysm-DDA
and is sometimes called the “CleverRaven repo” or the “upstream repo”. You’ll need your own copy of the CleverRaven repo stored on your user account at github.com
. Creating your own copy of the repo is called “forking the repo” (as in a fork in the road). You can also clone
a repo, which means copying it from one location to another. You can clone your fork of the CleverRaven repo to copy it out of the cloud and onto your desktop machine or laptop. If you do that, the clone of your fork on your machine is the “local repo” and the copy of your fork on github.com
is the remote repo. You can also use github.com
's tools to make changes directly on your remote repo.
Each repo has one or more branches. A branch is a list of commits, where each commit is a set of changes to files that are all supposed to happen together. For instance, if you added a new item in JSON, there would be a change to the JSON file for the item’s definition, a change to another JSON file for the recipe to craft the item, and a change in another JSON file to add the item to the lists of items that spawn in the game. All three changes would be grouped together in a single commit. Each branch is independent of every other branch. You can add commits to one branch without changing any other branch.
By tradition, the master
branch is the standard release branch for each repo. You should never add code directly to your master
branch, but instead it should always be an exact copy of the master
branch of the CleverRaven repo. Instead, you should create a new branch for each feature you want to add.
The branch you are currently working on contains the “working set” of your repo, which is just the changes you are currently working on. You can check out
branches, which causes git
to replace your current working set with the changes from the new branch. By committing changes and then changing branches, you can work on different projects at once without needing to clone the entire repo again.
When you are happy with all the commits you want to make for a branch in your local repo, you can “push” those changes to your remote repo, storing them on github.com
. When your changes are in your remote repo, you can open a “pull request” or “PR” against the CleverRaven repo, which is a request to add those changes to the CleverRaven repo’s master branch. One of the maintainers will review your PR and eventually “merge” it into the CleverRaven repo’s master branch, at which point your changes will become part of CDDA.