This guide covers what the project is and the many ways you can get involved with helping us build and improve the Bukkit project and its community.
After reading this guide, you should be familiar with:
- What the Bukkit project is.
- How to help out with development within the project if you are a programmer.
- How to help out with improving and maintaining the documentation (JavaDoc) for our API if you are a technical writer.
What is Bukkit?
Bukkit is an open-source and completely free Minecraft server modification that provides developers with the tools they need to extend the functionality of the standard Minecraft server. Through the creation of programs known as plugins, developers have the ability to add, remove or change Minecraft functionality at will. These modifications can range from admin tools that make managing a Minecraft server easier to adding entirely new features to the Minecraft server. As well as providing these tools (which are an API for plugins to be built upon), the Bukkit server often contains improvements, optimisations and bug fixes on top of the Minecraft server provided by Mojang.
There are two important aspects of the Bukkit project: Bukkit and CraftBukkit.
Bukkit is the API with which plugins are developed, while CraftBukkit is a modified Minecraft server with the Bukkit API included inside of it in order for Bukkit plugins to be able to run on it. If you're looking to run a server, CraftBukkit is what you'll want to run. If you're looking to develop plugins, you do so using Bukkit.
Programmers: Help us develop Bukkit (and CraftBukkit)
Bukkit is an open-source project which spans across a multitude of different Git repositories all under the Bukkit GitHub organisation. In order to contribute to the project as a programmer, you'll need a free GitHub account to be able to fork the appropriate repositories and submit pull requests to them.
The two main repositories are Bukkit and CraftBukkit and they're generally the repositories that you'll be working with to contribute to the project. As explained above, Bukkit is the API and CraftBukkit is our implementation of the API inside of the Minecraft server. However, if you're looking to contribute to the API, there is a chance that the file you'll need to edit is not imported by the project already, in which case you'll need to import it from the mc-dev repository.
Technical Writers: Help us improve the Bukkit API documentation (JavaDocs)
A programming API is only useful and powerful if it has properly written and maintained documentation to help you use it. While we try our best to include well written JavaDocs whenever it is called for in our commits, there is always room for improvement of our documentation. If you're the type of person who enjoys writing documentation and is able to understand how code works, you'll fit right in with improving our API documentation.
In order to contribute to the documentation of our API, you'll need a (free) GitHub account which you'll use to submit your JavaDoc contributions to our project. When contributing to the JavaDocs for our API, all you need is access to a web browser so you can use the GitHub interface to directly edit files. Simply fork the Bukkit-JavaDoc repository on GitHub and use the file editor on GitHub's website to edit the file you need that contains the API you want to document.
Bukkit primarily follows Oracle's guidelines for writing and formatting JavaDocs, however here are a few Bukkit specific rules to keep in mind:
- No trailing spaces at the end of lines
- Wrap long lines at 78 characters. Make it look nice.
- code blocks inside JavaDoc comments follow Bukkit code conventions.
- For @param @return and @throws tags, the description follows on the same line wrapped lines should be indented
- We do not use the following tags
- You must not deprecate any methods
Remeber: JavaDoc comments should never consist only of the information that is provided by reading the signature of the method it is documenting.
Contributing to the Bukkit API documentation is simple, first navigate to the Bukkit-JavaDoc repository, navigate to the file you wish to edit, make your changes and submit them.
As an example, here I have navigated to the file Event.java:
Click on the “Edit” button to begin editing the file. You will note that GitHub will automatically fork the repository for you, so you don’t need to understand or do anything with Git to make changes:
This will bring you to the file editor where you can make your changes:
Here I am making a few changes to the Event.java file, adding in some spacing that should be present, but is not:
Note: Be careful with the editor, in this instance it automatically added a space after the * on the new line I made, but that has to be removed to fit the guidelines!
Next, Click on “Preview” to see the total changes you have made, and make sure you've only changed what you meant to:
Scroll down and give your changes a short description about what you've changed, then click “Propose File Change”:
Finally, review your Pull Request, then click “Send pull request”:
And that’s it, you are done!