mirror/Essentials
2
0
Fork 0
mirror of https://github.com/EssentialsX/Essentials.git synced 2024-11-27 01:40:48 +08:00
Code Issues Packages Projects Releases Wiki Activity

Update README and contributing guide (#4851)

Browse Source 
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 2022-06-10 14:06:24 +01:00 committed by GitHub
parent 3af931740b
commit c6066bd2d8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 163 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

115
CONTRIBUTING.md
View File

@ -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/), ## Submitting code changes to 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:
* 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) If you're interested in submitting new code to EssentialsX, we accept changes via GitHub pull requests.
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.
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: In general, we will only consider PRs for features if they have already been discussed with the team through
* [Bug fixes](https://github.com/EssentialsX/Essentials/blob/2.x/.github/PULL_REQUEST_TEMPLATE/bug-fix.md) GitHub issues and discussions. Check the list of
* [New features](https://github.com/EssentialsX/Essentials/blob/2.x/.github/PULL_REQUEST_TEMPLATE/new-feature.md) ["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
View File

@ -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. 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 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 requires Java 8 or higher.** On older versions, the plugin may not work properly. * **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 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. 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). 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: To build EssentialsX, you need JDK 8 or higher installed on your system.
```sh
./gradlew build
```
...or if you're on windows run the following command: Clone this repository, then run the following command:
```batch * On Linux or macOS: `./gradlew build`
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: 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` | | Snapshots | `net.essentialsx` | `EssentialsX` | `2.19.5-SNAPSHOT` |
| Older releases | `net.ess3` | `EssentialsX` | `2.18.2` | | 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. 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. 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/), ### Donate to 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:
* 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) Donations allow us to cover the costs of our infrastructure, and also enable us to keep updating EssentialsX with new
and ["bug: unconfirmed"](https://github.com/EssentialsX/Essentials/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22bug%3A+unconfirmed%22) features and for new Minecraft versions.
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). You can support us with a one-off or monthly donation via [GitHub Sponsors](https://github.com/sponsors/EssentialsX),
* Do you enjoy helping others? If so, why not contribute to the [EssentialsX documentation](https://github.com/EssentialsX/wiki)? and you'll get a badge on GitHub for supporting the project through this.
You can also join the [MOSS Discord community](https://discord.gg/casfFyh) and provide direct community support to
other EssentialsX users. Alternatively, you can also donate monthly to the EssentialsX project on [Patreon](https://www.patreon.com/essentialsx/),
* 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) or you can make a one-off donation on our [Ko-fi page](https://ko-fi.com/essentialsx).
issues. We're always happy to receive bug fixes and feature additions as pull requests.
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. 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.