Terra/CONTRIBUTING.md

# Contributing to Terra

First off, thank you for considering contributing to Terra. It's people like you that make Terra such a great tool.

Following these guidelines helps to effectively use the time of the developers managing and developing this open source project, making it
more enjoyable for all of us.

Terra is an open source project and we love to receive contributions from our community, you! There are many ways to contribute, from
writing tutorials or blog posts, improving the documentation, submitting bug reports and feature requests or writing code which can be
incorporated into Terra.

The following is a set of guidelines for contributing to Terra and its packages, which are hosted in
the [PolyhedralDev Organization](https://github.com/PolyhedralDev) on GitHub. These are mostly guidelines, not rules. Use your best
judgment, and feel free to propose changes to this document in a pull request.

#### Table Of Contents

[Code of Conduct](#code-of-conduct)

[I don't want to read this whole thing, I just have a question!!!](#i-dont-want-to-read-this-whole-thing-i-just-have-a-question)

[Getting Started](#getting-started)

- [Your First Contribution](#your-first-contribution)
- [Reporting Bugs](#reporting-bugs)
    - [Before Submitting A Bug Report](#before-submitting-a-bug-report)
    - [How Do I Submit A (Good) Bug Report?](#how-do-i-submit-a-good-bug-report)
- [Suggesting Enhancements](#suggesting-enhancements)
    - [Before Submitting An Enhancement Suggestion](#before-submitting-an-enhancement-suggestion)
    - [How Do I Submit A (Good) Enhancement Suggestion?](#how-do-i-submit-a-good-enhancement-suggestion)
- [Pull Requests](#pull-requests)
    - [Before Submitting A Pull Request](#before-submitting-a-pull-request)
    - [How Do I Submit A (Good) Pull Request?](#how-do-i-submit-a-good-pull-request)

[Styleguides](#styleguides)

- [Git Commits](#git-commits)
    - [Committing](#committing)
    - [Git Commit Messages](#git-commit-messages)
- [Code Styleguide](#code-styleguide)
- [Documentation Styleguide](#documentation-styleguide)
    - TODO

[Coding Pratices](#coding-practices)

- [Compatibility](#compatibility)
    - [General Compatibility](#general-compatibility)
    - [Specific Compatibility](#specific-compatibility)
- [Platform-Agnostic Design](#platform-agnostic-design)
- [Data-Driven](#data-driven)

## Code of Conduct

This project and everyone participating in it is governed by the [Terra of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected
to uphold this code. Please report unacceptable behavior to [Terra global moderation team](CODE_OF_CONDUCT.md#Reporting).

## I don't want to read this whole thing I just have a question!!!

> **Note:** Please don't file an issue to ask a question. You'll get faster results by using the resources below.

We have an official discord server where you can request help from various users

- [The official PolyhedralDev discord server](https://discord.dfsek.com)

## Getting Started

### Your First Contribution

Unsure where to begin contributing to Terra? You can start by looking through "beginner" and "help wanted" issues:

- [Beginner issues](https://github.com/PolyhedralDev/Terra/labels/Note%3A%20Good%20First%20Issue) - issues which should be friendly to
  anyone new to terra.
- [Help wanted issues](https://github.com/PolyhedralDev/Terra/labels/Note%3A%20Help%20Wanted) - issues which should be a bit more involved
  than "beginner" issues.

New to github? Working on your first Pull Request? Check
out [How to Contribute to an Open Source Project on GitHub](https://app.egghead.io/playlists/how-to-contribute-to-an-open-source-project-on-github)
to get you up on your feet.

At this point, you're ready to make your changes! Feel free to ask for help; everyone is a beginner at first!

If a maintainer asks you to "rebase" your PR, they're saying that a lot of code has changed, and that you need to update your branch so it's
easier to merge.

### Reporting Bugs

This section guides you through submitting a bug report for Terra. Following these guidelines helps maintainers and the community understand
your report, and spend their time fixing the issue instead of understanding what you mean.

Before creating bug reports, please check [this list](#before-submitting-a-bug-report) as you might find out that you don't need to create
one. When you are creating a bug report, please [include as many details as possible](#how-do-i-submit-a-good-bug-report).

> **Note:** If you find a **Closed** issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one.

#### Before Submitting A Bug Report

- Join the [discord server](https://discord.dfsek.com) to help resolve simple issues.
- You must be on the LATEST version of Terra to receive any support. There is no support for older versions of Terra.
- Make sure that this is not a *specific* compatibility issue with another terrain generation mod. Do not request *specific* compatibility
  with mods or plugins (e.g. "Compatibility with TechCraft v7"). That should be implemented in an addon, **not** in the main project.
  *General* compatibility (e.g. "Ability to pull Vanilla/Modded features from parent biomes") will be considered in the main project.
- Search for any [already existing issues](https://github.com/PolyhedralDev/Terra/issues?q=is%3Aissue+) open with your problem. If you open
  a duplicate, it will be closed as such.
- Make sure that it is actually Terra causing the issue, and not another mod/plugin. You can do this by testing to see if you can recreate
  the issue without Terra installed.
- Double check that this is not an issue with a specific Terra *pack* or Terra *addon*, and instead applies to all of Terra.
- Include a copy of the latest.log file. Putting *just* the exception is not enough. We need to be able to check that there wasn't anything
  else before that caused it.
- Be sure to fill out all the required information and give descriptions of everything.

#### How Do I Submit A (Good) Bug Report?

Bugs are tracked as [GitHub issues](https://guides.github.com/features/issues/)
. [Create an issue](https://github.com/PolyhedralDev/Terra/issues/new) and provide the prerequisite information by filling in the Bug Report
template.

Explain the problem and include additional details to help maintainers reproduce the problem:

- **Use a clear and descriptive title** for the issue to identify the problem.
- **Describe the exact steps which reproduce the problem** in as many details as possible. When listing steps, **don't just say what you
  did, but explain how you did it**.
- **Provide specific examples to demonstrate the steps**.
- **Describe the behavior you observed after following the steps** and point out what exactly is the problem with that behavior.
- **Explain which behavior you expected to see instead and why.**
- **If the problem wasn't triggered by a specific action**, describe what you were doing before the problem happened and share more
  information using the guidelines below.

Include details about your configuration and environment:

- **Which version of Terra are you using?** You can get the exact version by running `/te version`.
- **What's the name and version of the platform you're using**? (eg. Spigot, Fabric, Paper, etc.)
- **Which external plugins or mods do you have installed?**
- **Which Terra packs do you have installed?** You can get that list by running `/te packs`.
- **Which Terra addons do you have installed?** You can get that list by running `/te addons`.

### Suggesting Enhancements

This section guides you through submitting an enhancement suggestion for Terra, including completely new features and minor improvements to
existing functionality. Following these guidelines helps maintainers and the community understand your suggestion and find related
suggestions.

Before creating enhancement suggestions, please check [this list](#before-submitting-an-enhancement-suggestion) as you might find out that
you don't need to create one. When you are creating an enhancement suggestion,
please [include as many details as possible](#how-do-i-submit-a-good-enhancement-suggestion).

#### Before Submitting An Enhancement Suggestion

- You must be on the **LATEST** version of Terra to make sure your feature hasn't been added yet.
- Search for any [already existing issues](https://github.com/PolyhedralDev/Terra/issues?q=is%3Aissue+) (Including closed!) with your
  problem. If you open a duplicate, it will be closed as such.
- Verify that this is actually within the scope of Terra.
- Be sure that this is not a feature request that should be made for a specific Terra *pack*, and instead applies to all of Terra.
- Be sure that this is not something that should be implemented as a Terra addon, and instead applies to all of Terra.
- Make sure that you attach a copy of the latest.log file, if there are any exceptions thrown in the console. Putting *just* the exception
  **is not enough**. We need to be able to check that there wasn't anything else before that caused it.

#### How Do I Submit A (Good) Enhancement Suggestion?

Enhancement suggestions are tracked as [GitHub issues](https://guides.github.com/features/issues/). Create an issue on our main repository
and provide the following information:

- **Use a clear and descriptive title** for the issue to identify the suggestion.
- **Provide a step-by-step description of the suggested enhancement** in as many details as possible.
- **Provide specific examples to demonstrate the steps**.
- **Describe the current behavior** and **explain which behavior you expected to see instead** and why.
- **Explain why this enhancement would be useful** to most Terra users and isn't something that can or should be implemented as an addon.

### Pull Requests

This section guides you through submitting a pull request for Terra.

While the prerequisites above must be satisfied prior to having your pull request reviewed, the reviewer(s) may ask you to complete
additional design work, tests, or other changes before your pull request can be ultimately accepted.

#### Before Submitting A Pull Request

- You must be on the **LATEST** version of Terra to make sure your feature hasn't been added yet.
- Search for any [already existing issues](https://github.com/PolyhedralDev/Terra/issues?q=is%3Aissue+) (Including closed!) with your
  problem. If you open a duplicate, it will be closed as such.
- Verify that this is actually within the scope of Terra.
- Be sure that this is not a feature request that should be made for a specific Terra *pack*, and instead applies to all of Terra.
- Be sure that this is not something that should be implemented as a Terra addon, and instead applies to all of Terra.
- Make sure that you attach a copy of the latest.log file, if there are any exceptions thrown in the console. Putting *just* the
  exception **is not enough**. We need to be able to check that there wasn't anything else before that caused it.

#### How Do I Submit A (Good) Pull Request?

Pull Requests are tracked as [GitHub Pull Requests](https://guides.github.com/activities/forking/#making-a-pull-request). Create a pr on our
main repository and provide the following information:

- **Use a clear and descriptive title** to identify the pull request.
- **State what this pull request adds/fixes**.
- **Be sure that you are the owner of the code you contributed** or that it can be licensed under the GPLv3.
- **Provide a description goals and non-goals of the pull request** in as many details as possible.
- **Describe the current behavior** and **explain which behavior you expected to see instead** and why.
- **Explain why this enhancement would be useful** to most Terra users and isn't something that can or should be implemented as an addon.

## Styleguides

### Git Commits

Following this is not mandatory, but rather a set of guidelines. As long as your commit messages aren't absolutely awful, it's probably
fine. But it would be nice if you followed them.

#### Committing

When you commit code, try to avoid committing large amounts of code in a single go. Splitting up code into smaller commits is much nicer and
makes it easier to trace a feature to a single commit.

Try to stick to one feature/fix/etc. per commit. A good rule of thumb is if you need to use the word "and" in the subject line, then it
should probably™ be two commits.

#### Git Commit Messages

- Subject line must fit the following format: `<type>: <short summary>`. Type must be one of the following:
    - Build: Changes that affect the build system or external dependencies.
    - Docs: Documentation only changes.
    - Feat: A new feature.
    - Fix: A bug fix.
    - Perf: Performance improvements.
    - Refactor: Refactoring sections of the codebase.
    - Repo: Changes to the repository structure that do not affect code. (Eg. modification of the `README.md` file, etc.)
    - Revert: Revert a previous commit.
    - Style: Code style updates.
    - Test: Anything related to testing.
    - Trans: Translation and localization of Terra to other languages.
    - WIP: Work in progress.
- Separate the subject line from the body with a single blank line.
- Do not end subject line with a period.
- Limit the subject line to 50 or less.
- The subject line and all body lines should be in sentence case.
- Use the present tense. ("Add feature" not "Added feature")
- Use the imperative mood. ("Move cursor to..." not "Moves cursor to...")
- Reference relevant issues and pull requests in the body.

>
> Here is a template you can follow:
> ```
> Capitalized, short (50 chars or less) summary
>
> More detailed explanatory text, if necessary. Wrap it to about 72
> characters or so. In some contexts, the first line is treated as
> the subject of the commit and the rest of the text as the body. The
> blank line separating the summary from the body is critical (unless
> you omit the body entirely); various tools like `log`, `shortlog` and
> `rebase` can get confused if you run the two together.
>
> Explain the problem that this commit is solving. Focus on why you are
> making this change as opposed to how (the code explains that). Are
> there side effects or other unintuitive consequences of this
> change? Here's the place to explain them.
>
>
> Further paragraphs come after blank lines.
> - Bullet points are okay, too
> - Typically a hyphen or asterisk is used for the bullet, followed
>   by a single space, with blank lines in between, but conventions vary
>   here
> - Use a hanging indent
>
> Reference any relevant issues at the bottom, like so:
>
> Resolves: #123
> See also: #456, #789
> ```

### Code Styleguide

Use an IDE with support for `.editorconfig` files. There is an included editorconfig file in the base of the project so that your IDE should
automatically use the correct code style settings.

### Documentation Styleguide

TODO

## Coding Practices

### Compatibility

#### General Compatibility

General compatibility (example: injection of Vanilla structures/features/carvers into packs) is acceptable in the main project.

- General compatibility features should be *disabled by default*. Having things auto-injected causes unpredictable behaviour that is
  annoying to diagnose. General-compatibility options should have config values attached which are disabled by default.
- These config options should also be *simple to use*. Think of the people who will be using these compatibility options. They want to flick
  a switch and have things be compatible. That means that a majority of compatibility options should stay in `pack.yml`, to make it simple
  to go into a pack and turn on specific compatibilities. This does *not* mean that more advanced compatibility options are off the table,
  for example, look at Feature compatibility, where features can either be automatically injected, *or* configured individually per Terra
  biome, depending on how much control the user wants.

#### Specific Compatibility

Specific compatibility should *not* be put in the main project. (Example: Adding the ability to generate TechCraft v7's doo-dads with a
TerraScript function)

Having specific compatibilities leads to tons of extra dependencies to keep track of, as well as adding lots of additional stuff to
maintain. It quickly becomes a mess. Especially when most users will never need to use this feature.

We have designed an addon API for exactly this purpose. **Specific compatibilities are welcome and encouraged, in the form of addons.**

### Platform-Agnostic Design

Terra must, at all times, remain platform agnostic. This means it must be able to run on theoretically any voxel based platform. Including
non-minecraft games like Terasology.

When adding a new feature to `common`, make no assumptions about what platform it'll be running on.

Examples:

- Don't assume the world height is 256.
- Don't assume that a specific block, item, or entity exists. (Eg. don't assume there exists a block called `minecraft:grass_block`)

### Data-Driven

When adding a new feature, make it abstract. Don't make assumptions about "specific use cases." If you can only think of a few use cases,
your idea should probably be generalized.

You must use configs effectively. Make configs that are *powerful* but also *make sense* and are \[easy\] to use.