Upstream/Paper
1
0
Fork 0
mirror of https://github.com/PaperMC/Paper.git synced 2024-11-22 18:45:54 +01:00
Code Issues Projects Releases Wiki Activity

README.md updates

Browse Source 
* Add description of how to apply patches to CraftBukkit.
* Extract PR guidelines into CONTRIBUTING.md
* Add index for easier navigation.
This commit is contained in:
Senmori 2018-08-20 02:03:01 -04:00 committed by md_5
parent 903c0e30c1
commit ec86574b9b
2 changed files with 79 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
CONTRIBUTING.md Normal file
View File

@ -0,0 +1,51 @@
Creating a Pull Request
-----------------------
##### Pull Request Title Example
The first line in a Pull Request(PR) message is an imperative statement briefly explaining what the PR is achieving.
If the PR fixes a bug, or implements a new feature as requested from the [JIRA](http://hub.spigotmc.org/jira/), then it should reference that ticket.
This is accomplished by simply type SPIGOT-####, where #### is the ticket number. (i.e. SPIGOT-3510).
You can reference multiple tickets in a single commit message; for example: "SPIGOT-1, SPIGOT-2" without the quotes.
__For Example:__
* SPIGOT-3510: Velocity broken for certain entities
* MC-111753, SPIGOT-2971: Brewing stand not reloading
As you can see, Minecraft tickets can be referenced by including the appropriate ticket number (i.e. MC-111753)
##### Pull Request Message Expectations
The body of a PR needs to describe how the ticket was resolved, or if there was no ticket, describe the problem itself.
If a PR is for both Bukkit and CraftBukkit it should include a link to the appropriate PR. [Read this to learn how to link to a PR.](https://confluence.atlassian.com/bitbucketserver053/markdown-syntax-guide-938022413.html?utm_campaign=in-app-help&utm_medium=in-app-help&utm_source=stash#Markdownsyntaxguide-Linkingtopullrequests)
##### Submitting the Changes
* Push your changes to a topic branch in your fork of the repository.
* Submit a pull request to the relevant repository in the Spigot organization.
* Make sure your pull request meets our [code requirements.](README.md)
* If you are fixing a JIRA ticket, be sure to update the ticket with a link to the pull request.
* Ensure all changes (including in patches) have our Minimal Diff Policy in mind.
##### Pull Request Feedback
Spigot has a lot of Pull Requests open. Some of these are old and no longer maintained. As a general rule, we do not delete PRs because they are old or abandoned.
You will eventually receive feedback on your Pull Requests. If the criticism is rough, do not take it personally. We have all started out, or just made bad PRs.
Take the advice and use it to make yourself better. If you think someone is being malicious contact an [admin](https://www.spigotmc.org/XenStaff/#Administrator).
Feedback goes both ways. If you believe a feature should be present then be prepared to argue your case.
Per our Code Requirements, formatting issues are almost always required to be fixed before a PR is accepted.
Although we have many discussions on Stash, there are also many discussions in the #spigot-dev channel of IRC.
Join us there if you plan on contributing to Spigot!
##### Tips to Get Your Pull Request Accepted
Making sure to follow the conventions!
* Your change should fit with Bukkit's goals.
* Make sure you follow our conventions to the letter.
* Check for formatting errors. They may be invisible, but [we notice.](https://hub.spigotmc.org/stash/projects/SPIGOT/repos/craftbukkit/pull-requests/298/diff)
* Provide proper JavaDocs where appropriate.
* JavaDocs should detail every limitation, caveat, and gotcha the code has.
* Provide proper accompanying documentation where appropriate.
* Test your code and provide adequate testing material and/or proof.
* For example: adding an event? Test it with a plugin and provide us with the source.
* Make sure you follow our conventions to the letter.
__Note:__ The project is often on a code freeze leading up to the release of a Minecraft update in order to give the team a static code base to work with.

93
README.md
View File

@ -2,6 +2,19 @@ CraftBukkit
======
An implementation of the [Bukkit](https://hub.spigotmc.org/stash/projects/SPIGOT/repos/bukkit) plugin API for [Minecraft](https://minecraft.net/) servers, currently maintained by [SpigotMC](http://www.spigotmc.org/).
#### Index
* [Bug Reporting](#bug-reporting)
* [Compilation](#compilation)
* [Contributing](#contributing)
* [Code Requirements](#code-requirements)
* [Applying Patches](#applying-patches)
* [Making Changes to Minecraft](#making-changes-to-minecraft)
* [Minimal Diff Policy](#minimal-diff-policy)
* [CraftBukkit Comments](#craftbukkit-comments)
* [Creating Pull Requests](#creating-pull-requests)
* [Useful Resources](#useful-resources)
Bug Reporting
-------------
The development team is very open to both bug and feature requests / suggestions. You can submit these on the [JIRA Issue Tracker](http://hub.spigotmc.org/jira/).
@ -58,25 +71,17 @@ will help to ensure the PR can be easily maintained over time and encourage the
* __Absolutely no wildcard imports.__
* If you only use an import once, don't import it. Use the fully qualified name.
For example:
```java
import java.io.ByteArrayInputStream;
import java.io.DataInputStream;
import java.io.IOException;
import java.io.UnsupportedEncodingException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.atomic.AtomicIntegerFieldUpdater;
import org.bukkit.Bukkit;
import org.bukkit.Location;
import org.bukkit.craftbukkit.CraftWorld;
import org.bukkit.craftbukkit.inventory.CraftInventoryView;
import org.bukkit.craftbukkit.inventory.CraftItemStack;
import org.bukkit.craftbukkit.util.LazyPlayerSet;
```
Any questions about these requirements can be asked in #spigot-dev in IRC.
Applying Patches
----------------
Any time new patches are created and/or updated in CraftBukkit, you need to apply them to your development environment.
1. Pull changes from CraftBukkit repo.
2. Run the `applyPatches.sh` script in the CraftBukkit directory.
- This script requires a decompile directory from BuildTools. (e.g. <BuildTools Directory>/work/decompile-XXXXXX)
3. Your development environment is now up to date with the latest CraftBukkit patches!
Making Changes to Minecraft
---------------------------
Importing new NMS classes to CraftBukkit is actually very simple.
@ -106,8 +111,10 @@ __*Key Points*__:
* __Never__ rename an existing field or method. If you want something renamed, include a ```PAIL rename``` comment
* Converting a method/class from one access level to another (i.e. private to public) is fine as long as that method is not overridden in subclasses.
* If a method is overridden in its' subclasses, create a new method that calls that method instead (along with appropriate CraftBukkit comments).
* If you can use a field to accomplish something, use that over creating a new method.
**Minimal Diff Policy**
Minimal Diff Policy
-------------------
The Minimal Diff Policy is key to any changes made within Minecraft classes. When people think of the phrase "minimal diffs", they often take it
to the extreme - they go completely out of their way to abstract the changes they are trying to make away from editing Minecraft's classes as much as possible.
@ -265,53 +272,9 @@ Otherwise, if the change is obvious, such as firing an event, then you can simpl
__Imports in Minecraft Classes__
* Do not remove unused imports if they are not marked by CraftBukkit comments.
Creating a Pull Request
-----------------------
##### Pull Request Title Example
The first line in a Pull Request(PR) message is an imperative statement briefly explaining what the PR is achieving.
If the PR fixes a bug, or implements a new feature as requested from the [JIRA](http://hub.spigotmc.org/jira/), then it should reference that ticket.
This is accomplished by simply type SPIGOT-####, where #### is the ticket number. (i.e. SPIGOT-3510).
You can reference multiple tickets in a single commit message; for example: "SPIGOT-1, SPIGOT-2" without closing punctuation.
__For Example:__
* SPIGOT-3510: Velocity broken for certain entities
* MC-111753, SPIGOT-2971: Brewing stand not reloading
As you can see, Minecraft tickets can be referenced by including the appropriate ticket number (i.e. MC-111753)
##### Pull Request Message Expectations
The body of a PR needs to describe how the ticket was resolved, or if there was no ticket, describe the problem itself.
If a PR is for both Bukkit and CraftBukkit it should include a link to the appropriate PR. [Read this to learn how to link to a PR.](https://confluence.atlassian.com/bitbucketserver053/markdown-syntax-guide-938022413.html?utm_campaign=in-app-help&utm_medium=in-app-help&utm_source=stash#Markdownsyntaxguide-Linkingtopullrequests)
##### Submitting the Changes
* Push your changes to a topic branch in your fork of the repository.
* Submit a pull request to the relevant repository in the Spigot organization.
* Make sure your pull request meets our [code requirements.](#code-requirements)
* If you are fixing a JIRA ticket, be sure to update the ticket with a link to the pull request.
* Ensure all changes (including in patches) have our Minimal Diff Policy in mind.
##### Tips to Get Your Pull Request Accepted
Making sure to follow the conventions!
* Your change should fit with Bukkit's goals.
* Make sure you follow our conventions to the letter.
* Check for formatting errors. They may be invisible, but [we notice.](https://hub.spigotmc.org/stash/projects/SPIGOT/repos/craftbukkit/pull-requests/298/diff)
* Provide proper JavaDocs where appropriate.
* JavaDocs should detail every limitation, caveat, and gotcha the code has.
* Provide proper accompanying documentation where appropriate.
* Test your code and provide material.
* For example: adding an event? Test it with a plugin and provide us with the source.
* Make sure you follow our conventions to the letter.
__Note:__ The project is on a code freeze leading up to the release of a Minecraft update in order to give the team a static code base to work with.
Creating Pull Requests
----------------------
To learn what Spigot expects of a Pull Request please view the [Contributing guidelines](CONTRIBUTING.md)
Useful Resources
----------------