feat: introduce Refined Architect
This commit is contained in:
raoulvdberge
204
.github/CONTRIBUTING.md
vendored
204
.github/CONTRIBUTING.md
vendored
@@ -1,47 +1,203 @@
|
||||
# Contributing to Refined Storage
|
||||
# Contributing
|
||||
|
||||
When contributing to this repository, please first discuss the change you wish to make via
|
||||
[GitHub issues](https://github.com/refinedmods/refinedstorage/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
|
||||
|
||||
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`).
|
||||
Documentation must be kept up to date when adding or changing functionality.
|
||||
|
||||
After releasing:
|
||||
### Javadoc
|
||||
|
||||
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`.
|
||||
Javadoc is available after every release on https://refinedmods.com/refinedstorage/.
|
||||
|
||||
## Pipelines
|
||||
### 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.
|
||||
|
||||
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.
|
||||
|
||||
`CHANGELOG.md` will be updated by this workflow, you can review this in the resulting release PR.
|
||||
|
||||
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`.
|
||||
|
||||
## 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`.
|
||||
|
||||
### Release
|
||||
The build workflow takes care of the following:
|
||||
|
||||
The release pipeline triggers when a tag is pushed. This will run all the steps that our build pipeline does.
|
||||
- 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.
|
||||
|
||||
After that succeeds, it will publish to GitHub packages and CreeperHost Maven repository.
|
||||
- Code style validation with Checkstyle.
|
||||
- Mutation and line coverage test with Pitest.
|
||||
- Uploading the artifacts on the action.
|
||||
|
||||
The "Unreleased" section in `CHANGELOG.md` is parsed and a GitHub release is created with the changelog body and
|
||||
relevant artifacts.
|
||||
### Draft release
|
||||
|
||||
After that, a Discord and Twitter notification is sent.
|
||||
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:
|
||||
|
||||
- Creating the release branch.
|
||||
- Updating the changelog on this release branch.
|
||||
- Creating a pull request merging the release branch into `main`.
|
||||
|
||||
### Publish release
|
||||
|
||||
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 workflow takes care of the following:
|
||||
|
||||
- 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/refinedstorage/packages) and
|
||||
CreeperHost Maven.
|
||||
- Publishing Javadoc on [GitHub pages](https://github.com/refinedmods/refinedstorage/tree/gh-pages).
|
||||
- Deploying on [GitHub releases](https://github.com/refinedmods/refinedstorage/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.
|
||||
|
||||
Reference in New Issue
Block a user