Upstream
/
Paper
mirror of https://github.com/PaperMC/Paper.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

[ci skip] Update contributing guidelines (#6497) 

Co-authored-by: Jason Penilla <11360596+jpenilla@users.noreply.github.com>
This commit is contained in:
Nassim Jahnke 2021-08-31 02:18:45 +02:00 committed by GitHub
parent f99119eb81
commit 7ff0a9ba19
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 85 additions and 107 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

192
CONTRIBUTING.md
View File

@ -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.
@ -497,7 +495,7 @@ your version by running `winver` in the run window (Windows key + R)). If you're
out of date, update your system with the
[Windows Update Assistant](https://www.microsoft.com/en-us/software-download/windows10).
To setup WSL 2, follow the information here:
To set up WSL 2, follow the information here:
<https://docs.microsoft.com/en-us/windows/wsl/install-win10>
You will most likely want to use the Ubuntu apps. Once it's set up, install the
@ -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