Branch Structure

Our project has a number of branches. We have three main branches (dev, stable, and beta), the special base branch master, numerous feature branches, some archival branches, and some miscellaneous branches. The archival and miscellaneous branch types aren't important for most of us; the main branches are very important but of them only dev will be used directly by most users; and the submission and feature branches are important for just about everyone submitting code to Github.

#Philosophy Incomplete features should have their own branch. Features that will be ready for release if they are successfully tested by the team should be merged into the dev branch. Admins will merge features that have completed pre-release testing into beta or stable as appropriate (generally stable). The master branch is kept at code that we are reasonably confident will stay in the mod in the next release, which generally means a few commits after the most recent release.

#The Base Branch master The master branch is what you start with when adding brand new features. If your code creates a new feature, you should create a new branch from this branch while working on it. If you are adding multiple features, please code them in separate branches and submit these branches through separate pull requests or merge them into dev separately; this makes it easier to merge features that have finished testing without merging insufficiently tested features.

#The Feature Branches Features should have their own branches until they are completed. Once complete, we usually don't bother keeping their branches up to date, and any small changes are made directly to dev. More complicated changes (of more than 3 or 4 commits) are made to the feature branch and then merged into dev when complete.

#The Main Branches There are three main branches.

The stable branch contains the code we plan on releasing as our next "stable" version of the mod on Steam. It should contain code that is ready to go live on Steam.

The beta branch contains the code we plan on releasing as our next "beta" version of the mod on the Paradox forums. It should contain code that is ready to go live for beta testing by forum users of our mod. Due to lack of interest we are not currently doing beta releases, and so the beta branch is deprecated.

The dev branch contains the code we plan on testing in our developers' games. If the code is ready to show up in multiplayer games we play with each other it should go in this branch, as should code that is ready to go into the games our testers play.

Pull requests should submitted to either the dev branch or an appropriate feature branch. (It is preferable to create a new branch from master rather than submitting a pull request to master if you want a new branch.)

#The Archival Branches The archival branches mark which code we have previously released, e.g. v1.4.1 is an archival branch. These branches should not be changed. Some of these are maintained as tags rather than branches.

#The Miscellaneous Branches There are a few additional branches that serve various purposes. If you have a miscellaneous branch with more than a few commits, consider whether some or all of its code could be merged into a feature branch (the answer might be no, but you should consider it).