Add file import and patch notes to CONTRIBUTING.md

Also does some minor cleanup for broken formatting
This commit is contained in:
Zach Brown 2018-01-24 22:47:00 -05:00
parent 388f0e1001
commit c584eb918f
No known key found for this signature in database
GPG Key ID: CC9DA35FC5450B76
1 changed files with 66 additions and 13 deletions

View File

@ -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,7 +53,7 @@ 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.
3. Make the changes you want to make to the patch.
@ -55,7 +67,7 @@ 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.
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.
4. Make the changes you want to make to the patch.
@ -111,6 +123,43 @@ entity.getWorld().explode(new BlockPosition(spawnLocation.getX(), spawnLocation.
- 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 <theboyetronic@gmail.com>
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;
```