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
CDDA’s data and code files are stored in the cloud on
github.com using a version control system called
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.