mirror of
https://github.com/EssentialsX/Essentials.git
synced 2024-11-21 01:01:35 +08:00
Update README and contributing guide (#4851)
Co-authored-by: Josh Roy <10731363+JRoy@users.noreply.github.com> This PR brings the README up-to-date, reduces the number of references to upstream Essentials, and fleshes out the contributing guide with much more detail.
This commit is contained in:
MD
GitHub
parent
3af931740b
commit
c6066bd2d8
115
CONTRIBUTING.md
115
CONTRIBUTING.md
@ -1,31 +1,102 @@
|
||||
Contributing to EssentialsX
|
||||
===========================
|
||||
# Contributing to EssentialsX
|
||||
|
||||
Want to help improve EssentialsX? There are several ways you can support and contribute to the project.
|
||||
*By contributing to EssentialsX, you agree to license your changes under the [GNU General Public License version 3](https://github.com/EssentialsX/Essentials/blob/2.x/LICENSE).*
|
||||
|
||||
If you'd like to make a financial contribution to the project, you can join our [Patreon](https://www.patreon.com/essentialsx/),
|
||||
or to make a one-off donation you can visit our [Ko-fi page](https://ko-fi.com/essentialsx). If you can't make a
|
||||
donation, don't worry! There are lots of other ways to contribute:
|
||||
## Submitting code changes to EssentialsX
|
||||
|
||||
* Do you run a server? Take a look at our ["help wanted"](https://github.com/EssentialsX/Essentials/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22help+wanted%22)
|
||||
and ["bug: unconfirmed"](https://github.com/EssentialsX/Essentials/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22bug%3A+unconfirmed%22)
|
||||
issues, where you can find issues that need extra testing and investigation.
|
||||
* Do you speak multiple languages? If so, we always welcome contributions to our [Crowdin project](https://crowdin.com/project/essentialsx-official).
|
||||
* Do you enjoy helping others? If so, why not contribute to the [EssentialsX documentation](https://github.com/EssentialsX/wiki)?
|
||||
You can also join the [MOSS Discord community](https://discord.gg/casfFyh) and provide direct community support to
|
||||
other EssentialsX users.
|
||||
* If you're a developer, you could look through our ["open to PR"](https://github.com/EssentialsX/Essentials/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22status%3A+open+to+PR%22)
|
||||
issues. We're always happy to receive bug fixes and feature additions as pull requests.
|
||||
If you're interested in submitting new code to EssentialsX, we accept changes via GitHub pull requests.
|
||||
|
||||
Submitting a PR
|
||||
---------------
|
||||
### Adding features
|
||||
|
||||
EssentialsX has extensive templates for PRs that detail how to submit your PR. To find out more, see the PR templates for:
|
||||
* [Bug fixes](https://github.com/EssentialsX/Essentials/blob/2.x/.github/PULL_REQUEST_TEMPLATE/bug-fix.md)
|
||||
* [New features](https://github.com/EssentialsX/Essentials/blob/2.x/.github/PULL_REQUEST_TEMPLATE/new-feature.md)
|
||||
In general, we will only consider PRs for features if they have already been discussed with the team through
|
||||
GitHub issues and discussions. Check the list of
|
||||
["open to PR" issues](https://github.com/EssentialsX/Essentials/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22status%3A+open+to+PR%22)
|
||||
and [feature request discussions](https://github.com/EssentialsX/Essentials/discussions/categories/ideas-and-feature-suggestions)
|
||||
before you start working on your changes. If you don't see your desired feature listed,
|
||||
[open a feature request](https://github.com/EssentialsX/Essentials/issues/new/choose) and wait for a response, otherwise
|
||||
you may end up wasting your time on a feature that we aren't in a position to accept.
|
||||
|
||||
Want to discuss a feature before opening a PR? Join the [EssentialsX Development Discord server](https://discord.gg/CUN7qVb). Note that this server is **not for end-users** - if you need support with EssentialsX, you should join [MOSS](https://discord.gg/casfFyh) instead.
|
||||
#### Keep it focused
|
||||
|
||||
By contributing to EssentialsX, you agree to license your code under the [GNU General Public License version 3](https://github.com/EssentialsX/Essentials/blob/2.x/LICENSE).
|
||||
Please try to keep feature PRs focused around one feature. Your PR should ideally contain
|
||||
one feature, or a few closely-linked features. If you submit several unrelated features
|
||||
in one PR, the PR will not be accepted.
|
||||
|
||||
### Fixing bugs
|
||||
|
||||
If you're opening a PR to fix a bug, please ensure a bug report has been filed - search the
|
||||
[issue tracker](https://github.com/EssentialsX/Essentials/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22bug%3A+confirmed%22%2C%22bug%3A+unconfirmed%22%2C%22bug%3A+upstream%22)
|
||||
for an existing report, and if you can't find a bug report,
|
||||
[create one](https://github.com/EssentialsX/Essentials/issues/new/choose) before you submit your PR.
|
||||
|
||||
#### Unconfirmed bugs
|
||||
|
||||
You may find a bug report with the label `bug: unconfirmed`. This means the EssentialsX team hasn't had the time
|
||||
to review the bug report yet or hasn't been able to confirm
|
||||
whether the reported issue is actually a bug in EssentialsX. You can help us by following the steps in the report and
|
||||
posting whether you are able to replicate this issue, ideally on the latest versions of EssentialsX and Paper. This will
|
||||
help us confirm issues and prioritise PRs accordingly.
|
||||
|
||||
#### Upstream bugs
|
||||
|
||||
You may also find bug reports with the `bug: upstream` label. This label means the issue is caused by a bug in *another
|
||||
project*, not EssentialsX. This includes bugs in CraftBukkit/Spigot and bugs in other plugins. It may be appropriate to
|
||||
mitigate an issue in EssentialsX, but please check with us in the [EssentialsX Development Discord server](https://discord.gg/CUN7qVb) before you submit a PR.
|
||||
|
||||
### Making your changes
|
||||
|
||||
You'll need the following to make your changes to EssentialsX:
|
||||
|
||||
* A GitHub account
|
||||
* [`git`](https://git-scm.com/downloads): the Git command-line tool, used to track and save your changes
|
||||
* [`gh`](https://cli.github.com/): the GitHub command-line tool, used to submit your changes to EssentialsX
|
||||
* Your IDE of choice - we recommend [IntelliJ IDEA Community Edition](https://www.jetbrains.com/idea/download)
|
||||
|
||||
If you're already familiar with Git, you can skip this next section.
|
||||
|
||||
You'll need to clone the EssentialsX repository
|
||||
(`gh repo clone EssentialsX/Essentials`), then create a new branch for your work
|
||||
(`cd Essentials` then `git switch -c my-cool-pr`).
|
||||
|
||||
You can then make changes using your IDE of choice. Follow the instructions in `README.md` to build and test your
|
||||
changes.
|
||||
|
||||
Once you've finished, you should commit your changes (`git commit -am "My cool commit name!"`).
|
||||
|
||||
### Submitting your PR
|
||||
|
||||
*Even if you're already familiar with GitHub, you will need to follow these steps in order to submit a PR to
|
||||
EssentialsX. This ensures we have the information we need to test and review your changes.*
|
||||
|
||||
Next, you'll need to fork EssentialsX on GitHub and push your changes to a branch on that fork. We strongly recommend
|
||||
using the `gh` command-line tool for this:
|
||||
|
||||
* In your terminal, run `gh pr create`.
|
||||
* Select either the bug fix or feature template, depending on what your PR is for.
|
||||
* If you get asked `Where should we push the '...' branch?`, select `Create a fork of EssentialsX/Essentials`.
|
||||
* For the title, choose a title that describes what your PR does. For example, `Add more ducks to /spawnmob`.
|
||||
* For the body, press E. You will then need to fill in the PR template in your text editor.
|
||||
- Follow the instructions in the template and fill out the sections as required.
|
||||
- This step is important! Without it, we won't know why you've made your changes or how to test them.
|
||||
* Save the file in your text editor and close it, then return to the terminal.
|
||||
* Select `Submit` to open your PR.
|
||||
|
||||
If you follow these steps correctly, GitHub will create a fork (if necessary) and then open a PR with your changes. You
|
||||
can now sit back while we review your changes. If we need to ask questions or request further changes to your code,
|
||||
we will review your PR and post a comment on GitHub. You can respond to our reviews and comments on the GitHub website,
|
||||
and you can push new changes using `git commit` and `git push`.
|
||||
|
||||
|
||||
## Submitting community translations to EssentialsX
|
||||
|
||||
EssentialsX relies on community translations for its messages in other languages. You can help translate EssentialsX on
|
||||
[Crowdin](https://translate.essentialsx.net/). You'll need a Crowdin account to translate and improve messages.
|
||||
|
||||
If your language isn't listed or doesn't have an active proofreader, please let us know on Discord (see below).
|
||||
|
||||
|
||||
## Discussing EssentialsX contributions
|
||||
|
||||
Want to discuss something before opening a PR or translating messages? Join the
|
||||
[EssentialsX Development Discord server](https://discord.gg/CUN7qVb). Note that this server is **not for end-users** -
|
||||
if you need support with EssentialsX, you should join [MOSS](https://discord.gg/casfFyh) instead.
|
||||
|
||||
113
README.md
113
README.md
@ -13,53 +13,64 @@ If you are using this, do **NOT** ask Essentials for support.
|
||||
The official upstream repository for the original Essentials project is at https://github.com/Essentials/Essentials.
|
||||
|
||||
|
||||
Why use EssentialsX?
|
||||
--------------------
|
||||
## Why use EssentialsX?
|
||||
|
||||
EssentialsX is an unofficial continuation of Essentials, updated to support modern Minecraft and Spigot versions. It provides several performance enhancements and fixes that are currently not available in Essentials and Spigot-Essentials. [For more details, see the wiki.](https://essentialsx.net/wiki/Improvements.html)
|
||||
EssentialsX is a continuation of the Essentials plugin suite, updated to support modern Minecraft and Spigot versions.
|
||||
|
||||
EssentialsX is almost a completely drop-in replacement for Essentials. However, it has different requirements:
|
||||
It provides countless new features, performance enhancements and fixes that are not available in the original
|
||||
Essentials or Spigot-Essentials. [For more details, see the wiki.](https://essentialsx.net/wiki/Improvements.html)
|
||||
|
||||
* **EssentialsX requires [Vault](http://dev.bukkit.org/bukkit-plugins/vault/) to enable chat prefix/suffixes and group support if you have a supported permissions plugin.** We recommend using [LuckPerms](https://luckperms.github.io).
|
||||
If you're coming from the original Essentials plugin, EssentialsX is a drop-in replacement for Essentials. It does,
|
||||
however, have some new requirements:
|
||||
|
||||
* **If you have an unsupported permissions plugin but still wish to use wildcards, enable `use-bukkit-permissions` in the configuration.** Otherwise, the plugin will fall back to config-based permissions.
|
||||
|
||||
* **EssentialsX requires Java 8 or higher.** On older versions, the plugin may not work properly.
|
||||
|
||||
* **EssentialsX supports Minecraft versions 1.8.8, 1.9.4, 1.10.2, 1.11.2, 1.12.2, 1.13.2, 1.14.4, 1.15.2, 1.16.5, 1.17.1, and 1.18.2.**
|
||||
* **EssentialsX requires CraftBukkit, Spigot or Paper to run.** Other server software may work, but these are not tested
|
||||
by the team and we may not be able to help with any issues that occur.
|
||||
* **EssentialsX currently supports Minecraft versions 1.8.8, 1.9.4, 1.10.2, 1.11.2, 1.12.2, 1.13.2, 1.14.4, 1.15.2,
|
||||
1.16.5, 1.17.1, and 1.18.2.**
|
||||
* **EssentialsX currently requires Java 8 or higher.** We recommend using the latest Java version supported by your
|
||||
server software.
|
||||
* **EssentialsX requires [Vault](http://dev.bukkit.org/bukkit-plugins/vault/) to enable using chat prefix/suffixes and
|
||||
group support from supported permissions plugins.**
|
||||
- **We recommend using [LuckPerms](https://luckperms.net) for permissions and groups.**
|
||||
- If you have an unsupported permissions plugin but still want to use wildcards, **enable `use-bukkit-permissions` in
|
||||
the configuration.** Otherwise, the plugin will fall back to config-based permissions.
|
||||
|
||||
|
||||
Support
|
||||
-------
|
||||
## Support
|
||||
|
||||
Need help with using EssentialsX? Join the [MOSS Discord community](https://discord.gg/casfFyh) to ask for help and discuss EssentialsX.
|
||||
|
||||
If you need to report a bug or want to suggest a new feature, you can [open an issue on GitHub](https://github.com/EssentialsX/Essentials/issues/new/choose).
|
||||
|
||||
|
||||
Building
|
||||
--------
|
||||
## Building
|
||||
|
||||
To build EssentialsX, you need JDK 8 or higher installed on your system. Then, run the following command:
|
||||
```sh
|
||||
./gradlew build
|
||||
```
|
||||
To build EssentialsX, you need JDK 8 or higher installed on your system.
|
||||
|
||||
...or if you're on windows run the following command:
|
||||
Clone this repository, then run the following command:
|
||||
|
||||
```batch
|
||||
gradlew build
|
||||
```
|
||||
* On Linux or macOS: `./gradlew build`
|
||||
* On Windows: `gradlew build`
|
||||
|
||||
Each module's jar can be found in `build/libs/` inside each module's directory or in `jars/`.
|
||||
You can then find builds of EssentialsX modules in the `jars/` directory.
|
||||
|
||||
### Running a test server
|
||||
|
||||
You can also run a test server from your development environment using the following command:
|
||||
|
||||
* On Linux or macOS: `./gradlew build :runServer`
|
||||
* On Windows: `gradlew build :runServer`
|
||||
|
||||
Note the `:` - without it, you will run several servers at once, which will likely crash Gradle.
|
||||
|
||||
|
||||
Using EssentialsX in your plugin
|
||||
--------------------------------
|
||||
## Using EssentialsX in your plugin
|
||||
|
||||
Do you want to integrate with EssentialsX in your plugin? You can use the EssentialsX Maven repo to build against EssentialsX's API.
|
||||
Do you want to integrate with EssentialsX in your plugin? You can build your plugin against the **EssentialsX API**,
|
||||
available from the EssentialsX Maven repo.
|
||||
|
||||
Releases are hosted on the Maven repo at `https://repo.essentialsx.net/releases/`, while snapshots (including dev builds) are hosted at `https://repo.essentialsx.net/snapshots/`.
|
||||
Releases are hosted on the Maven repo at `https://repo.essentialsx.net/releases/`, while snapshots (including dev
|
||||
builds) are hosted at `https://repo.essentialsx.net/snapshots/`.
|
||||
|
||||
To add EssentialsX to your build system, you should use the following artifacts:
|
||||
|
||||
@ -69,28 +80,44 @@ To add EssentialsX to your build system, you should use the following artifacts:
|
||||
| Snapshots | `net.essentialsx` | `EssentialsX` | `2.19.5-SNAPSHOT` |
|
||||
| Older releases | `net.ess3` | `EssentialsX` | `2.18.2` |
|
||||
|
||||
Note: up until `2.18.2`, EssentialsX used the `net.ess3` group ID, but starting with `2.19.0` snapshots, the group ID is now `net.essentialsx`.
|
||||
Note: until version `2.18.2`, EssentialsX used the `net.ess3` group ID.
|
||||
From `2.19.0` onwards, EssentialsX uses the `net.essentialsx` group ID.
|
||||
When updating your plugin, make sure you use the correct group ID.
|
||||
|
||||
You can find more information and examples at the [wiki](https://essentialsx.net/wiki/Common-Issues.html#how-do-i-add-essentialsx-as-a-dependency).
|
||||
You can find more information, including Maven and Gradle examples, at the
|
||||
[wiki](https://essentialsx.net/wiki/Common-Issues.html#how-do-i-add-essentialsx-as-a-dependency).
|
||||
|
||||
Contributing
|
||||
------------
|
||||
## Support the EssentialsX project
|
||||
|
||||
Want to help improve EssentialsX? There are several ways you can support and contribute to the project.
|
||||
|
||||
If you'd like to make a financial contribution to the project, you can join our [Patreon](https://www.patreon.com/essentialsx/),
|
||||
or to make a one-off donation you can visit our [Ko-fi page](https://ko-fi.com/essentialsx). If you can't make a
|
||||
donation, don't worry! There are lots of other ways to contribute:
|
||||
### Donate to EssentialsX
|
||||
|
||||
* Do you run a server? Take a look at our ["help wanted"](https://github.com/EssentialsX/Essentials/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22help+wanted%22)
|
||||
and ["bug: unconfirmed"](https://github.com/EssentialsX/Essentials/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22bug%3A+unconfirmed%22)
|
||||
issues, where you can find issues that need extra testing and investigation.
|
||||
* Do you speak multiple languages? If so, we always welcome contributions to our [Crowdin project](https://crowdin.com/project/essentialsx-official).
|
||||
* Do you enjoy helping others? If so, why not contribute to the [EssentialsX documentation](https://github.com/EssentialsX/wiki)?
|
||||
You can also join the [MOSS Discord community](https://discord.gg/casfFyh) and provide direct community support to
|
||||
other EssentialsX users.
|
||||
* If you're a developer, you could look through our ["open to PR"](https://github.com/EssentialsX/Essentials/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22status%3A+open+to+PR%22)
|
||||
issues. We're always happy to receive bug fixes and feature additions as pull requests.
|
||||
Donations allow us to cover the costs of our infrastructure, and also enable us to keep updating EssentialsX with new
|
||||
features and for new Minecraft versions.
|
||||
|
||||
You can support us with a one-off or monthly donation via [GitHub Sponsors](https://github.com/sponsors/EssentialsX),
|
||||
and you'll get a badge on GitHub for supporting the project through this.
|
||||
|
||||
Alternatively, you can also donate monthly to the EssentialsX project on [Patreon](https://www.patreon.com/essentialsx/),
|
||||
or you can make a one-off donation on our [Ko-fi page](https://ko-fi.com/essentialsx).
|
||||
|
||||
If you can't make a donation, don't worry! There are lots of other ways to contribute:
|
||||
|
||||
### Contributing directly to EssentialsX
|
||||
|
||||
* Are you a developer? We're always happy to receive bug fixes and feature additions as pull requests.
|
||||
* Do you speak multiple languages? If so, we always welcome contributions to our community translations.
|
||||
[Crowdin project](https://crowdin.com/project/essentialsx-official).
|
||||
|
||||
See [CONTRIBUTING.md](https://github.com/EssentialsX/Essentials/blob/2.x/CONTRIBUTING.md) to find out more.
|
||||
|
||||
### Providing support to other users
|
||||
|
||||
* Do you run a server? Take a look at our
|
||||
["help wanted"](https://github.com/EssentialsX/Essentials/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22help+wanted%22)
|
||||
and ["bug: unconfirmed"](https://github.com/EssentialsX/Essentials/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22bug%3A+unconfirmed%22)
|
||||
issues, where you can find issues that need extra testing and investigation.
|
||||
* Do you want to help others set up EssentialsX? You can contribute to the
|
||||
[EssentialsX docs](https://github.com/EssentialsX/wiki). You can also join the
|
||||
[MOSS Discord community](https://discord.gg/casfFyh) and provide direct community support to other EssentialsX users.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user