CraftBukkit
Public
Commits
Doc authored and md_5 committed e6cc7c70d75
| 1 1 | CraftBukkit |
| 2 2 | ====== |
| 3 - | 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/). |
| 3 + | 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](https://www.spigotmc.org/). |
| 4 4 | |
| 5 5 | #### Index |
| 6 6 | |
| 7 7 | * [Bug Reporting](#bug-reporting) |
| 8 8 | * [Compilation](#compilation) |
| 9 9 | * [Contributing](#contributing) |
| 10 10 | * [Code Requirements](#code-requirements) |
| 11 11 | * [Applying Patches](#applying-patches) |
| 12 12 | * [Making Changes to Minecraft](#making-changes-to-minecraft) |
| 13 13 | * [Minimal Diff Policy](#minimal-diff-policy) |
| 14 14 | * [CraftBukkit Comments](#craftbukkit-comments) |
| 15 15 | * [Creating Pull Requests](#creating-pull-requests) |
| 16 16 | * [Useful Resources](#useful-resources) |
| 17 17 | |
| 18 18 | Bug Reporting |
| 19 19 | ------------- |
| 20 - | 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/). |
| 20 + | <a name="bug-reporting"></a> |
| 21 + | The development team is very open to both bug and feature requests / suggestions. You can submit these on the [JIRA Issue Tracker](https://hub.spigotmc.org/jira/). |
| 21 22 | |
| 22 23 | Compilation |
| 23 24 | ----------- |
| 24 - | CraftBukkit is a Java program which uses [Maven 3](http://maven.apache.org/) for compilation. To compile fresh from Git, simply perform the following steps: |
| 25 + | <a name="compilation"></a> |
| 26 + | CraftBukkit is a Java program which uses [Maven 3](https://maven.apache.org/) for compilation. To compile fresh from Git, simply perform the following steps: |
| 25 27 | |
| 26 28 | * Install Git using your preferred installation methods. |
| 27 29 | * Download and run [BuildTools](https://www.spigotmc.org/wiki/buildtools/) |
| 28 30 | |
| 29 31 | Some IDEs such as [NetBeans](https://netbeans.org/) can perform these steps for you. Any Maven capable Java IDE can be used to develop with CraftBukkit, however the current team's personal preference is to use NetBeans. |
| 30 32 | |
| 31 33 | Contributing |
| 32 34 | ------------ |
| 35 + | <a name="contributing"></a> |
| 33 36 | Contributions of all sorts are welcome. To manage community contributions, we use the pull request functionality of Stash. In order to gain access to Stash and create a pull request, you will first need to perform the following steps: |
| 34 37 | |
| 35 - | * Create an account on [JIRA](http://hub.spigotmc.org/jira/). |
| 36 - | * Fill in the [SpigotMC CLA](http://www.spigotmc.org/go/cla) and wait up to 24 hours for your Stash account to be activated. Please ensure that your username and email addresses match. |
| 38 + | * Create an account on [JIRA](https://hub.spigotmc.org/jira/). |
| 39 + | * Fill in the [SpigotMC CLA](https://www.spigotmc.org/go/cla) and wait up to 24 hours for your Stash account to be activated. Please ensure that your username and email addresses match. |
| 37 40 | * Log into Stash using your JIRA credentials. |
| 38 41 | |
| 39 42 | Once you have performed these steps you can create a fork, push your code changes, and then submit it for review. |
| 40 43 | |
| 41 44 | If you submit a PR involving both Bukkit and CraftBukkit, each PR should link the other. |
| 42 45 | |
| 43 - | Although the minimum requirement for compilation & usage is Java 8, we prefer all contributions to be written in Java 7 style code unless there is a compelling reason otherwise. |
| 46 + | The minimum requirement for style, compilation & usage is Java 16 unless there is a compelling reason. |
| 44 47 | |
| 45 48 | Code Requirements |
| 46 49 | ----------------- |
| 47 - | * For the most part, CraftBukkit and Bukkit use the [Sun/Oracle coding standards](http://www.oracle.com/technetwork/java/javase/documentation/codeconvtoc-136057.html). |
| 50 + | <a name="code-requirements"></a> |
| 51 + | * For the most part, CraftBukkit and Bukkit use the [Sun/Oracle coding standards](https://www.oracle.com/technetwork/java/javase/documentation/codeconvtoc-136057.html). |
| 48 52 | * No tabs; use 4 spaces instead. |
| 49 53 | * Empty lines should contain no spaces. |
| 50 54 | * No trailing whitespaces. |
| 51 55 | * No 80 character column limit, or 'weird' mid-statement newlines unless absolutely necessary. |
| 52 56 | * The 80 character column limit still applies to documentation. |
| 53 57 | * No one-line methods. |
| 54 58 | * All major additions should have documentation. |
| 55 59 | * Try to follow test driven development where available. |
| 56 60 | * All code should be free of magic values. If this is not possible, it should be marked with a TODO comment indicating it should be addressed in the future. |
| 57 61 | * If magic values are absolutely necessary for your change, what those values represent should be documented in the code as well as an explanation in the Pull Request description on why those values are necessary. |
| 58 62 | * No unnecessary code changes. Look through all your changes before you submit it. |
| 59 63 | * Do not attempt to fix multiple problems with a single patch or pull request. |
| 60 64 | * Do not submit your personal changes to configuration files. |
| 61 65 | * Avoid moving or renaming classes. |
| 62 66 | |
| 63 - | Bukkit/CraftBukkit employs [JUnit 4](http://www.vogella.com/articles/JUnit/article.html) for testing. Pull Requests(PR) should attempt to integrate within that framework as appropriate. |
| 67 + | Bukkit/CraftBukkit employs [JUnit 4](https://www.vogella.com/tutorials/JUnit4/article.html) for testing. Pull Requests(PR) should attempt to integrate within that framework as appropriate. |
| 64 68 | Bukkit is a large project and what seems simple to a PR author at the time of writing may easily be overlooked by other authors and updates. Including unit tests with your PR |
| 65 69 | will help to ensure the PR can be easily maintained over time and encourage the Spigot team to pull the PR. |
| 66 70 | |
| 67 71 | * There needs to be a new line at the end of every file. |
| 68 72 | * Imports should be organised in a logical manner. |
| 69 73 | * Do not group packages |
| 70 74 | * All new imports should be within existing CraftBukkit comments if any are present. If not, make them. |
| 71 75 | * __Absolutely no wildcard imports outside of tests.__ |
| 72 76 | * If you only use an import once, don't import it. Use the fully qualified name. |
| 73 77 | |
| 74 - | Any questions about these requirements can be asked in #spigot-dev in IRC. |
| 78 + | Any questions about these requirements can be asked in #help-development in Discord. |
| 75 79 | |
| 76 80 | Applying Patches |
| 77 81 | ---------------- |
| 82 + | <a name="applying-patches"></a> |
| 78 83 | Any time new patches are created and/or updated in CraftBukkit, you need to apply them to your development environment. |
| 79 84 | |
| 80 85 | 1. Pull changes from CraftBukkit repo. |
| 81 86 | 2. Run the `applyPatches.sh` script in the CraftBukkit directory. |
| 82 87 | - This script requires a decompile directory from BuildTools. (e.g. <BuildTools Directory>/work/decompile-XXXXXX) |
| 83 88 | 3. Your development environment is now up to date with the latest CraftBukkit patches! |
| 84 89 | |
| 85 90 | Making Changes to Minecraft |
| 86 91 | --------------------------- |
| 92 + | <a name="making-changes-to-minecraft"></a> |
| 87 93 | Importing new NMS classes to CraftBukkit is actually very simple. |
| 88 94 | |
| 89 95 | 1. Find the `work/decompile-XXXXXX` folder in your BuildTools folder. |
| 90 96 | 2. Find the class you want to add in the `net/minecraft/server` folder and copy it. |
| 91 97 | 3. Copy the selected file to the `src/main/java/net/minecraft/server` folder in CraftBukkit. |
| 92 98 | 4. Implement changes. |
| 93 99 | 5. Run `makePatches.sh` to create a new patch for the new class. |
| 94 100 | * _Be sure that Git recognizes the new file. This might require manually adding the file._ |
| 95 101 | 6. Commit new patch. |
| 96 102 | |
| 97 103 | Done! You have added a new patch for CraftBukkit! |
| 98 104 | |
| 99 105 | **Making Changes to NMS Classes** |
| 100 106 | |
| 101 107 | Bukkit/CB employs a Minimal Diff policy to help guide when changes should be changed to Minecraft and what those changes should be. |
| 102 108 | This is to ensure that any changes have the smallest impact possible on the update process whenever a new Minecraft version is released. |
| 103 109 | As well as the Minimal Diff Policy, *every* change made to a Minecraft class must be marked with the appropriate CraftBukkit comment. |
| 104 110 | At no point should you rename an existing/obfuscated field or method. All references to existing/obfusacted fields/methods should be marked with the `// PAIL rename` comment. |
| 105 - | Mapping of new fields/methods are done when there are enough changes to warrant the work. (Any questions can be asked in #spigot-dev in [IRC](https://www.spigotmc.org/wiki/irc-guide/)) |
| 111 + | Mapping of new fields/methods are done when there are enough changes to warrant the work. (Any questions can be asked in our [Discord](https://www.spigotmc.org/go/discord)) |
| 106 112 | |
| 107 113 | __*Key Points*__: |
| 108 114 | * All additions to patches must be accompanied by an appropriate comment. |
| 109 115 | * To avoid large patches, avoid adding methods where possible. We prefer making fields public over adding methods in patches. |
| 110 116 | * If you *have* to add a method to a patch, please explain why in the Pull Request description. |
| 111 117 | * __Never__ rename an existing field or method. If you want something renamed, include a ```PAIL rename``` comment |
| 112 118 | * 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. |
| 113 119 | * If a method is overridden in its' subclasses, create a new method that calls that method instead (along with appropriate CraftBukkit comments). |
| 114 120 | * If you can use a field to accomplish something, use that over creating a new method. |
| 115 121 | |
| 116 122 | Minimal Diff Policy |
| 117 123 | ------------------- |
| 124 + | <a name="minimal-diff-policy"></a> |
| 118 125 | |
| 119 126 | 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 |
| 120 127 | 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. |
| 121 128 | However, this is not what is meant by "minimal diffs". Instead, when trying to understand this policy, it helps to keep in mind its goal: to reduce the impact of changes we make |
| 122 129 | to Minecraft's internals have on our update process. |
| 123 130 | |
| 124 131 | To put it simply, the Minimal Diffs Policy simply means to make the smallest change in a Minecraft class possible without duplicating logic. |
| 125 132 | |
| 126 133 | Here are a few tips you should keep in mind, or common areas you should focus on: |
| 127 134 | |
| 195 202 | this.b(world, i, j, k, itemstack); |
| 196 203 | } |
| 197 204 | // CraftBukkit end */ |
| 198 205 | |
| 199 206 | super.remove(world, i, j, k, l, i1); |
| 200 207 | } |
| 201 208 | } |
| 202 209 | ``` |
| 203 210 | |
| 204 211 | #### CraftBukkit Comments |
| 212 + | <a name="craftbukkit-comments"></a> |
| 205 213 | |
| 206 214 | Changes to a Minecraft class should be clearly marked using CraftBukkit comments. |
| 207 215 | |
| 208 216 | * All CraftBukkit comments should be capitalised appropriately. (i.e. CraftBukkit, not CB/craftBukkit, etc.) |
| 209 217 | * If the change only affects one line of code, use an end of line CraftBukkit comment |
| 210 218 | |
| 211 219 | __Examples:__ |
| 212 220 | |
| 213 221 | If the change is obvious, then you need a simple end of line comment. |
| 214 222 | ```java |
| 267 275 | } |
| 268 276 | // CraftBukkit end |
| 269 277 | ``` |
| 270 278 | * All CraftBukkit comments should be on the same indentation level the code block it is in. |
| 271 279 | |
| 272 280 | __Imports in Minecraft Classes__ |
| 273 281 | * Do not remove unused imports if they are not marked by CraftBukkit comments. |
| 274 282 | |
| 275 283 | Creating Pull Requests |
| 276 284 | ---------------------- |
| 285 + | <a name="creating-pull-requests"></a> |
| 277 286 | To learn what Spigot expects of a Pull Request please view the [Contributing guidelines](CONTRIBUTING.md) |
| 278 287 | |
| 279 288 | Useful Resources |
| 280 289 | ---------------- |
| 290 + | <a name="useful-resources"></a> |
| 281 291 | |
| 282 292 | * [An example pull request demonstrating the things we look out for](https://hub.spigotmc.org/stash/projects/SPIGOT/repos/craftbukkit/pull-requests/365/overview) |
| 283 - | * [JIRA, our bug tracker](http://hub.spigotmc.org/jira/) |
| 284 - | * [Join us on IRC - #spigot-dev @ irc.spi.gt](https://www.spigotmc.org/wiki/irc-guide/) |
| 293 + | * [JIRA, our bug tracker](https://hub.spigotmc.org/jira/) |
| 294 + | * [Join us on Discord - #help-development](https://www.spigotmc.org/go/discord) |