Contributing to Treasury

This page is complete and is valid as of Treasury v2.0.0.

About

Treasury is a community project. Code contributions can help make Treasury better for every server owner and plugin utilizing the resource.

Contributions are done through pull requests on this GitHub repository.

All contributors are attributed for their work: in the code, and in documentation.

Things to Know

Please follow the Process below. We can't accept all contributions, as we maintain a high development standard for Treasury to keep it a great, stable resource. For example, we are strictly against bloating the resource, and we have a list of guidelines which PRs must follow in order to be merged. We always suggest you ask the Treasury maintainers first before starting work on any contributions to ensure it isn't a waste of time.

Process

• Ask Treasury's maintainers if your contribution idea is worth working on.
  • Usually, opening an issue that describes your idea is the best way to go, as contributors can also comment on it.
• If people say it sounds good, fork Treasury's repository and begin your work.
• Check the guidelines below, ensure you follow them throughout your code.
• Do a last check-up to make sure it follows the guidelines. It saves us a lot of time.
• Push all of your commits to your fork's repository.
• Submit a pull request to Treasury's repository.
• Mark your pull request as a draft if it is not complete. Otherwise, we will expect that it is ready to be merged as-is.
• Respond and act to the feedback and comments on your PR. One or more Treasury maintainers will take a look at your PR as well. It will either be merged or closed in the future.

Guidelines

Star imports

Don't use star imports - disable them in your IDE. For example, this is what not to do:

import org.bukkit.*;

Curly braces in if-else statements

For if-else statements, you must use curly braces ({ and }) in its structure. For example, this is what not to do:

if(shouldDoSomething)
  doSomething();
else
  dontDoSomething();

Starting curly braces on the same line

With very few exceptions, starting curly braces should not be on its own line. For example, this is what you should do:

if(true) {
  hello();
}

This is what you should not do:

if(true)
{
  hello();
}

Javadocs

If you are going to write a new API addition, you 100% need to document it, including an @author and @since other than the already required @param for all parameters and @return if the method's gonna return any data. The @since tag should include a {@link to the specific API version e.g. if you're going to add something to the Economy API, your @since would be `@since {@link EconomyAPIVersion#v1_0 v1.0}.

Example (not written inside an IDE so it is not particularly ideal):

/**
* Retrieves the {@link Foo} data of this {@code Something}
* 
* @param subscription the {@link EconomySubscriber} accepting the {@link Foo} data
* @author MrIvanPlays
* @since {@link EconomyAPIVersion#v1_0 v1.0}
*/
void retrieveFooData(EconomySubscriber<Foo> subscription);

If you need a code example in a javadoc, you should use the <pre> tag.

/**
* Retrieves the {@link Foo} data of this {@code Something}
* <p>
* An example of how you should handle {@code Foo} data: 
* <p>
* <pre>
*    retrieveFooData(new EconomySubscriber<Foo>() {
*        @Override
*        public void succeed(Foo foo) {
*            foo.requiredToCall();
*            // ...
*        }
*        // failure method
*        // ...
*    });
* </pre>
* @param subscription the {@link EconomySubscriber} accepting the {@link Foo} data
* @author MrIvanPlays
* @since {@link EconomyAPIVersion#v1_0 v1.0}
*/
void retrieveFooData(EconomySubscriber<Foo> subscription);

If you are modifying an already existing method, you might want to add yourself as an author e.g

/**
// ...
* @author MrIvanPlays, YourNameHere
*/
// ...

Automatic refactoring

Do not blindly allow your IDE to automatically fix warnings in the resource. Some things are meant to be but your IDE will complain about it, such as config variables which are not final on purpose.

Do not use Reformat Code or Rearrange Code in IntelliJ! (Or equivalent in other IDEs.) Definitely use Optimize Imports if you're sure it's choosing the correct imports (check before you commit).

Treasury includes a .editorconfig for IntelliJ, but that won't stop IntelliJ from refactoring some stuff if you use Rearrange Code or some other stuff other than Ctrl + Alt + L.

Is that all!?

Not really - it's unfeasible for us to cover every single thing, so we're adding entries as we spot them. So long you're using common sense + standard Java programming principles such as camelCase for method names etc, there is a very low chance your code will have any problems here.