diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 589373f870..f986b1e24b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -29,6 +29,18 @@ Adding patches to Paper is very simple: Your commit will be converted into a patch that you can then PR into Paper +## Help! I can't find the file I'm looking for! +By default, Paper (and upstream) only import files that we make changes to. +If you would like to make changes to a file that isn't present in Paper-Server's source directory, you +just need to add it to our import script. + +1. Save (rebuild) any patches you are in the middle of working on! +2. Identify the names of the files you want to import. + - A complete list of all possible file names can be found at ```./work/Minecraft/$MCVER/net/minecraft/server``` +3. Open the file at `./scripts/importmcdev.sh` and add the name of your file to the script. +4. Re-patch the server `./paper patch` +5. Edit away! + ## Modifying Patches Modifying previous patches is a bit more complex: @@ -41,9 +53,9 @@ However, while in the middle of an edit, unless you also reset your API to a rel The PaperMC build tool provides a handy command to automatically do this type of patch modification. 1. Type `./paper edit server` or `./paper edit api` depending on which project you want to edit. - - It should show something like [this](https://gist.github.com/Zbob750/e6bb220d3b734933c320). + - It should show something like [this](https://gist.github.com/zachbr/21e92993cb99f62ffd7905d7b02f3159). 2. Replace `pick` with `edit` for the commit/patch you want to modify, and "save" the changes - - Only do this for one commit at a time. + - Only do this for one commit at a time. 3. Make the changes you want to make to the patch. 4. Type `./paper edit continue` to finish and rebuild patches. 5. PR your modifications back to this project. @@ -53,19 +65,19 @@ In case you need something more complex or want more control, this step-by-step exactly what the above slightly automated system does. 1. If you have changes you are working on type `git stash` to store them for later. - - Later you can type `git stash pop` to get them back. + - Later you can type `git stash pop` to get them back. 2. Type `git rebase -i upstream/upstream` - - It should show something like [this](https://gist.github.com/Zbob750/e6bb220d3b734933c320). + - It should show something like [this](https://gist.github.com/zachbr/21e92993cb99f62ffd7905d7b02f3159). 3. Replace `pick` with `edit` for the commit/patch you want to modify, and "save" the changes. - - Only do this for one commit at a time. + - Only do this for one commit at a time. 4. Make the changes you want to make to the patch. 5. Type `git add .` to add your changes. 6. Type `git commit --amend` to commit. - - **MAKE SURE TO ADD `--amend`** or else a new patch will be created. - - You can also modify the commit message here. + - **MAKE SURE TO ADD `--amend`** or else a new patch will be created. + - You can also modify the commit message here. 7. Type `git rebase --continue` to finish rebasing. 8. Type `./paper rebuild` in the main directory. - - This will modify the appropriate patches based on your commits. + - This will modify the appropriate patches based on your commits. 9. PR your modifications back to this project. ### Method 2 (sometimes easier) @@ -78,7 +90,7 @@ This method has the benefit of being able to compile to test your change without 3. Type `git rebase -i upstream/upstream`, move (cut) your temporary commit and move it under the line of the patch you wish to modify. 4. Change the `pick` with `f` (fixup) or `s` (squash) if you need to edit the commit message 5. Type `./paper rebuild` in the main directory - - This will modify the appropriate patches based on your commits + - This will modify the appropriate patches based on your commits 6. PR your modifications to github @@ -110,6 +122,43 @@ entity.getWorld().explode(new BlockPosition(spawnLocation.getX(), spawnLocation. - It is fine to go over 80 lines as long as it doesn't hurt readability - There are exceptions, especially in Spigot-related files - When in doubt, use the same style as the surrounding code + +## Patch Notes +When submitting patches to Paper, we may ask you to add notes to the patch header. +While we do not require it for all changes, you should add patch notes when the changes you're making are technical or complex. +It is very likely that your patch will remain long after we've all forgotten about the details of your PR, patch notes will help +us maintain it without having to dig back through GitHub history looking for your PR. + +These notes should express the intent of your patch, as well as any pertinent technical details we should keep in mind long-term. +Ultimately, they exist to make it easier for us to maintain the patch across major version changes. + +If you add a long message to your commit in the Paper-Server/API repos, the rebuildPatches command will handle these patch +notes automatically as part of generating the patch file. Otherwise if you're careful they can be added by hand (though you should be careful when doing this, and run it through a patch and rebuild cycle once or twice). + +```patch +From 02abc033533f70ef3165a97bfda3f5c2fa58633a Mon Sep 17 00:00:00 2001 +From: Shane Freeder +Date: Sun, 15 Oct 2017 00:29:07 +0100 +Subject: [PATCH] revert serverside behavior of keepalives + +This patch intends to bump up the time that a client has to reply to the +server back to 30 seconds as per pre 1.12.2, which allowed clients +more than enough time to reply potentially allowing them to be less +tempermental due to lag spikes on the network thread, e.g. that caused +by plugins that are interacting with netty. + +We also add a system property to allow people to tweak how long the server +will wait for a reply. There is a compromise here between lower and higher +values, lower values will mean that dead connections can be closed sooner, +whereas higher values will make this less sensitive to issues such as spikes +from networking or during connections flood of chunk packets on slower clients, + at the cost of dead connections being kept open for longer. + +diff --git a/src/main/java/net/minecraft/server/PlayerConnection.java b/src/main/java/net/minecraft/server/PlayerConnection.java +index a92bf8967..d0ab87d0f 100644 +--- a/src/main/java/net/minecraft/server/PlayerConnection.java ++++ b/src/main/java/net/minecraft/server/PlayerConnection.java +``` ## 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. These helpers should be be made as easy to inline as possible by the JVM whenever possible. @@ -135,7 +184,7 @@ While they may not always be done in exactly the same way each time, the general ## Configuration files To use a configurable value in your patch, add a new entry in either ```PaperConfig``` or ```PaperWorldConfig```. Use the former if a value must remain the same throughout all worlds, or the latter if it can change between worlds. The latter is preferred whenever possible. -###```PaperConfig``` example: +### PaperConfig example: ```java public static boolean saveEmptyScoreboardTeams = false; private static void saveEmptyScoreboardTeams() { @@ -143,9 +192,11 @@ private static void saveEmptyScoreboardTeams() { } ``` Notice that the field is always public, but the setter is always private. This is important to the way the configuration generation system works. To access this value, reference it as you would any other static value: -```if (!PaperConfig.saveEmptyScoreboardTeams) {``` +```java +if (!PaperConfig.saveEmptyScoreboardTeams) { +``` -###```PaperWorldConfig``` example: +### PaperWorldConfig example: ```java public boolean useInhabitedTime = true; private void useInhabitedTime() { @@ -154,4 +205,6 @@ 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``` object: -```return this.world.paperConfig.useInhabitedTime ? this.w : 0;``` +```java +return this.world.paperConfig.useInhabitedTime ? this.w : 0; +```