Setup for patch remapping, along with documentation on how to do itmappings/mojang/base

3 files changed, 100 insertions, 60 deletions

diff --git a/README.md b/README.md
index f580b62708..62aa425afb 100644
--- a/README.md
+++ b/README.md
@@ -1,76 +1,114 @@
-Paper ![GitHub Workflow Status (branch)](https://img.shields.io/github/workflow/status/PaperMC/Paper/Build%20Paper/master)
-===========
+Remapping Fork Patches
+======================
 
-High performance Spigot fork that aims to fix gameplay and mechanics inconsistencies.
+This repo is based on Paper 1.16.5. It can be used to remap patches of Paper forks.
 
+This branch is specifically and only for fork remapping. This is not for Paper development or for general use. It
+requires special steps and special set up. Follow the instructions in this readme, don't ask for help if you haven't
+read this entire readme and followed all of these steps.
 
-**Support and Project Discussion:**
- - [IRC](https://webchat.esper.net/?channels=paper) or [Discord](https://discord.gg/papermc)
- 
+Remapping patches requires knowledge of how to fix issues when patches don't or can't apply correctly. Patches not
+applying correctly is not an issue with this repo or paperweight. You must fix them and continue the process manually
+yourself. This is identical to any other upstream update.
 
-How To (Server Admins)
-------
-Paperclip is a jar file that you can download and run just like a normal jar file.
+Setup
+-----
 
-Download Paper from our [downloads page](https://papermc.io/downloads).
+Paper's unmapped 1.16.5 patches are in [`patches/server-unmapped/0001`](https://github.com/PaperMC/Paper/tree/mappings/mojang/base/patches/server-unmapped/0001).
+Place the patches you want to remap in `0002`. Paperweight will only remap patches placed in the last directory - for
+example if there are directories `0001`, `0002`, and `0003`, only the patches in `0003` will be remapped.
 
-Run the Paperclip jar directly from your server. Just like old times
+If you are remapping patches for a fork of a fork, place you other upstream patches in `0002`, and your patches in `0003`.
 
-  * Documentation on using Paper: [paper.readthedocs.io](https://paper.readthedocs.io/)
-  * For a sneak peak on upcoming features, [see here](https://github.com/PaperMC/Paper/projects)
+Pre-remapping
+-------------
+
+The patch remap task has no registered inputs, to make working with it repeated easier. That means if you run the task
+by itself, it will fail.
+
+Before you start remapping patches, you must first set up the patch environment by running:
+
+```shell
+./gradlew applyPatches
+```
+
+You will only need to do this once to set up the environment before you start remapping.
+
+Remapping
+---------
+
+To start remapping patches, run the `remapPatches` task:
+
+```shell
+./gradlew remapPatches
+```
+
+This can take a very long time, hours even, as patch remapping is a very complex and CPU & disk intensive task. How long
+it takes depends entirely on how many patches there are to be remapped, and how powerful your computer is.
+
+That said, while you may need to walk away during the process, the remapping process does require some amount of
+hands-on work to get it to complete. If you leave for a while and come back to a patch failure, you'll need to fix the
+issue and restart paperweight to pick up from where it left off, explained below.
+
+### Fixing patch application issues
+
+It is pretty unlikely that patch remapping will succeed first try. Paper's patches have already been fixed to apply
+correctly on this branch, but either your patches or your upstream patches are likely to fail in one way or another due
+to minor differences in tooling, setup, etc. Again, it is your responsibility to handle patch application issues as they
+come up just like any other upstream update.
+
+While the process of fixing issues with patch application is the same, how to resume and complete the process is
+different, as it hopefully goes without saying that patch remapping is a more complex process which requires extra work
+vs just a simple patch update.
+
+### Patch remap working directory setup
+
+There are a variety of files and directories that paperweight uses during patch remap, but only one directory that you
+need to worry about. This is the directory where patches are applied, and code is remapped.
 
-How To (Plugin Developers)
-------
- * See our API patches [here](Spigot-API-Patches)
- * See upcoming, pending, and recently added API [here](https://github.com/PaperMC/Paper/projects/6)
- * Paper API javadocs here: [papermc.io/javadocs](https://papermc.io/javadocs/)
- * Maven Repo (for paper-api):
-```xml
-<repository>
-    <id>papermc</id>
-    <url>https://papermc.io/repo/repository/maven-public/</url>
-</repository>
 ```
- * Artifact Information:
-```xml
-<dependency>
-    <groupId>com.destroystokyo.paper</groupId>
-    <artifactId>paper-api</artifactId>
-    <version>1.16.5-R0.1-SNAPSHOT</version>
-    <scope>provided</scope>
-</dependency>
- ```
-
-**Or alternatively, with Gradle:**
-
- * Repository:
-```groovy
-repositories {
-    maven {
-        url 'https://papermc.io/repo/repository/maven-public/'
-    }
-}
+<project_root>/.gradle/caches/paperweight/patch-remap-input
 ```
- * Artifact:
-```groovy
-dependencies {
-    compileOnly 'com.destroystokyo.paper:paper-api:1.16.5-R0.1-SNAPSHOT'
-}
+
+That directory contains what would be the `Paper-Server` directory during the patch remapping process.
+
+### Apply patch fixes
+
+If a patch fails to apply, go to the `patch-remap-input` directory to fix the issue, like you normally would. This repo
+contains the `apatch.sh` script in the `scripts` directory if you want to use it.
+
+Once you have fixed the issues in patch application, and are ready to continue, run `am --continue` in the
+`patch-remap-input` directory:
+
+```shell
+git am --continue
+```
+
+Each patch is applied in its own `am` session, so this won't cause any of the other patches to incidentally apply. After
+the `am` command in the above `patch-remap-input` directory is completed, continue the remapping process with:
+
+```shell
+./gradlew remapPatches --continue-remap
 ```
 
-How To (Compiling Jar From Source)
-------
-To compile Paper, you need JDK 8, maven, and an internet connection.
+Due to the `--continue-remap` flag paperweight will pick up where it left off. If the patch that failed is in a
+pre-remap upstream patch set, it will simply continue applying the other patches. If the patch is in the remap patch
+set, paperweight will record the patch, remap it, and re-apply it on the remap branch as it normally would, then
+continue applying the rest of the patches from there.
 
-Clone this repo, run `./paper jar` from *bash*, get files.
+### Completed patch remap
 
-How To (Pull Request)
-------
-See [Contributing](CONTRIBUTING.md)
+After the process is complete and all patches have been remapped, the new remapped patches (only including the remap
+patch set explained above) will be generated into `patches/server-remapped`.
 
-Special Thanks To:
--------------
+Help, something went wrong
+--------------------------
 
-![YourKit-Logo](https://www.yourkit.com/images/yklogo.png)
+If something goes wrong, it's almost certainly a patch application issue discussed above. We will not support or help
+you work through these kinds of issues. Dealing with patch breakages is part of the process of maintaining a fork, so if
+you don't already know what to do, don't expect us to teach you how to do it.
 
-[YourKit](https://www.yourkit.com/), makers of the outstanding java profiler, support open source projects of all kinds with their full featured [Java](https://www.yourkit.com/java/profiler) and [.NET](https://www.yourkit.com/.net/profiler) application profilers. We thank them for granting Paper an OSS license so that we can make our software the best it can be.
+If there is an error in paperweight that is causing some issue other than patch application, then we can look into
+figuring out what's wrong and fixing it. Please, *please*, read through everything here first and follow the
+instructions word for word. Do not try to simplify the process. Do not make up your own steps. If you do, again, we will
+absolutely not help you.
diff --git a/build.gradle.kts b/build.gradle.kts
index 53fe549258..58130c692e 100644
--- a/build.gradle.kts
+++ b/build.gradle.kts
@@ -4,7 +4,7 @@ import io.papermc.paperweight.util.set
 plugins {
     java
     id("com.github.johnrengelman.shadow") version "7.0.0" apply false
-    id("io.papermc.paperweight.core") version "1.1.8"
+    id("io.papermc.paperweight.core") version "1.1.9-SNAPSHOT"
 }
 
 subprojects {
diff --git a/gradle.properties b/gradle.properties
index de58c7304c..9d88d52d2e 100644
--- a/gradle.properties
+++ b/gradle.properties
@@ -3,3 +3,5 @@ version = 1.16.5-R0.1-SNAPSHOT
 
 mcVersion = 1.16.5
 packageVersion = 1_16_R3
+
+org.gradle.jvmargs=-Xmx4G