When contributing to this repository, please first discuss the change you wish to make via issues, discussions, or any other method with the owners of this repository before making a change.
Note that we have a code of conduct, so please follow it in all your interactions with the project.
A contribution can be as simple as opening a discussion or reporting us an issue, an idea of enhancement or a code improvement.
No matter of your capabilities or how important is your wish to contribute to this project, your help will be welcome and very appreciated!
Discussions are where we have conversations.
If you'd like to help troubleshooting a PR you're working on, have a great new idea, or want to share something amazing you've experimented with our product, join us in discussions.
Issues are used to track tasks that contributors can help with. If an issue doesn't have any label, this means we haven't reviewed it yet, and you shouldn't begin to work on it.
If you've found a bug, a weird behavior or an exploit, search open issues to see if someone else has reported the same thing. If it's something new, open an issue using a template. We'll use the issue to have a conversation about the problem you want to be fixed.
A pull request is a way to suggest changes in our repository. When we merge those changes, they would be deployed in the next release by the maintainer. 🌍
If this is your first pull request (PR), we recommend you to get familiar with the process through this GitHub repository.
When considering contributing to the project through PRs, please follow these guidelines:
- Try to open several smaller PRs instead of only a big one, it will make the job of the reviewers easier.
- Give a summary of the changes provided by your PR. Link any related issue, discussion or documentation that could help the reviewer understand your work, the impacts and the plus-value.
- You will need at least one approval of a reviewer before being able to merge the PR.
- All automatic jobs must pass (GitHub Actions, SonarQube analysis, security scans, formatting verification, ...) before merging.
If you are working on Bukkit related parts of the project, then you may find useful to consult these documentations if required:
Asking questions is a way for you to be unblocked, and by doing so, this could help other people too if they are interested in the answer! Thus, the best place for asking support is under discussions.
Furthermore, rest assured that the community will try to find the best way to help you! ✨
These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.
Working on this project requires the following dependencies installed in your local environment:
- JDK 17 (Download Link)
- Maven 3.8+ (Download Link | Install Guide)
- Docker v24.0+ (on Windows it's possible to use Docker Desktop, Podman Desktop or Rancher Desktop:
choose whatever you want or any other alternative if you like)
- Required for running integration tests
- Testcontainers reusable containers feature
enabled (how to)
- On Linux you can run the following command:
echo 'testcontainers.reuse.enable=true' >> ~/.testcontainers.properties
We suppose you know how to install a Minecraft server.
To build the project and run unit and integration tests, you can simply build the project by typing this command at the root project:
$ mvn
This is the command you will run most of the time.
You will find the packaged JAR file of the PaperMC plugin at src/paper-plugin/target.
If you want to test it, copy it into your local PaperMC server by taking care that the server
version is compatible with the plugin.
The TDD is a great way to improve software quality and maintainability by writing tests first.
A good way to adopt this approach is by relying on the "red, green, refactor" framework.
Each source code change must add, update or remove tests while ensuring a minimal code coverage of 80% is respected. Meeting these requirements is required for each PR before being merged.
The only thing we ask when contributing to the code is to apply Google Java Style Guide.
To help respect this, an automatic formatter has been configured through Maven to be dispatched automatically when building the project and running tests.
If you are using IntelliJ IDEA, you can install the google-java-format plugin which will replace the default IDE code formatting behavior.
Following a standard for commit message provides several benefits:
- Readable for both humans and machines
- Automatic version bump
- Automatic release note creation/update
This is why we strive to follow the Conventional Commits one.
We took inspiration from Angular project.
<type>(<scope>): <short summary>
│ │ │
│ │ └─⫸ Summary in present tense. Not capitalized. No period at the end.
│ │
│ └─⫸ Commit Scope: core|paper-adapter|paper-plugin|readme|contributing|packaging|deps|
│ other|github|renovate|release
│
└─⫸ Commit Type: feat|fix|perf|refactor|docs|test|build|ci|chore
The <type> and <summary> fields are mandatory, the (<scope>) field is optional.
It must be one of the following:
- feat: A new feature
- fix: A bug fix
- perf: A code change that improves performance
- refactor: A code change that neither fixes a bug nor adds a feature
- docs: Documentation only changes
- test: Adding missing tests or correcting existing tests
- build: Changes that affect the build system or external dependencies (e.g. PaperMC API, Guice, Flyway, ...)
- ci: Changes to our CI configuration files and scripts (e.g. GitHub Actions, Renovate, ...)
- chore: Changes that don't in any other category (e.g. dependencies' update, update
of
.gitignore.gitattributes&.editorconfigfiles, ...)
Most of the time, you should try to stick with the following scopes:
- core: used for changes related to the
patch-place-break-api,patch-place-break-coreandpatch-place-break-ctsmodules - paper-adapter: used for changes related to the
paper-patch-adaptermodule - paper-plugin: used for changes related to the
paper-pluginmodule
But there are exceptions that shall be considered as well depending mostly on the change type.
- readme: used for changes updating the
README.mdfile - contributing: used for changes updating the contribution-related
files:
CONTRIBUTING.md,CODE_OF_CONDUCT.md&SECURITY.md
- packaging: used for changes updating the Maven layout in all of our modules (e.g. groupId change, inherited plugins changes, ...)
- github: used for updating GitHub Actions workflows, issues/PRs templates and
CODEOWNERSfile(s) - renovate: used for updating Renovate configuration
- release: used for updating release-related configuration
- deps: used for changes updating the project dependencies
- none/empty string: useful for test and refactor changes that are done across all packages (e.g. test: add missing unit tests) and for docs changes that are not related to a specific package (e.g. docs: fix typo in tutorial)
The summary must provide a succinct description of the change:
- Use the imperative, present tense: "change" not "changed" nor "changes"
- Don't capitalize on the first letter
- No dot (.) at the end
Just as in the summary, use the imperative, present tense: "fix" not "fixed" nor "fixes".
Explain the motivation for the change in the commit message body. This commit message should explain why you are making the change. You can include a comparison of the previous behavior with the new behavior in order to illustrate the impact of the change.
The footer can contain information about breaking changes and is also the place to reference GitHub issues, Jira tickets, and other PRs that this commit closes or is related to.
For example:
BREAKING CHANGE: <breaking change summary>
<BLANK LINE>
<breaking change description + migration instructions>
<BLANK LINE>
<BLANK LINE>
Fixes #<issue number>
Breaking Change section should start with the phrase BREAKING CHANGE: followed by a summary of
the breaking change, a blank line, and a detailed description of the breaking change that also
includes migration instructions.