Skip to content

Development with GitHub

Jump to bottom
questionmarkexclamationpoint edited this page Nov 12, 2019 · 19 revisions

Branches

Branches on GitHub are the heart and soul of our workflow.

Main branches

These are our mainline, shared branches. No direct commits should be made to these branches. Instead, any work should be done in a feature or fix branch and merged into the appropriate mainline branch through a pull request, as explained below.

Alpha

This is our main branch scheme before we make a release. This will change slightly once we make our first release, as seen below. This section will be removed when that happens.

  • master: This is our mainline branch. All feature and fix branches should be based on this, and any pull requests from a feature branch or fix branch should target this branch.

After the First Release

  • master: This is known good code, fit for a release. Any code in here should have been tested to the point that we feel it's ready for showtime. Any hotfix branches should be based on this branch, and their pull requests should target this branch.
  • develop-minor: This branch contains new features which we know won't break save games. Any non-savegame breaking features should be based on this branch, and their pull requests should target this branch. This branch is based on master, and should be kept up to date with master, as explained below in Releases.
  • develop-major: This branch contains new features and fixes which will break save games. Any savegame breaking features or fixes should be based on this branch, and their pull requests should target this branch. This branch is based on develop-minor, and should be kept up to date with develop-minor, as explained below in Releases.

Feature and Fix Branches

These are branches for specific changes and fixes. This is where almost all of the work happens.

Any of these branches should have a well defined scope, and you should do your best not to deviate from that scope. If you'd like to make another, separate change, make another, separate branch for it. Only one person should be working on a given branch at any given time, with few exceptions.

Alpha note: You can drop in master for any mention of a develop branch while we are in the alpha stage mentioned above. At this stage, we don't have any develop branches, as we haven't released any known working code yet, so master is effectively our develop and master branch.

  • project-name/feature-name (for instance, cultures/french-cultures): These branches are for new features. They should be associated with a project, and typically also should have an associated issue. This is where new changes happen. Each of these branches should be based on develop-minor if it doesn't break savegames, or develop-major if it does, and their pull requests should target the same.
  • hotfix/name-of-the-bug (for instance, hotfix/wrong-norse-reformation-requirements): These are bugfixes which do not break savegames. These branches should be based on master, and their pull requests should target master.
  • fix/name-of-the-bug (for instance, fix/cultures-not-properly-set-up): These are bugfixes which will break savegames. These branches should be based on develop-major, and their pull requests should target the same.

To make a new branch, checkout the main branch you will be targeting, then checkout a new branch from there:

git checkout develop-major
git checkout -b culture/example-culture

A Short Note on Commits

Commits should be kept as atomic as possible. A large, sweeping change should not be made in a single commit. At the same time, you should not be committing at every single line change. Try to keep your commits well scoped to small chunks of related changes.

Pull Requests and Review

Because we have disabled direct commits to our mainline branches, all changes to these branches must be conducted through pull requests. Changes are easier to track this way, and you also get a second pair of eyes to look over your changes before they make it into a mainline branch.

Here is a decent overview of good pull request guidelines.

Making a pull request

When you feel that your change is ready to be merged into its base branch, push your code to GitHub on your branch, then navigate to the Pull Requests tab and make a new pull request. There, make sure you choose the right base branch (almost always the branch you based your branch off of when creating), and then choose your branch as the "compare" branch. With that done, you should start off your pull request:

  • Pick a reviewer you feel would be helpful from the right hand panel
  • Pick the appropriate project this change is associated with
  • Briefly explain the changes and link any associated issues in the opening comment

Then it's up to your reviewer to look at your changes.

Reviewing a Pull Request

Reviewing a pull request takes some care and diligence. Ultimately the onus is on the reviewer to ensure that everything about a change looks right before it gets merged.

When reviewing, take a look over all the changes and look for any issues or bugs in the change. Sometimes this is best done by testing the changes yourself, or downloading them to your local machine and looking at them there. Where you find issues or bugs, make a comment on the corresponding line explaining the issue. It is then up to the reviewee to make changes to rectify the issue and push those changes up to GitHub. When you feel that a particular comment chain has been resolved, mark it as such.

Finally, when you feel a change is ready to be merged, mark it as approved, merge it, then delete the branch. This can all be done right from the pull request page.

Note that, as a reviewer, you are essentially critiquing someone else's hard work. Please try to keep it a constructive criticism: congratulate people on cool changes; don't be too accusatory; remember that we are all trying to make the project better together.

Releases

Versioning

Our releases follow semantic versioning. That is, they will be of the format M.m[.p] (such as 1.2.3, or 2.4), where M is the Major version number, m is the minor version number, and p is the patch version number. Each number represents a different kind of change:

  • The Major version number represents any changes (fixes or new functionality) that are not backwards compatible; this number is always required in a new version
  • The minor version number represents new functionality (i.e. new features) that is backwards compatible; this number is always required in a new version
  • The patch version number represents fixes that are backwards compatible; the patch version is only required in a patch release

When bumping the version for a release, you should increment the appropriate number for the given release. Examples:

  • If the current version is 1.2.3 and you are releasing a patch, the new version should be 1.2.4
  • If the current version is 1.2 and you are releasing a patch, the new version should be 1.2.1
  • If the current version is 1.2.3 and you are releasing a minor update, the new version should be 1.3
  • If the current version is 1.2 and you are releasing a minor update, the new version should be 1.3
  • If the current version is 1.2.3 and you are releasing a major update, the new version should be 2.0
  • If the current version is 1.2 and you are releasing a major update, the new version should be 2.0

Making a release

When making a release, there are a number of things that have to be done:

  • Merge branches following the guide below according to the type of release you are making
  • Tag a new release with a version number following the semantic versioning outlined above
  • Attach the mod files to the newly created tag as a .zip file
  • Include a changelog with the tag on GitHub
  • Update the master changelog in the wiki on GitHub
  • Update the post on the Paradox Forums with the new release and info

Merging branches for a release

Patch

For a patch release:

Minor

For a minor release:

Major

For a major release:

Clone this wiki locally