Contributing to Lorekeeper

Lorekeeper, much like any project in its vein, thrives on community contributions; be they bugfixes, new features, extensions, or so on, these efforts are what help make the project shine. If you are interested in contributing to core Lorekeeper, pull requests (or PRs) are always open at the GitHub repository. If you have not already done so, a good first step is making a fork of the repository on your own account via the button on the upper right hand side of the page.

As a rule of thumb, we welcome PRs containing:

• Bugfixes (always!)
• Small features or quality-of-life additions
  • The rule of thumb for this is that the feature should relatively small in scale/compact, and either
    • Broadly useful to all users of Lorekeeper, or
    • Useful to most, but not all, users of Lorekeeper but wholly optional.
      • If your feature is compact enough to do so it is encouraged in this instance to create a toggle for it in config/lorekeeper/extensions that controls whether it is enabled or not.

General Architecture

Generally speaking, Lorekeeper and its branches are structured and maintained in keeping with GitFlow. Loosely, this means that there are two persistent branches:

• The default/primary branch-- master, in this case-- which always contains the current release/the current stable version, and
• The development branch-- develop, in this case-- which always contains the latest work-- features, fixes, and so on. It is by definition unstable.
  • This branch is itself off of master and in the infrequent but possible event that the latter is updated directly (i.e. via a hotfix), master will be merged into it.

As well as three types of branches; each branch of these types is destined to be merged into another and is important but ultimately impermanent:

• Feature branches
  • These follow the naming scheme feature/FEATURE-NAME-HERE, i.e. feature/two-factor-auth.
  • While these are called feature branches, they can contain new features and/or non-emergency bugfixes!
  • New features are always merged into develop and develop only.
  • These branches are created branched off of develop (if they contain features or there is no current release branch) or the current release branch (if there is one, and the feature branch contains only bugfixes for the current content within it).
• Release branches
  • These follow the naming scheme release/UPCOMING-VERSION-HERE.
  • These are created by a maintainer of the repo when an upcoming release is feature-complete or otherwise ready, and are branched off of develop.
  • Once they are created, no additional features or work from develop will be merged into these branches, only bugfixes for the features already in them.
  • Conversely, bugfixes for features contained in a release branch are merged directly into the release branch and the release branch only. In the event that a release branch receives bugfixes, said release branch is periodically merged back into develop to incorporate them.
  • In essence, the purpose of a release branch is to isolate, test, and if necessary fix a static set of features.
  • When a release branch is sufficiently stable and any necessary preparations complete, the branch will be merged into master and become the new current release.
• Hotfix branches
  • These follow the naming scheme hotfix/HOTFIX-NAME-HERE.
  • These contain emergency bugfixes, e.g. fixes for critical issues or security vulnerabilities.
  • These are directly branched off of master/the current release and merged back into master when complete.
  • In such an event, master is merged back into develop as well to incorporate fixes.

Branches and You

In summary:

• When contributing to Lorekeeper, you will create either a feature or (more rarely) a hotfix branch.
• If you are creating a new feature, it must be isolated in its own feature branch and a PRed into develop.
• If you are fixing bug(s), there are a few possibilities depending on the circumstances:
  • If there is currently a release branch, make a feature branch off of the release branch or check out the release branch itself.
    • Once you have done so, fix bug(s) with the current content of the release branch, then push the branch to your fork and make a PR to the release branch.
    • Prioritize fixing bugs in the release branch first and foremost. This allows the branch to better achieve stability and move toward full release.
  • If there is not currently a release branch, or if your fix(es) concern content that is only present in develop, make a feature branch off of develop or check out develop itself.
    • Alternately put: do not PR bugfixes that apply to an extant release branch to develop. Isolate them from any changes relevant only to develop on a branch created from the release branch and PR them to the release branch. This helps the release branch achieve stability and move toward full release.
  • As a general rule, making feature branches for bugfixes vs. checking out develop or the release branch and committing them directly is recommended, but not required, as you will need to push the relevant branch to your fork and make a PR regardless.
  • If you are making a hotfix for a critical issue present in the current release, create a new hotfix branch off of master, make the necessary changes, and PR it back into master.

Making a Pull Request

Once you have made your branch and your feature or fixes,