Merge pull request #45 from refinedmods/release/1.1.0

Release v1.1.0

.github/CONTRIBUTING.md

@@ -1,47 +1,203 @@
-# Contributing to Ranged Pumps
+# Contributing
+
+When contributing to this repository, please first discuss the change you wish to make via
+[GitHub issues](https://github.com/refinedmods/rangedpumps/issues), [Discord](https://discordapp.com/invite/VYzsydb),
+or any other method with the owners of this repository before making a change.
+
+## Pull requests
+
+- Keep your pull request (PR) as small as possible, this makes reviewing easier.
+- Commits serve a clear purpose and have a fitting commit message.
+- Branches are kept up to date by rebasing (updating a branch by merging makes for a confusing Git history).
+- PRs are merged by merging the commits on top of the target branch (which is `develop`).
+- Remember to add your changes in `CHANGELOG.md`. If your changes are merely technical, it's not necessary to update the
+  changelog as it's not relevant for users.
+
+### Commit messages
+
+Commit messages must adhere to [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). We
+use [Commitlint](https://commitlint.js.org/) to validate commit messages.
+
+We use
+the [conventional configuration](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional)
+for Commitlint.
+
+It is recommended to install
+the [Conventional Commit plugin](https://plugins.jetbrains.com/plugin/13389-conventional-commit) to make it
+easier to write commit messages.
+
+### Branch names
+
+Because we use merge commits when merging a PR, branch names will be part of the history of the repository. That is why
+branch names must follow a certain standard.
+
+The format is `{category}/GH-{issue number}/{lowercase-description}` and a branch name can be maximum 50 characters of
+length.
+
+Category must match a
+category [used in our Commitlint config](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional#type-enum).
+
+Valid examples are:
+
+- `fix/GH-123/add-branch-linting`
+- `docs/GH-123/cleanup`
 
 ## Versioning
 
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## Pull requests
+### Version metadata
 
-- Keep your PR as small as possible, this makes reviewing easier.
-- Commits serve a clear purpose and have a fitting commit message.
-- Branches are kept up to date by rebasing, preferably.
-- PRs are merged by rebasing the commits on top of the target branch.
-- Changes are added in `CHANGELOG.md`. Please refrain from using technical terminology, keep it user-friendly. The
-  format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+The code doesn't contain version metadata: `build.gradle` specifies a version of `0.0.0` (via Refined Architect).
+The versioning information is entirely contained in Git by using tags.
+
+Per [Semantic Versioning](https://semver.org/spec/v2.0.0.html), the version number being released depends on the changes
+in that release. We usually can't predict those
+changes at the start of a release cycle, so we can't bump the version at the start of a release cycle. That means that
+the version number being released is determined at release time.
+
+Because the version number is determined at release time, we can't store any versioning metadata in the
+code (`build.gradle`). If we did, `build.gradle` would have the version number of the latest released version during the
+release cycle of the new version, which isn't correct.
+
+### Dealing with Minecraft
+
+Whenever we port to a new Minecraft version, at least the minor version should be incremented.
+
+This is needed so that we can still support older Minecraft versions without the version numbers conflicting.
+
+## Changelog
+
+The changelog is kept in `CHANGELOG.md`.
+
+Keeping a readable, relevant and user-friendly changelog is essential for our end users
+to stay up to date with the project.
+
+Please refrain from using technical terminology or adding entries for technical changes
+that are (generally) not relevant to the end-user.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## Gitflow
 
 This project uses [Gitflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow).
 
-## Releasing
+## Documentation
+
+Documentation must be kept up to date when adding or changing functionality.
+
+### Javadoc
+
+Javadoc is available after every release on https://refinedmods.com/rangedpumps/.
+
+### API annotations
+
+Public APIs must be annotated with an `@API` annotation
+from [API Guardian](https://github.com/apiguardian-team/apiguardian).
+
+## Code style
+
+We use [Checkstyle](https://checkstyle.sourceforge.io/) in our build workflow to validate coding style.
+
+It is recommended to import the [config/checkstyle/checkstyle.xml](../config/checkstyle/checkstyle.xml) file into your
+IDE, so that formatting rules are respected.
+
+Moreover, the [CheckStyle-IDEA plugin](https://plugins.jetbrains.com/plugin/1065-checkstyle-idea) can be used to check
+if there are no style violations.
+
+## Release process
+
+The release process is automated and follows Gitflow.
+
+Before running the "Draft release" workflow to start the release process make sure `CHANGELOG.md` contains all the
+unreleased changes.
 
-1) Make sure the version number in `build.gradle` is correct.
-2) Merge `develop` to `main`.
-3) Push a tag with the version number (prefixed with `v`).
+To determine the version number to be released, the workflow will ask you which release type this is (major, minor,
+patch).
+The latest version from `CHANGELOG.md` will be used as a base, and that will be incremented
+depending on the release type.
 
-After releasing:
+`CHANGELOG.md` will be updated by this workflow, you can review this in the resulting release PR.
 
-1) Rename the "Unreleased" section to the correct version number in `CHANGELOG.md`.
-2) Upgrade the version number in `build.gradle`.
-3) Create a new "Unreleased" section in `CHANGELOG.md`.
+If you merge the release PR, the "Publish release" workflow will automatically publish the release. An additional PR
+will be created to merge the changes in `CHANGELOG.md` back into `develop`.
 
-## Pipelines
+## Hotfix process
+
+The hotfix process is semi-automated and follows Gitflow:
+
+- Create a hotfix branch off `main`.
+- Commit your changes on this branch.
+- Update `CHANGELOG.md` (with version number and release date) manually on this branch.
+- Push the branch and create a PR for it, merging into `main`.
+
+The "Publish release" workflow will take care of the rest.
+
+## Workflows
+
+We have a few GitHub workflows:
+
+- Build (PRs, pushes to `develop` and `main`)
+- Draft release (manual trigger)
+- Publish release (merging a PR to `main`)
+- Validate changelog (PRs)
+  - To validate if `CHANGELOG.md` is valid and updated.
+  - Not every pull request needs a changelog change, so the `skip-changelog` label can be added to the pull request to
+    ignore this.
+- Validate commit messages (PRs)
+  - Validates whether the commits on a pull request
+    respect [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
+  - We use
+    the [conventional configuration](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional).
+- Validate branch names (PRs)
+- Issue for unsupported version (issues)
+  - Posts a message on a GitHub issue if the issue is about an unsupported version.
+- Lock resolved issues and PRs (every night)
 
 ### Build
 
-The build pipeline triggers when a commit is pushed to a branch or pull request.
+The build workflow triggers when a pull request is updated or when a commit is pushed to `develop` or `main`.
+
+The build workflow takes care of the following:
+
+- Running a Gradle build, running our tests in the process and generating an aggregated code coverage report for the API
+  modules.
+- Analyzing the code on SonarQube.
+  > Because of
+  > [limitations with SonarQube](https://portal.productboard.com/sonarsource/1-sonarcloud/c/50-sonarcloud-analyzes-external-pull-request),
+  > pull requests originating from a fork aren't analyzed on SonarQube.
+
+- Code style validation with Checkstyle.
+- Mutation and line coverage test with Pitest.
+- Uploading the artifacts on the action.
+
+### Draft release
+
+The draft release workflow is a manual workflow which will create a release branch from `develop`.
+
+To determine the version number to be released, it will extract the latest version number from `CHANGELOG.md` and
+increment it depending on the release type selected.
+
+This workflow takes care of the following:
 
-### Release
+- Creating the release branch.
+- Updating the changelog on this release branch.
+- Creating a pull request merging the release branch into `main`.
 
-The release pipeline triggers when a tag is pushed. This will run all the steps that our build pipeline does.
+### Publish release
 
-After that succeeds, it will publish to GitHub packages and CreeperHost Maven repository.
+The "publish release" workflow is triggered when a release or hotfix PR is merged to `main`. Usually, this will be the
+PR created earlier in the "Draft release" workflow.
 
-The "Unreleased" section in `CHANGELOG.md` is parsed and a GitHub release is created with the changelog body and
-relevant artifacts.
+The workflow takes care of the following:
 
-After that, a Discord and Twitter notification is sent.
+- Extracting the version number from the release or hotfix branch name that is merged in the PR.
+- Extracting the changelog entry for this version number.
+- Running a build.
+- Publishing on [GitHub packages](https://github.com/refinedmods/rangedpumps/packages) and
+  CreeperHost Maven.
+- Publishing Javadoc on [GitHub pages](https://github.com/refinedmods/rangedpumps/tree/gh-pages).
+- Deploying on [GitHub releases](https://github.com/refinedmods/rangedpumps/releases).
+- Announcing the release on Discord and Twitter.
+- Creating a PR that merges `main` back into `develop` to get the changes to `CHANGELOG.md` and `build.gradle`
+  into `develop` from the draft release workflow.

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -35,8 +35,8 @@ body:
         description: |
           If your Minecraft version isn't listed here, it means that it's no longer supported. In that case, don't create an issue.
         options:
-          - Minecraft 1.18.2
           - Minecraft 1.19.2
+          - Minecraft 1.20.1
       validations:
         required: true
     - type: input

.github/SUPPORT.md

@@ -0,0 +1,11 @@
+# Support
+
+If you have a problem and need help, we offer various channels where you can ask for help.
+
+## I have a question
+
+Questions can be asked on [Discord](https://discordapp.com/invite/VYzsydb).
+
+## I have found a bug
+
+If you have found a bug, please report it on [GitHub issues](https://github.com/refinedmods/rangedpumps/issues).

.github/workflows/build.yml

@@ -1,44 +1,15 @@
 name: Build
 on:
-    push:
-    pull_request:
-        types: [ opened, synchronize, reopened ]
+  push:
+    branches:
+      - develop
+      - main
+  pull_request:
+    types: [ opened, synchronize, reopened ]
 jobs:
-    build:
-        strategy:
-            matrix:
-                java: [
-                        17
-                ]
-                os: [ ubuntu-latest ]
-        runs-on: ${{ matrix.os }}
-        steps:
-            - name: Checkout repository
-              uses: actions/checkout@v2
-              with:
-                  fetch-depth: 0  # Shallow clones should be disabled for a better relevancy of analysis
-            - name: Validate Gradle wrapper
-              uses: gradle/wrapper-validation-action@v1
-            - name: Setup JDK ${{ matrix.java }}
-              uses: actions/setup-java@v1
-              with:
-                  java-version: ${{ matrix.java }}
-            - name: Cache Gradle packages
-              uses: actions/cache@v1
-              with:
-                  path: ~/.gradle/caches
-                  key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle') }}
-                  restore-keys: ${{ runner.os }}-gradle
-            - name: Make Gradle wrapper executable
-              if: ${{ runner.os != 'Windows' }}
-              run: chmod +x ./gradlew
-            - name: Build
-              run: ./gradlew build
-              env:
-                  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-            - name: Upload build artifacts
-              if: ${{ runner.os == 'Linux' && matrix.java == '17' }}
-              uses: actions/upload-artifact@v2
-              with:
-                  name: Artifacts
-                  path: build/libs/
+  build:
+    uses: refinedmods/refinedarchitect/.github/workflows/[email protected]
+    with:
+      mutation-testing: false
+      sonarqube: false
+    secrets: inherit

.github/workflows/draft-release.yml

@@ -0,0 +1,24 @@
+name: Draft release
+on:
+  workflow_dispatch:
+    inputs:
+      release-type:
+        description: 'Release type'
+        required: true
+        default: 'minor'
+        type: choice
+        options:
+          - major
+          - minor
+          - patch
+      version-number-override:
+        description: 'Version number override'
+        required: false
+        type: string
+jobs:
+  draft:
+    uses: refinedmods/refinedarchitect/.github/workflows/[email protected]
+    with:
+      release-type: ${{ inputs.release-type }}
+      version-number-override: ${{ inputs.version-number-override }}
+    secrets: inherit

.github/workflows/issue-for-unsupported-version.yml

@@ -0,0 +1,7 @@
+name: Issue for unsupported version
+on:
+  issues:
+    types: [ labeled, unlabeled, reopened ]
+jobs:
+  unsupported-labeler:
+    uses: refinedmods/refinedarchitect/.github/workflows/[email protected]

.github/workflows/publish-release.yml

@@ -0,0 +1,18 @@
+name: Publish release
+on:
+  pull_request:
+    branches:
+      - main
+    types:
+      - closed
+jobs:
+  publish-release:
+    uses: refinedmods/refinedarchitect/.github/workflows/[email protected]
+    secrets: inherit
+    with:
+      project-name: 'Ranged Pumps'
+      announce: true
+      mutation-testing: false
+      sonarqube: false
+      curseforge: true
+      modrinth: true