-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
0 parents
commit e05579d
Showing
58 changed files
with
2,118 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,227 @@ | ||
# Contributing | ||
|
||
When contributing to this repository, please first discuss the change you wish to make via | ||
[GitHub issues](https://github.com/refinedmods/refinedstorage-jei-integration/issues), [Discord](https://discordapp.com/invite/VYzsydb), | ||
or any other method with the owners of this repository before making a change. | ||
|
||
## Quickstart | ||
|
||
These are the most important things to know before contributing (also explained in more detail later in this document): | ||
|
||
- Commit messages must adhere to [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). | ||
- Branch names must be formatted correctly. The format is `{category}/GH-{issue number}/{lowercase-description}`. | ||
Category must match a | ||
category [used in our Commitlint config](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional#type-enum). | ||
- 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) | ||
or [config/intellij-code-style.xml](../config/intellij-code-style.xml) file into your | ||
IDE, so that formatting rules are respected. | ||
- Branches are kept up to date by rebasing, not by merging. | ||
- For non-technical changes, adding a changelog entry is required. | ||
|
||
## 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). | ||
|
||
## 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/). | ||
|
||
### Javadoc | ||
|
||
Javadoc is available after every release on https://refinedmods.com/javadoc/. | ||
|
||
## Gitflow | ||
|
||
This project uses [Gitflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow). | ||
|
||
## Documentation | ||
|
||
Documentation must be kept up to date when adding or changing functionality. | ||
|
||
### 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) | ||
or [config/intellij-code-style.xml](../config/intellij-code-style.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. | ||
|
||
## Architecture | ||
|
||
## Testing | ||
|
||
When adding functionality or fixing a bug, it is important to add tests. Tests are important, if not more important, | ||
than the implementation code. | ||
|
||
That means that they need to be first class citizens in the codebase, and must be readable | ||
at all times. | ||
|
||
They ensure that there are no regressions, act as general documentation for the codebase, | ||
and ensure that the project can evolve over time. | ||
|
||
To avoid brittle tests, tests need to validate behavior. A test cannot rely on the internal code structure, so most | ||
mocking should be avoided. | ||
|
||
### Test coverage | ||
|
||
Our [SonarQube quality gate](https://sonarcloud.io/organizations/refinedmods/quality_gates/show/9) requires a minimum | ||
test coverage percentage of 80%. | ||
|
||
### Mutation testing | ||
|
||
We also use [Pitest](https://pitest.org/) mutation testing. | ||
|
||
Our build workflow requires a minimum test coverage percentage of 80% and a minimum mutation | ||
coverage percentage of 90%. | ||
|
||
## 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 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: | ||
|
||
- 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-jei-integration/packages) and | ||
CreeperHost Maven. | ||
- Publishing Javadoc on [GitHub pages](https://github.com/refinedmods/javadoc). | ||
- Deploying on [GitHub releases](https://github.com/refinedmods/refinedstorage-jei-integration/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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
patreon: raoulvdberge |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,59 @@ | ||
name: Bug report | ||
description: Found a bug or encountered a crash? Please report it here. | ||
labels: [ bug ] | ||
body: | ||
- type: markdown | ||
attributes: | ||
value: | | ||
Provide a summary of the issue in the title above. | ||
- type: textarea | ||
id: description | ||
attributes: | ||
label: Describe the bug | ||
description: | | ||
Be as detailed as possible. | ||
If applicable, also tell us what you expected to happen instead. | ||
validations: | ||
required: true | ||
- type: textarea | ||
id: reproduce | ||
attributes: | ||
label: How can we reproduce this bug or crash? | ||
description: | | ||
Provide us with steps on how to reproduce this issue. | ||
placeholder: | | ||
1. | ||
2. | ||
3. | ||
validations: | ||
required: true | ||
- type: dropdown | ||
id: minecraft | ||
attributes: | ||
label: What Minecraft version is this happening on? | ||
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.20.4 | ||
validations: | ||
required: true | ||
- type: input | ||
id: modloader-version | ||
attributes: | ||
label: What NeoForge or Fabric version is this happening on? | ||
validations: | ||
required: true | ||
- type: input | ||
id: version | ||
attributes: | ||
label: What version is this happening on? | ||
description: | | ||
Ensure that you are using the latest version. | ||
validations: | ||
required: true | ||
- type: textarea | ||
id: logs | ||
attributes: | ||
label: Relevant log output | ||
description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks. | ||
render: shell |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
blank_issues_enabled: true | ||
contact_links: | ||
- name: Discord Community Support | ||
url: https://discordapp.com/invite/VYzsydb | ||
about: Please ask and answer questions here. Issues should be used for bugs and feature requests. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,23 @@ | ||
name: Enhancement | ||
description: Do you have a suggestion for a new feature or improvement? Let us know. | ||
labels: [ enhancement ] | ||
body: | ||
- type: markdown | ||
attributes: | ||
value: | | ||
Provide a summary of the enhancement in the title above. | ||
Please follow following guidelines before proposing an enchancement: | ||
1) Ensure that you are running on the latest version (to ensure that the enhancement does not exist yet). | ||
2) Ensure that your enhancement hasn't already been posted. Please look in the closed issues as well (for enhancements that have been denied). | ||
We might close your issue, without explanation, if you do not follow these guidelines. | ||
- type: textarea | ||
id: describe | ||
attributes: | ||
label: Describe your enhancement | ||
description: | | ||
Be as detailed as possible. | ||
Tell us how your idea should work. Why should we consider this? | ||
validations: | ||
required: true |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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/refinedstorage-jei-integration/issues). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,14 @@ | ||
name: Build | ||
on: | ||
push: | ||
branches: | ||
- develop | ||
- main | ||
pull_request: | ||
types: [ opened, synchronize, reopened ] | ||
jobs: | ||
build: | ||
uses: refinedmods/refinedarchitect/.github/workflows/[email protected] | ||
with: | ||
mutation-testing: false | ||
secrets: inherit |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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] |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,14 @@ | ||
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: 'Refined Storage - JEI Integration' | ||
mutation-testing: false |
Oops, something went wrong.