Skip to content

Development with GitHub

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

Table of Contents

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 at time of release, 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 at time of release, 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 typically be associated with a project, and also should typically have an associated issue. This is where new changes happen. Each of these branches should either be based on develop-minor or develop-major; one of these branches should be based on develop-minor if it doesn't break savegames, and develop-major if it does. These branches' pull requests should target the same branch they are based on.
  • 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 develop-major.

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

git checkout BASE-BRANCH
git checkout -b culture/example-culture

Where BASE-BRANCH is the branch you will be targeting for this change.

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.

Handling Merge Conflicts

First, it's recommended you turn on diff3 for merge conflicts.

If you work long enough on a team of any size on a project in git, you will eventually run into a merge conflict. A merge conflict happens when changes on two different branches affect the same area in the same file. Unless you are rebasing all the time on your branch, you will likely first be informed of a merge conflict on your pull request page, and GitHub won't allow your change to be merged unless the conflict is resolved. When this happens, it's usually easiest to solve on your local setup.

To fix this, perform a pull with rebase on your local machine:

git pull origin BASE-BRANCH --rebase

Where BASE-BRANCH is the branch you are basing your change off of (typically one of develop-major, develop-minor, or master). Or, if you are using a GUI-based git interface, perform the equivalent using that application. Git will take all of your changes and apply them, one by one, onto the latest version of the branch you are rebasing onto (the BASE-BRANCH). At least one of these commits will create a merge conflict. When this happens, git will pause at this commit and allow you to fix the conflict before proceeding with the application of the rest of the commits. If you run git status, you can see which files are causing the conflict. When you open these files, you will see something like the following:

<<<<<<< HEAD
GreenMessage.send(include_signature: true)
||||||| merged common ancestor
BlueMessage.send(include_signature: true)
=======
BlueMessage.send(include_signature: false)
>>>>>>> merged-branch

This may look confusing at first, but what it's conveying to you is fairly simple:

  • The code between <<<<<<< and ||||||| are the changes on your local branch
  • The code between ||||||| and ======= are the most recent common ancestor of the changes in your branch and the changes in the base branch
  • The code between ======= and >>>>>>> are the changes from the base branch you are rebasing onto

To solve this conflict, you will have to replace this with a combined version of both changes. So, using the changes you've made and the changes in the base branch, you will have to determine how to combine both changes in a sensible way.

In this case, the solution is quite simple; you would replace all of this text with:

GreenMessage.send(include_signature: false)

This combines the changes from your branch and the base branch.

When you've resolved the conflict, you can add the resolved files (git add path/to/the/file) and continue the rebase (git rebase --continue). You may run into other conflicts on the way. If these happen, resolve in the same way.

Not all conflicts are as simple as the above example, however; some will take some diligence to solve. However, the benefits of everyone being able to work on the same files at the same time are worth these rare occurrences.

If you ever run into a very nasty merge conflict, or just want a better graphical interface for dealing with conflicts, one great tool to resolve them is called Meld, which has releases for all three major desktop operating systems.

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

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 below
  • Attach the mod files to the newly created tag as a .zip file
    • You should only include CK2Plus, CK2Plus.mod, CK2Plus_extended, and CK2Plus_extended.mod in the .zip
  • Include a changelog with the tag on GitHub
  • Include the target checksum, the checksum with just CK2Plus enabled, and the checksum with CK2Plus and CK2Plus_expanded enabled on the tag
  • Update the master changelog
  • Update the post on the Paradox Forums with the new release and info

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 updating 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

Merging Branches for a Release

With each release, some amount of merging will be necessary to keep our branches up to date with one another. You can follow along with the appropriate guide below for the type of release you are making by simply clicking on the links.

Patch

For a patch release:

Minor

For a minor release:

Major

For a major release:

Clone this wiki locally