[ci skip] Update contributing guidelines (#6497)

Co-authored-by: Jason Penilla <[email protected]>

1 files changed, 85 insertions, 107 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 8f4503c565..ce1812f581 100644
--- a/CONTRIBUTING.md
+++ b/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:
-
-```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:
+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 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