mirror of
https://github.com/PaperMC/Paper.git
synced 2024-12-26 22:40:21 +01:00
[ci skip] Update contributing guidelines (#6497)
Co-authored-by: Jason Penilla <11360596+jpenilla@users.noreply.github.com>
This commit is contained in:
Nassim Jahnke
GitHub
parent
f99119eb81
commit
7ff0a9ba19
1 changed files with 85 additions and 107 deletions
190
CONTRIBUTING.md
190
CONTRIBUTING.md
|
|
@ -28,12 +28,13 @@ To generate and update the TOC: https://github.com/mzlogin/vim-markdown-toc -->
|
|||
* [Configuration files](#configuration-files)
|
||||
* [PaperConfig example](#paperconfig-example)
|
||||
* [PaperWorldConfig example](#paperworldconfig-example)
|
||||
* [Testing API changes](#testing-api-changes)
|
||||
* [Using the Paper Test Plugin](#using-the-paper-test-plugin)
|
||||
* [Publishing to Maven local (use in external plugins)](#publishing-to-maven-local-use-in-external-plugins)
|
||||
* [Frequently Asked Questions](#frequently-asked-questions)
|
||||
* [I can't find the NMS file I need!](#i-cant-find-the-nms-file-i-need)
|
||||
* [Where can I learn how to name method/field?](#where-can-i-learn-how-to-name-methodfield)
|
||||
* [My commit doesn't need a build, what do I do?](#my-commit-doesnt-need-a-build-what-do-i-do)
|
||||
* [Patching and building is *really* slow, what can I do?](#patching-and-building-is-really-slow-what-can-i-do)
|
||||
* [I wrote some API, how do I use it in Paper-Server?](#i-wrote-some-api-how-do-i-use-it-in-paper-server)
|
||||
|
||||
<!-- vim-markdown-toc -->
|
||||
|
||||
|
|
@ -60,25 +61,26 @@ which can be obtained in (most) package managers such as `apt` (Debian / Ubuntu;
|
|||
you will most likely use this for WSL), `homebrew` (macOS / Linux), and more:
|
||||
|
||||
- `git` (package `git` everywhere);
|
||||
- `patch` (often package `patch`);
|
||||
- A Java 8 or later JDK (packages vary, use Google/DuckDuckGo/etc.).
|
||||
If you need one, you can find them on [AdoptOpenJDK](https://adoptopenjdk.net/).
|
||||
- `maven` (often package `maven`; can be found on
|
||||
[Apache's site](https://maven.apache.org/download.cgi) too);
|
||||
- `curl` (package `curl` everywhere).
|
||||
- A Java 16 or later JDK (packages vary, use Google/DuckDuckGo/etc.).
|
||||
- [Adoptium](https://adoptium.net/) has builds for most operating systems.
|
||||
- Paper requires JDK 16 to build, however makes use of Gradle's
|
||||
[Toolchains](https://docs.gradle.org/current/userguide/toolchains.html)
|
||||
feature to allow building with only JRE 8 or later installed. (Gradle will
|
||||
automatically provision JDK 16 for compilation if it cannot find an existing
|
||||
install).
|
||||
|
||||
If you're on Windows, check
|
||||
[the section on WSL](#patching-and-building-is-really-slow-what-can-i-do).
|
||||
|
||||
If you're compiling with Docker, you can use the
|
||||
[`adoptopenjdk`](https://hub.docker.com/_/adoptopenjdk/) images like so:
|
||||
If you're compiling with Docker, you can use Adoptium's
|
||||
[`eclipse-temurin`](https://hub.docker.com/_/eclipse-temurin/) images like so:
|
||||
|
||||
```console
|
||||
# docker run -it -v "$(pwd)":/data --rm adoptopenjdk:8-jdk-hotspot bash
|
||||
# docker run -it -v "$(pwd)":/data --rm eclipse-temurin:16.0.2_7-jdk bash
|
||||
Pulling image...
|
||||
|
||||
root@abcdefg1234:/# javac -version
|
||||
javac 1.8.0_252
|
||||
javac 16.0.2
|
||||
```
|
||||
|
||||
## Understanding Patches
|
||||
|
|
@ -88,8 +90,7 @@ split into different directories which target certain parts of the code. These
|
|||
directories are:
|
||||
|
||||
- `Paper-API` - Modifications to `Spigot-API`/`Bukkit`;
|
||||
- `Paper-MojangAPI` - An API for
|
||||
[Mojang's Brigadier](https://github.com/Mojang/brigadier);
|
||||
- `Paper-MojangAPI` - An API for [Mojang's Brigadier](https://github.com/Mojang/brigadier);
|
||||
- `Paper-Server` - Modifications to `Spigot`/`CraftBukkit`.
|
||||
|
||||
Because the entire structure is based on patches and git, a basic understanding
|
||||
|
|
@ -99,24 +100,18 @@ of how to use git is required. A basic tutorial can be found here:
|
|||
Assuming you have already forked the repository:
|
||||
|
||||
1. Clone your fork to your local machine;
|
||||
1. Type `./paper patch` in a terminal to apply the changes from upstream;
|
||||
1. cd into `Paper-Server` for server changes, and `Paper-API` for API changes.
|
||||
You can also run `./paper server` or `./paper api` for these same directories
|
||||
2. Type `./gradlew applyPatches` in a terminal to apply the changes from upstream.
|
||||
On Windows, leave out the `./` at the beginning for all `gradlew` commands;
|
||||
3. cd into `Paper-Server` for server changes, and `Paper-API` for API changes.
|
||||
<!--You can also run `./paper server` or `./paper api` for these same directories
|
||||
respectively.
|
||||
1. You can also run `./paper setup`, which allows you to type `paper <command>`
|
||||
from anywhere in the Paper structure in most cases.
|
||||
from anywhere in the Paper structure in most cases.-->
|
||||
|
||||
`Paper-Server` and `Paper-API` aren't git repositories in the traditional sense:
|
||||
|
||||
- Every single commit in `Paper-Server`/`Paper-API` is a patch;
|
||||
- `origin/master` points to a directory similar to `Paper-Server`/`Paper-API`
|
||||
but for Paper;
|
||||
- Typing `git status` should show that we are 10 or 11 commits ahead of master,
|
||||
meaning we have 10 or 11 patches Spigot and CraftBukkit don't.
|
||||
- If it says something like `212 commits ahead, 207 commits behind`,
|
||||
cd into the root directory of the cloned repository and type `git fetch` to
|
||||
update your upstream. Setting up a remote for the upstream Paper repository
|
||||
might be necessary.
|
||||
- `base` points to the unmodified source before Paper patches have been applied.
|
||||
- Each commit after `base` is a patch.
|
||||
|
||||
## Adding Patches
|
||||
|
||||
|
|
@ -125,7 +120,7 @@ Adding patches to Paper is very simple:
|
|||
1. Modify `Paper-Server` and/or `Paper-API` with the appropriate changes;
|
||||
1. Type `git add .` inside these directories to add your changes;
|
||||
1. Run `git commit` with the desired patch message;
|
||||
1. Run `./paper rebuild` in the main directory to convert your commit into a new
|
||||
1. Run `./gradlew rebuildPatches` in the main directory to convert your commit into a new
|
||||
patch;
|
||||
1. PR the generated patch file(s) back to this repository.
|
||||
|
||||
|
|
@ -148,6 +143,7 @@ edit it using `git rebase`.
|
|||
> you must reset the Server, and reset the API if you're editing the Server.
|
||||
|
||||
#### Using the Paper tool
|
||||
*CURRENTLY NOT OPERATIONAL*
|
||||
|
||||
The PaperMC build tool provides a handy command to automatically do this type of
|
||||
patch modification.
|
||||
|
|
@ -177,7 +173,7 @@ instruction do exactly what the above slightly automated system above does.
|
|||
1. If you have changes you are working on, type `git stash` to store them for
|
||||
later;
|
||||
- You can type `git stash pop` to get them back at any point.
|
||||
1. Type `git rebase -i upstream/upstream`;
|
||||
1. Type `git rebase -i base`;
|
||||
- It should show something like
|
||||
[this](https://gist.github.com/zachbr/21e92993cb99f62ffd7905d7b02f3159) in
|
||||
the text editor you get.
|
||||
|
|
@ -194,7 +190,7 @@ later;
|
|||
- **Make sure to add `--amend`** or else a new patch will be created.
|
||||
- You can also modify the commit message and author here.
|
||||
1. Type `git rebase --continue` to finish rebasing;
|
||||
1. Type `./paper rebuild` in the root directory;
|
||||
1. Type `./gradlew rebuildPatches` in the root directory;
|
||||
- This will modify the appropriate patches based on your commits.
|
||||
1. PR your modified patch file(s) back to this repository.
|
||||
|
||||
|
|
@ -211,14 +207,14 @@ messing with your HEADs.
|
|||
|
||||
1. Make your change while at HEAD;
|
||||
1. Make a temporary commit. You don't need to make a message for this;
|
||||
1. Type `git rebase -i upstream/upstream`, move (cut) your temporary commit and
|
||||
1. Type `git rebase -i base`, move (cut) your temporary commit and
|
||||
move it under the line of the patch you wish to modify;
|
||||
1. Change the `pick` to the appropriate action:
|
||||
1. `f`/`fixup`: Merge your changes into the patch without touching the
|
||||
message.
|
||||
1. `s`/`squash`: Merge your changes into the patch and use your commit message
|
||||
and subject.
|
||||
1. Type `./paper rebuild` in the root directory;
|
||||
1. Type `./gradlew rebuildPatches` in the root directory;
|
||||
- This will modify the appropriate patches based on your commits.
|
||||
1. PR your modified patch file(s) back to this repository.
|
||||
|
||||
|
|
@ -232,10 +228,10 @@ move it under the line of the patch you wish to modify;
|
|||
assist you too.
|
||||
- Alternatively, if you only know the name of the patch, you can do
|
||||
`git commit -a --fixup "Subject of Patch name"`.
|
||||
1. Rebase with autosquash: `git rebase --autosquash -i upstream/upstream`.
|
||||
1. Rebase with autosquash: `git rebase --autosquash -i base`.
|
||||
This will automatically move your fixup commit to the right place, and you just
|
||||
need to "save" the changes.
|
||||
1. Type `./paper rebuild` in the root directory;
|
||||
1. Type `./gradlew rebuildPatches` in the root directory;
|
||||
- This will modify the appropriate patches based on your commits.
|
||||
1. PR your modified patch file(s) back to this repository.
|
||||
|
||||
|
|
@ -244,14 +240,15 @@ need to "save" the changes.
|
|||
Steps to rebase a PR to include the latest changes from `master`.
|
||||
These steps assume the `origin` remote is your fork of this repository and `upstream` is the official PaperMC repository.
|
||||
|
||||
1. Pull latest changes from upstream's master: `git checkout master && git pull upstream master`.
|
||||
1. Pull the latest changes from upstreams master: `git checkout master && git pull upstream master`.
|
||||
1. Checkout feature/fix branch and rebase on master: `git checkout patch-branch && git rebase master`.
|
||||
1. Apply updated patches: `./paper patch`.
|
||||
1. Apply updated patches: `./gradlew applyPatches`.
|
||||
1. If there are conflicts, fix them.
|
||||
1. If your PR creates new patches instead of modifying exist ones, in both the `Paper-Server` and `Paper-API` directories, ensure your newly-created patch is the last commit by either:
|
||||
* Renaming the patch file with a large 4 digit number in front (e.g. 9999-Patch-to-add-some-new-stuff.patch)
|
||||
* Run `git rebase --interactive upstream/upstream` and move the commits to the end.
|
||||
1. Rebuild patches: `./paper rebuild`.
|
||||
* Renaming the patch file with a large 4-digit number in front (e.g. 9999-Patch-to-add-some-new-stuff.patch), and re-applying patches.
|
||||
* Running `git rebase --interactive base` and moving the commits to the end.
|
||||
1. Rebuild patches: `./gradlew rebuildPatches`.
|
||||
1. Commit modified patches.
|
||||
1. Force push changes: `git push --force`.
|
||||
|
||||
## PR Policy
|
||||
|
|
@ -352,31 +349,18 @@ index a92bf8967..d0ab87d0f 100644
|
|||
|
||||
## Obfuscation Helpers
|
||||
|
||||
In an effort to make future updates easier on ourselves, Paper tries to use
|
||||
obfuscation helpers whenever possible. The purpose of these helpers is to make
|
||||
the code more readable and maintainable. These helpers should be be made as easy
|
||||
to inline as possible by the JVM whenever possible.
|
||||
|
||||
An obfuscation helper to access an obfuscated item may be as simple as something
|
||||
like this:
|
||||
While rarely needed, obfuscation helpers are sometimes useful when it comes
|
||||
to unmapped local variables, or poorly named method parameters. In an effort
|
||||
to make future updates easier on ourselves, Paper tries to use obfuscation
|
||||
helpers wherever it makes sense. The purpose of these helpers is to make the
|
||||
code more readable and maintainable. These helpers should be made easy to
|
||||
inline by the JVM wherever possible.
|
||||
|
||||
An example of an obfuscation helper for a local variable:
|
||||
```java
|
||||
public final int getStuckArrows() { return this.bY(); } // Paper - OBFHELPER
|
||||
```
|
||||
|
||||
Or it may be as complex as forwarding an entire method so that it can be
|
||||
overridden later:
|
||||
|
||||
```java
|
||||
public boolean be() {
|
||||
// Paper start - OBFHELPER
|
||||
return this.pushedByWater();
|
||||
}
|
||||
|
||||
public boolean pushedByWater() {
|
||||
// Paper end
|
||||
return true;
|
||||
}
|
||||
double d0 = entity.getX(); final double fromX = d0; // Paper - OBFHELPER
|
||||
// ...
|
||||
this.someMethod(fromX); // Paper
|
||||
```
|
||||
|
||||
While they may not always be done in exactly the same way, the general goal is
|
||||
|
|
@ -429,13 +413,41 @@ private void useInhabitedTime() {
|
|||
```
|
||||
|
||||
Again, notice that the field is always public, but the setter is always private.
|
||||
To access this value, you'll need an instance of the `net.minecraft.World`
|
||||
To access this value, you'll need an instance of the `net.minecraft.world.level.Level`
|
||||
object:
|
||||
|
||||
```java
|
||||
return this.world.paperConfig.useInhabitedTime ? this.w : 0;
|
||||
return this.level.paperConfig.useInhabitedTime ? this.inhabitedTime : 0;
|
||||
```
|
||||
|
||||
## Testing API changes
|
||||
|
||||
### Using the Paper Test Plugin
|
||||
|
||||
The Paper project has a `test-plugin` module for easily testing out API changes
|
||||
and additions. To use the test plugin, enable it in `test-plugin.settings.gradle.kts`,
|
||||
which will be generated after running Gradle at least once. After this, you can edit
|
||||
the test plugin, and run a server with the plugin using `./gradlew runDev` (or any
|
||||
of the other Paper run tasks).
|
||||
|
||||
### Publishing to Maven local (use in external plugins)
|
||||
|
||||
To build and install the Paper APIs and Server to your local Maven repository, do the following:
|
||||
|
||||
- Run `./gradlew publishToMavenLocal` in the base directory.
|
||||
|
||||
If you use Gradle to build your plugin:
|
||||
- Add `mavenLocal()` as a repository. Gradle checks repositories in the order they are declared,
|
||||
so if you also have the Paper repository added, put the local repository above Paper's.
|
||||
- Make sure to remove `mavenLocal()` when you are done testing, see the [Gradle docs](https://docs.gradle.org/current/userguide/declaring_repositories.html#sec:case-for-maven-local)
|
||||
for more details.
|
||||
|
||||
If you use Maven to build your plugin:
|
||||
- If you later need to use the Paper-API, you might want to remove the jar
|
||||
from your local Maven repository.
|
||||
If you use Windows and don't usually build using WSL, you might not need to
|
||||
do this.
|
||||
|
||||
## Frequently Asked Questions
|
||||
|
||||
### I can't find the NMS file I need!
|
||||
|
|
@ -449,39 +461,25 @@ patching process.
|
|||
progress will be lost if you do not;
|
||||
1. Identify the name(s) of the file(s) you want to import.
|
||||
- A complete list of all possible file names can be found at
|
||||
`./work/Minecraft/$MCVER/spigot/net/minecraft/server`. You might find
|
||||
[MiniMappingViewer] very useful to find the file you need.
|
||||
1. Open the file at `./scripts/importmcdev.sh` and add the name of your file to
|
||||
the script. Skip to the 2nd last header and follow the instructions there;
|
||||
1. Re-patch the server `./paper patch`;
|
||||
`./Paper-Server/.gradle/caches/paperweight/mc-dev-sources/net/minecraft/`. You might find
|
||||
[MiniMappingViewer] useful if you need to translate between Mojang and Spigot mapped names.
|
||||
1. Open the file at `./build-data/dev-imports.txt` and add the name of your file to
|
||||
the script. Follow the instructions there;
|
||||
1. Re-patch the server `./gradlew applyPatches`;
|
||||
1. Edit away!
|
||||
|
||||
> ❗ This change is temporary! **DO NOT COMMIT CHANGES TO THIS FILE!**
|
||||
> Once you have made your changes to the new file, and rebuilt patches, you may
|
||||
> undo your changes to `importmcdev.sh`.
|
||||
> undo your changes to `dev-imports.txt`.
|
||||
|
||||
Any file modified in a patch file gets automatically imported, so you only need
|
||||
this temporarily to import it to create the first patch.
|
||||
|
||||
To undo your changes to the file, type `git checkout scripts/importmcdev.sh`.
|
||||
|
||||
### Where can I learn how to name method/field?
|
||||
|
||||
For most cases, it is preferred if you use [yarn], as their license works with
|
||||
Paper's license. If you can't do that, [MiniMappingViewer] is always around to
|
||||
provide you with more of a general idea, *but* you cannot use the Mojang names
|
||||
for more than understanding the code.
|
||||
|
||||
[yarn] is in general more thorough than Mojang's own mappings, as they include
|
||||
method arguments as well, whereas Mojang's do not. If you need local variables
|
||||
to understand the code, you might be more lucky with ModCoderPack.
|
||||
|
||||
For more information on the Mojang name licensing issues, check this out:
|
||||
<https://cpw.github.io/MinecraftMappingData.html>
|
||||
To undo your changes to the file, type `git checkout build-data/dev-imports.txt`.
|
||||
|
||||
### My commit doesn't need a build, what do I do?
|
||||
|
||||
Well, quite simple: You add `[CI-SKIP]` to the start of your commit subject.
|
||||
Well, quite simple: You add `[ci skip]` to the start of your commit subject.
|
||||
|
||||
This case most often applies to changes to files like `README.md`, this very
|
||||
file (`CONTRIBUTING.md`), the `LICENSE.md` file, and so forth.
|
||||
|
|
@ -510,24 +508,4 @@ everything like usual.
|
|||
> in Windows like described here:
|
||||
> <https://www.howtogeek.com/426749/how-to-access-your-linux-wsl-files-in-windows-10/>
|
||||
|
||||
### I wrote some API, how do I use it in Paper-Server?
|
||||
|
||||
To install the API to your local maven repository, do the following:
|
||||
|
||||
- Enter the API directory by running `./paper api`;
|
||||
- Run `mvn install`.
|
||||
- If you are working on a patch without much care for whether the tests
|
||||
pass, you can instead run `mvn install -DskipTests`. Do not PR changes
|
||||
without running tests first.
|
||||
- If a test failed, you have to identify the failing tests by scrolling up a
|
||||
couple lines (i.e. around 50-200). You should find it fairly quickly.
|
||||
- If you later need to use the Paper-API, you might want to remove the jar
|
||||
from your local maven repository.
|
||||
If you use Windows and don't usually build using WSL, you might not need to
|
||||
do this.
|
||||
|
||||
You can now use the API in your plugin to test it before PRing. You will also
|
||||
need to do this to build the Server with the implemented API.
|
||||
|
||||
[MiniMappingViewer]: https://minidigger.github.io/MiniMappingViewer/
|
||||
[yarn]: https://github.com/FabricMC/yarn
|
||||
|
|
|
|||
Loading…
Reference in a new issue