Policies

Intro

The Mâché repo will strictly adhere to these rules in terms of how branching is managed, how versions are released, and how branches are updated.

Branch Names

The primary branch will always be the current release version. This mean the primary branch will always match the pattern ver\/\d+.\d+(:?\.\d+)?.

Snapshots will use the branch name format snap/<version>, and all other versions (including pre-release and release candidate versions) will use the branch name format ver/<version>.

Branch and version name agreement

Each branch will only host a single version in the versions/ directory. Each of the following 3 version names (represented as <version_name>) must all match exactly for all branches and all versions:

1. The name of the branch: ver/<version_name> or snap/<version_name>
2. The name of the version directory: versions/<version_name>/
3. The MC version set in the versions/<version_name>/build.gradle.kts:

   mache {
       minecraftVersion = "<version_name>"
   }

Branching Strategy

Branches should maintain linear history when possible:

• PRs should never be merged with merge commits, to maintain linear history.
• The only exception to this rule is when applying a build-system change to all currently supported versions.

This means merges will only happen in the "upward" direction - that is, from branches for older versions into branches for newer versions. This is only to apply changes to things such as the Gradle build config, GitHub Actions config, readme, etc.

Any changes to the version build definition itself (either the patches in versions/<ver>/patches or versions/<ver>/build.gradle.kts must only ever be made as independent commits to their individual branches.

Creating a new branch

The Mâché tooling provides some automation for the process of handling new versions to make this process simpler, but there are still some necessary requirements. On a new Minecraft snapshot or version release, the following process must be followed:

1. The current latest version is used as the base branch. This refers to whichever version is closest to the newly release version, whether it's the previous release version, a snapshot version, or a pre-release version.
2. A new branch is created using the branching name rules discussed above.
3. The migrate command is run to migrate from the old version to the new:

   ./gradlew migrate --from=<old_version> --to=<new_version>
   # For example:
   ./gradlew migrate --from=1.20.1 --to=23w31a

   1. The --from= version must be the current version associated with the current branch.
   2. The --to= version must be the exact name of the newly release Minecraft version.
4. The build config changes in versions/<new_version>/build.gradle.kts should be updated accordingly if there are new mappings available.
5. The patches should be applied with ./gradlew setup and any patch failures should be fixed.

It is acceptable to commit and push the new branch as-is after step 3, to allow the patches to be fixed at a later time, if necessary. This will simply prevent the project from building, which will prevent any artifacts from being published.