Draft of Glowstone contributing & PR handling guidelines

CONTRIBUTING.md

Contributing to Glowstone

Glowstone is a lightweight, open source Minecraft server written in Java. For those who wish to contribute, we encourage you to fork the repository and submit pull requests. Below you will find guidelines that will explain this process in further detail.

Quick Guide

1. Create or find an issue on the issue tracker.
2. Fork Glowstone if you haven't done so already.
3. Create a branch dedicated to your change.
4. Write code addressing your feature or bug.
5. Commit your change according to the committing guidelines.
6. Push your branch and submit a pull request.

Getting Started

• Find an issue to fix or a feature to add.
• Search the issue tracker for your bug report or feature.
• Large changes should always have a separate issue to allow discussion.
  • If your feature or bug incorporates a large change, file a new issue, so the feature and its implementation may be tracked separately. This way, the nature of the issue may be discussed before time is spent addressing the issue.
• Fork the repository on GitHub.

Making Changes

• Create a topic branch from where you want to base your work.
  • This is usually the master branch.
  • Name your branch something relevant to the change you are going to make.
  • To quickly create a topic branch based on master, use git checkout master followed by git checkout -b <name>. Avoid working directly on the master branch.
• Make your best effort to meet our code style guidelines.
• Changes should generally be future-proof and not strongly tied to details that may change in a future Minecraft version.
• Large changes should be documented by the appropriate javadocs if applicable.

Committing your changes

• Check for unnecessary whitespace with git diff --check before committing.
• Describe your changes in the commit description.
• For a prolonged description, continue on a new line.
• If your change addresses an open issue, include in the first line one of:
  • For a bug-related issue: "Fixes #NNN".
  • For a feature request: "Resolves #NNN".

Example commit message:

Changed wgen to treat 128 as world height in all cases (fixes #151).

Submitting Your Changes

• Push your changes to the topic branch in your fork of the repository.
• Submit a pull request to this repository.
  • Be concise and to the point with your pull request title.
  • Explain in detail what your changes are and the motives behind them.
  • If your PR is not finished, but you are looking for review anyway, prefix title with [WIP].
• Await peer review and feedback.
• Revise PR based on feedback.

How to get your pull request accepted

• Ensure your change does not solely consist of formatting changes.
• Be concise and to the point in your pull request title.
• Address your changes in detail. Explain why you made each change.
• The code must be your work or you must appropriately credit those whose work you have used.

Additional Resources

• Bug tracker
• General GitHub documentation
• GitHub pull request documentation
• IRC: #glowstone (general) and #glowstonedev (development) on EsperNet

PR Handling.md

See PR Handling.

How the process sort of should go:

1. Contributor submits a PR (or, developer starts PR from feature branch). Ideally, there is one commit at this point, but this is not mandatory.
2. If the PR isn't complete, but early feedback is desired, precede title with [WIP].
3. Feedbackt on the PR takes place by PR handlers, maintainers (i.e. Space), and community devs.
4. More commits are pushed to the PR as work is done. Rebasing to master occurs at submitter's discretion.
5. Eventually, submitter & handler/community seem to agree PR is complete.
6. PR is rebased to master and squashed to one commit with a descriptive commit message.
7. The commit is merged (fast-forward or cherry-pick only - merge commits are evil).

General thoughts:

• PRs which implement some discrete chunk of a feature (e.g. Cows) but not the whole feature (e.g. all Animals) are acceptable.
• PRs which are intended to improve performance should only be accepted if there is evidence they succeed at doing so.
• PRs which fix bugs are acceptable.
• PRs which only change whitespace or styling are usually not accepted.
• If PR submitter disappears for too long (how long?) PR is closed. It may be reopened by submitter.
• If a PR is determined to be making a change which is not desirable, and the submitter does not wish to fix, it is closed.

I'm liking everything mentioned here. I personally prefer people to keep a single commit in their PRs, --forcing as necessary. Any commits after comments are left. Just my 2c. Another point is be sure that commit messages are professional and aren't nonsensical.