Skip to content

Contributing

Jump to bottom
Jerom van der Sar edited this page Aug 10, 2017 · 27 revisions
Last changed 2017-08-07

TotalFreedomMod is a Minecraft server plugin for CraftBukkit/Spigot servers. It provides the means to grant players many more freedoms than usually possible within Minecraft server communities. In particular, TotalFreedomMod (TFM) allows players to become 'operator' (OP) without providing unrestricted access to damage the server. TFM was originally designed for the TotalFreedom Minecraft Server, but has since grown to support dozens of online communities by providing increased player freedom.

For those who wish to contribute, we encourage you to fork the repository and submit pull requests. Below you will find guidelines that explain this process in further detail.

Quick Guide

  1. Come up with an idea for a feature or find a bug.
    • If your proposed change is a new feature, ensure your change fits TotalFreedomMod's goals.
  2. Find your issue on the issue tracker.
    • If a similar issue does not exist, make one.
    • Before continuing, Ensure your change meets the pull request requirements.
    • If your change does not meet the pull request requirements, it may be closed without notice.
    • Keep in mind that you will need to sign a Contributor License Agreement.
  3. Fork TotalFreedomMod, if you have not done so already.
  4. Make a branch dedicated to your change.
  5. Edit TotalFreedom's source.
    • Before continuing, ensure that the entire issue is addressed.
    • Before continuing, ensure that the code meets the code requirements.
  6. Commit your change according to the committing guidelines.
  7. Push your branch and submit a pull request.

Getting Started

  1. Search the issue tracker for your bug report or feature request.
  2. If the issue does not exist already, create it.
    • Clearly describe the issue.
    • If your issue is a bug, describe the steps needed to reproduce it.
    • If your issue is a feature request, ensure it fits TotalFreedomMod's goals and describe your feature in detail.
  3. Fork the repository on GitHub.

Does the change fit TotalFreedomMod's goals?

As a rough guideline, ask yourself the following questions to determine if your proposed change fits the TotalFreedomMod project's goals. Please remember that this is only a rough guideline and may or may not reflect the definitive answer to this question.

  • Is the change in line with the principles of "Minecraft freedom"? Players should enjoy an experience of freedom. We do not normally make changes that restrict players unless absolutely necessary.

  • Does the change bypass or impair other TotalFreedomMod features already present? If so, it might be better to improve that feature instead?

  • Does the change add a feature that involves micromanagement? Pull requests that involve adding a micromanagement feature will likely not be accepted. This includes shorthands for multiple commands.

  • Is a similar feature already present? Features that have very similar alternatives will not be added. For example, a command that temporarily bans a player from the server is very similar to the /tban command and thus will likely not be accepted.

Pull Request Requirements

Due to a lot of pull requests, and the effort it takes to review each PR, some requirements for pull requests have been imposed. PRs opened that do not meet the pull request requirements may be closed.

  • PRs must only address issues which are marked as "accepted".
  • PRs must only address one issue per PR, not several.
  • PRs must not solely be grammar fixes, config-edits, small changes (less than 10 lines of code) or message rephrasing edits. Small edits such as these take very little effort to make and a lot more effort to review and integrate into the codebase.
  • PRs must be compiled and tested before they are submitted. If your PR does not function or has clearly not been tested, it may be closed without notice.

Making Changes

  • Create a topic branch from where you want to base your work.
    • This is usually the main development branch. (i.e. devel) See Development Process for more information.
    • Name your branch something relevant to the change you are going to make.
    • To quickly create a topic branch based on a base branch, use git checkout <basebranch> followed by git checkout -b <newbranch>. Avoid working directly on the devel branch.
  • Make sure your change meets our code requirements.

Code requirements

  • Code must be written in Allman style, should follow Java Code Conventions.
  • No tabs; use 4 spaces for indentation.
  • No trailing whitespaces for code lines, comments or configuration files.
  • No CRLF line endings, only LF is allowed.
    • For Windows-based machines, you can configure Git to do this for your by running git config --global core.autocrlf true.
    • If you are running a Linux or Mac OSX, you should run git config --global core.autocrlf input instead.
    • For more information about line feeds. See this this article.
  • No 80 character line limit or 'weird' mid-statement newlines.
  • Additions should be compiled, complete and tested before committing.
  • Avoid using org.bukkit.Server.dispatchCommand(). Changes that make use of it will likely be rejected.
  • Files must always end with a newline.
  • Avoid nested code structures.

Committing your changes

  • Check for unnecessary whitespace with git diff --check before committing.
  • Make sure your commit compiles before committing.
  • Describe your changes in the commit description.
  • For a prolonged description, please add continue on the full description.
  • The first description line should be one sentence and should not exceed 10 words.

Example commit message

Fixed bugs with /saconfig clear. Admins can now use /saconfig clear [ip] to remove the designated IP (only their own IPs can be removed. They can also simply use /saconfig clear to remove all IPs but the current one. /saconfig clear is safe, meaning you can not remove your current IP or an IP that does not belong to you.

Submitting Your Changes

  • Push your changes to the topic branch in your fork of the repository.
  • Submit a pull request to this repository.
    • Explain in detail what each one of your commits changes and point out any big changes.
  • Wait as a developer evaluates your changes. You will likely be asked to address some issues with your code. Don't be alarmed, this is part of the process.
  • Do not add any prefixes or tags.

Tips - How To Get Your Pull Request Accepted

  • Please make sure your changes are written such as other features would be. For example, commands have their own class and extend FreedomCommand.
  • Do not increment the version number.
  • Please avoid having to add files in the main namespace where possible.
  • Please refrain from using an excessive amount of commits. As few as possible is generally the best.
  • Please do not spread your contribution over several pull-requests.

Additional Resources

TotalFreedom is not affiliated with Bukkit or Mojang in any way. All rights belong to their respective owners.

TotalFreedomMod is licensed under the TotalFreedom General License

Clone this wiki locally