BukkitDev: Project Submission Guidelines
To ensure that projects on BukkitDev are given the exposure and attention they deserve, as well as make it easier for people to find what they are looking for, we are actively enforcing a set of rules and guidelines that we expect and require every project using our service to adhere to.
Please keep in mind these are guidelines. The BukkitDev Staff have the final decision in approving or rejecting your project.
Last revision: 2014-05-21
Release binaries uploaded to your project should follow the requirements outlined below.
- Your project's name should contain the name of your project.
- Your project's description should contain a sales pitch within the first 500 or so characters, as this will be displayed on the projects listings.
- Your project's description should also contain detailed information on what your project has to offer, how to install it and use it, and so on.
- Your project should be associated with the most relevant categories to your project, with one main category and up to 4 sub-categories.
- You are expected to actively maintain your project as detailed below.
- A changelog and known issues list should be provided for every binary you upload to BukkitDev, if at all possible.
- Please be sure to read through the rest of these guidelines to make sure you understand what's expected of you.
There are several aspects of your project that you should pay attention to in order to best present it to prospective users. Taking the extra time needed to make sure your project is setup properly will make all the difference in terms of the amount of attention your project receives, the amount of support calls you'll have to manage and so on.
Project Description & Naming
Most of the projects we mark as "Changes Required" are rejected because of an unsatisfactory description.
What are the commands? What's the thing? What are the permissions? What is a "permition?" It's also a good idea to use correct grammar and nice formatting in the description.
Obviously, you don't want to name it something as ambiguous as MyPlugin.
Naming a Project
The name of your project should be the short name you chose for your plugin, i.e. MyPlugin. It should never include the version, as the project name needs to be static and not require changing. Including information about the plugin, i.e. "MyPlugin - Grow trees with ease!" in the project title is also discouraged and may cause your submission to be sent back.
You must choose a name that is not the same as or too similar to an existing project's. BukkitDev Staff may ask you to revise your project's name to eliminate confusion when searching plugins.
Describing a Project
The most important part of a project is your project's description. It is the first thing people will see when looking for and at your project. The project description should be well written, properly formatted and detailed. On BukkitDev, we pull the first 500 characters or so from your project description and display them in the project listings. As such, it is important that you include a well-written description or sales pitch within that limit so that people can see, at a glance, what your project has to offer them.
Once you have the 'sales pitch' portion of your description done, we need to focus on other important pieces of information you should be providing prospective users of your project with: what your project has to offer (a feature list), how to install and use your project's binaries, and so on. Without this information, you'll be getting a lot of un-needed support calls as people won't know how to properly make use of your work or understand what your project does.
On top of your project description, you'll want to upload a "default image" which will be displayed as a thumbnail on the searchable list of projects. Having a "default image" could very well be the element that sets your project apart from a similar one, as it shows that you take your project seriously and don't mind spending extra time and care on the presentation of your project.
Categories and What Tools You Plan On Using:
You need to decide if you want to make use of BukkitDev's provided issue trackers, wiki and forums, or if you want to offload that to something like GitHub, an external Redmine or MediaWiki installation, bearing in mind that it is more likely people will have an account on BukkitDev than any other service you want to use. You also need to decide if you want to make use of the built-in BukkitDev repository or use something like GitHub.
Whatever you decide, please be sure to set it up accordingly: some things need to be enabled on your project. So, for example, if you want to make use of the forums or issue tracker, you'll need to turn that on and set it up within your project's settings before it becomes available to anyone.
Lastly, you need to decide what main category and up to 4 sub-categories best describe your project. When deciding on this, you should take into consideration a weighting of each category in terms of how much it relates to your project and pick accordingly. Proper category choice is another aspect of the project setup we enforce to ensure everyone can find your project with ease.
A Plugin File is Required
You must accompany a new project with a plugin file for your project to be approved. If a new project has no files uploaded to the project, you may find your project sent back requiring changes. Fear not! You can add your plugin file to the project and resubmit the project for approval if this occurs. You will still be able to find your project ID when you first created your project for use in an auto updater.
Maintaining Your Project
On top of actively supporting your project, providing updates and - hopefully - adding cool new things, we expect and require that developers take a few minutes to test their binaries and name them appropriately as they upload them. As per above, we expect that the latest Recommended or Beta version (for Bukkit plugins) or the Minecraft version (for everything else) be the version selected on new file uploads.
Every so often staff will go around cleaning up the Projects List and your project might get hit and marked as inactive or unsupported if you haven't updated it within a reasonable amount of time.
Any project not adhering to these guidelines (within reason) will be unapproved until they've been updated to follow these Project Submission Guidelines.
BukkitDev provides developers with the facility to provide relevant, useful information for each binary they upload - effectively having a changelog and known issues list per binary version. We expect and require that people take advantage of this system to provide people with an idea as to what has changed between binary versions, as well as what issues you are already aware of so your issue tracker and forums are not filled with un-needed bug reports.
To get an idea of what we're looking for in terms of setting up a project properly, you can take a look at a few of these already established projects:
It's okay to have a PayPal donation button or an unshortened link to a PayPal donation page. However, there should be no obligation to donate or pay in order to use the plugin. Selling a license for your plugin or any extra service related to your plugin that requires payment is not allowed.
Downloads must come from dev.bukkit.org. BukkitDev allows for files to be marked as Alpha/Beta/Release. You can use these methods to mark your files appropriately.
Links to downloads not from BukkitDev will cause your project to be denied.
Links to downloads on BukkitDev that have not yet been approved will result in marking your project as "Changes Required." This removes your project from public view. Please wait for the approval process.
If you run a continuous integration server (such as Jenkins or Bamboo) you may provide a link to the project’s CI page for giving users up-to-the-minute updates. However, this may not be used as a replacement for your downloads and you may not prioritize these links over your BukkitDev download links. The link must be to the main CI page or the specific project’s page, not a specific version. Plugins found to be updating their CI server but not their BukkitDev downloads pages may lose the right to link to a CI server.
Downloads available from your CI server must also follow the BukkitDev submissions guidelines. BukkitDev staff may revoke your ability to link to a CI server at any time if the CI server is used to circumvent the BukkitDev submissions guidelines.
Links to a CI server must include this *exact* disclaimer (in regular sized text, not hidden, immediately before the link):
Development builds of this project can be acquired at the provided continuous integration server. These builds have not been approved by the BukkitDev staff. Use them at your own risk.
Other Things to Avoid
We'll send back projects for other reasons as well, according to these submission guidelines.
This list sums up some of the things you should check:
- URL shorteners (including, but not limited to adf.ly, bit.ly and goo.gl) are not permitted on sites under the Bukkit umbrella.
- The title of the project should not have your project's version in it.
- The description should be in English.
- You should not continue someone else's plugin without permission. We ask that the original author to sends us a message communicating that you are allowed to continue a plugin before you make a new project. We would, however, prefer if the original author added you to the original project instead. Plagiarism will not be tolerated.
- Projects should not simply be advertisements for your server.
- Again, we do not allow projects to ask for money in order to access, gain a license for, enable the full functionality of, or provide extra services for a plugin.
File submissions must also conform to the guidelines in order to be approved.
Each new file you submit has to have a title. Since you should not put the current version in your project's title, this is where it must go. File titles don't even have to have the project or plugin name in them at all, just the version. The name of the actual jarfile, however, should be static like the project. Here is an example of a well-titled file submission:
The project is Skillz; the file title is v5.5; and the file name is Skillz.jar.
On top of the name you give the file, you need to be sure to select the appropriate game version that the file is developed against. This should be the CraftBukkit recommended build or beta release that your file has been tested with. Please note: the supported version number should be within the LAST THREE Recommended Builds of CraftBukkit UNLESS there are API breakages occurring between them or a Recommended Build has been promoted pertaining to a Minecraft update.
File relationships should be used in all cases where the use of that file requires the use of another project's file. For example, if your plugin uses Vault but doesn't require it, then it would be a "Optional Dependency". If your plugin absolutely requires another plugin to work, it would be a "Required Dependency".
This allows all server admins to see which plugins require others at a quick glance.
Obfuscation of code can significantly increase time to approval for the file. If you must include obfuscation, please understand that it may take multiple days to have your file approved. If the obfuscation is too hard to read, the file may get rejected.
Including Other Plugins or Uploading Compilations
Do not include any other plugin except your own in the file you upload. Even if your plugin has dependencies, there is no reason to upload extra plugins. You should not automatically download plugin dependencies. If your plugin has a dependency on another plugin hosted on BukkitDev, provide a link to that plugin and state it is a dependency. It should be up to the server admin which plugins they want to use. Feel free to display a [INFO], [WARNING], or [SEVERE] message in the server console if your dependency is not found.
Note: You should use the "Relationships" section of your project page to state required and optional dependencies. You can mark these by using "Project Management -> Repository -> Edit Default Relationships"
Phoning home, stats collection, URLConnections and Update-checking
Any data collected about your plugin or its environment must be clearly indicated on the main page of your project; both that data is being collected and what specifically is being collected. There must be a configuration option to disable data collection, or a way for the server admin to otherwise disable this process. This applies to stats collection, error log collection, and any other data collection.
With any data collection you must state what you intend to do with that information, where it will go, and who will see it.
Any update checking or downloading done by your plugin must be clearly indicated on the main page of your project; both that updates will be checked and the configuration changes necessary to disable these checks. This applies to either simply checking for a new update or downloading new updates for the user.
Automatic Update checking & downloading
If you wish for your plugin to automatically check for updates and/or download JAR file updates, it must solely be communicating with and downloading from BukkitDev as defined below. Downloading from your Dropbox, CI, or webserver is not allowed as we cannot control what you put in it. You may not query an external website for any part of your update checking process regardless of the output of such a website (even if it currently only returns BukkitDev URLs).
If you check for updates, it must be possible to disable this check via your plugin's configuration. If you download updates, it must be possible to disable this download via your plugin's configuration. You may consolidate the control of these features to one option in your configuration provided it is possible to prevent all checking and downloading with that option. The necessary changes to your plugin's configuration to disable checking and downloading must be clearly documented on the plugin's main page as mentioned above. Use of a global (queried by multiple plugins) configuration option does not meet the above requirements.
To implement version checking and acquisition of file URLs for download, you may only utilize Curse's ServerMods API. The documentation for the API contains example code and functional example classes. You are not limited to using these classes, and may write your own code as long as it utilizes the API.
What You May Include in a File Upload
You must include in your Jarfile the compiled code and plugin.yml for your plugin to even work. It's perfectly fine to package it with source, default plugin folder(s), default configuration, a text document with your plugin's license information, and READMEs. Don't include any part of the Bukkit API as it will be available as a resource already when the plugin is used. Also, don't include libraries other than those which your plugin actually uses in some way. If your plugin hooks into another plugin, you don't need to include any part of the other plugin. The resources will be available on startup if the server has the plugin. If you do include an extra plugin for use as a library, it's considered bundling and no good. Anything else is okay as long these conditions are met:
It can't be malicious and should not be useless (you must have a reason for including it). It can't inhibit review operations done by moderators including but not limited to decompiling bytecode. You should make a note somewhere in your project that you have included it.
Some other file issues:
- You forgot to actually put your classes in the jarfile.
- You stole the plugin.
- You embedded Bukkit.
We will let you know about any of the above mistakes and give you the chance to resolve them (Except for theft).
In order to make it easier for everyone to find your project on BukkitDev, there are some guidelines we enforce to provide people with important information about your project at a glance.
Projects that are created to provide support for or security to offline mode servers will be denied unconditionally. This rule is enforced to ensure no server admin is given a false sense of security when using offline mode.
Furthermore, BukkitDev staff will not accept any project re-submitted or recreated after its denial in an attempt to redefine their plugin's intent to comply with the aforementioned rule. After a project has been denied once under this policy, the intent of the project is clear, and the author's resubmissions of the same project will be denied.
If your plugin does not work on CraftBukkit or has no functionality on CraftBukkit, it is best to be uploaded to the site where you found the mod in question.
Client/server modifications and other tools
Teams allow groups of users to work together on projects. In general, teams should follow the naming and description guidelines described for projects. Just like projects, teams are not a place to make monetary offers, advertise, link to offsite downloads, or do other things prohibited by project guidelines.
Naming a Team
The name of your team should be short and not require changing. It should not include a "motto" or any other sort of additional information. BukkitDev Staff may ask you to revise your team's name to eliminate confusion with other teams or projects. If you choose to use a project's name as part of your team, such as "MyPlugin Team", you must have ownership of that plugin.
Describing a Team
The team description should be well written, properly formatted, and provide information about your team in any easy to understand manner. Try to describe the work that the team does and any other relevant information about the team's members, background, or jobs.
If you follow these rules and everything else in the submission guidelines, you'll have no problem getting your submissions approved the first time. Bear in mind that every moderator is different; some will approve things that others may have rejected. We have to make a lot of judgement calls when approving submissions as these guidelines are just a general set of things to watch out for. By all means, reply with questions or comments!
Please keep in mind these are guidelines. The BukkitDev Staff have the final decision in approving or rejecting your project.
We'll keep working hard for you and Bukkit. Help us and yourself by following these rules and submitting top-quality plugins!