As the MultiMC project grows and more people contribute to the project, we have found our previous ways of using Git to be inadequate to properly maintain the project any longer. As such, this document shall outline a standard workflow to be used by all contributors and maintainers when working on the project.
Definitions of words and terms used in this document.
The main MultiMC repository is the project's primary GitHub repository. It can be found (here)[https://github.com/MultiMC/MultiMC5]. The Buildbot for official builds uses this repository for builds.
A channel is a set of Buildbot builders that build code from a specific Git branch. Users may switch to different channels from within their MultiMC settings dialog. Two major examples of channels are the development and stable channels, which build from the develop and master git branches respectively.
The project has a couple different "ranks" of contributors. A person's rank is based on how well trusted they are and how much they have contributed.
A maintainer or developer (sometimes also called a major contributor) is someone who is one of the primary developers of MultiMC. These are people who are well trusted and are actively contributing to or maintaining the project. Maintainers have commit access to the main MultiMC repository, are part of the MultiMC organization on GitHub, and are usually operators in the IRC channel, although some only have voice.
A minor contributor is anyone who has contributed something to the MultiMC project. Contributors generally don't have commit access to the main repository and are expected to contribute by pushing their changes to their own forks and submitting a pull request to be reviewed by one of the project maintainers. Contributors usually have voice in the MultiMC IRC channel.
This section outlines the workflows for performing different maintenance tasks. These may be tasks such as patching a small bug or making a minor tweak, implementing a major feature, and more.
Overall, code changes fall into three main categories: major, minor, and direct. A major change is any major code change or feature addition. A minor change is a small code change, tweak, or small, simple feature. All major and minor changes should first be made on their own separate feature branch before being reviewed and merged into the development branch. A direct change works a bit differently that major and minor changes. A direct change is a change that is made directly to the develop branch and typically doesn't increment any version numer (except Buildbot's build number). Direct changes should be avoided and should only be made in the case of quick important fixes (like when Mojang breaks stuff). The processes for making these changes is outlined below.
All major changes should start on their own branch. This branch should be branched off from the development branch and its code should be kept up to date with changes on said branch. Major change branch names should be prefixed with major_, so if I were adding a major feature that automatically resolved ID conflicts (which will never ever happen because it's not possible), it would be named major_id-resolver.
Major change branches should be worked on until they are somewhat finished and stable. When the people working on the change decide that it is ready, they should have their changes reviewed by at least one maintainer. If said maintainer decides that the changes are OK, he or she may merge those changes into the development branch and increment the major version number. This should be done using the process described in the "merging changes" section below.
Minor changes work similarly to major changes above. They should start on their own branch, which should be branched off from the development branch and they should be kept up to date with the branch. Minor change branches should be named exactly like major change branches, except their names should be prefixed with minor_, rather than major_.
Minor change branches should be worked on until they are stable just like major changes. The only difference here is that when they are merged, they should increment the minor version number, rather than the major version number.
Direct changes are changes made directly to the develop or master branches. These should probably only be made by maintainers and should not be done unless they are absolutely necessary. The purpose of direct changes is to quickly fix important bugs that cause significant problems or completely break MultiMC. These may be used especially in the case of Mojang's sudden, unannounced, launcher-breaking changes. Direct changes should also increment the minor version number.
The following sections detail how different workflow tasks should be performed.
An initial change merge is the process of merging changes from a major or minor change branch into the development branch of MultiMC for the first time. This should only be done after at least one maintainer (preferably one who didn't worke on the change) has reveiwed the changes and determined them to be acceptable.
Change branches should not be merged if unit tests don't pass. This should go without saying, though.
To merge one or more changes (note that merging multiple changes at once should usually be discouraged), a maintainer should pull the change branches to their own branches on his or her local repository, checkout the develop branch, and run the following command to merge the change branches without committing: git merge --no-commit branch-to-merge. Next, he or she should increment the major or minor version number depending on what kind of change he or she is merging. Finally, he or she should add an entry to the changelog for the new version describing the changes that were made in the change branch or branches that he or she merged. Once this is done, he or she should commit the merge with a commit message stating that a change branch was merged, and describing the changes that were made in said branch. Finally, the changes can be pushed to the main repository's development branch where they will be compiled and tested by Buildbot.
A subsequent change merge is a done when changes are made to a change branch for a feature branch that has already been merged before. This should work exactly as initial change merging above, but it should be treated as a minor change regardless of what type of change it was before.
A stable merge is the process of merging changes from the development branch into the master branch. This should be done when the developers determine that features on the develop branch are stable enough. Before doing a stable merge, the changes should be reviewed by as many maintainers as possible (at least two should be the absolute minimum). A stable merge is done by merging the changes from the develop branch into the master branch. This should only be done when all the features on the development branch are determined to be stable.