diff options
| -rw-r--r-- | CONTRIBUTING.md | 51 | ||||
| -rw-r--r-- | README.md | 93 |
2 files changed, 79 insertions, 65 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..4e3513bc --- /dev/null +++ b/CONTRIBUTING.md @@ -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. @@ -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 ---------------- |