doc: add conventional commits to contributing guidelines (#4410)
Tobias Nett
GitHub
parent
ddf6c7799e
commit
077020fa31
|
|
@ -1,5 +1,4 @@
|
|||
Contributing to Terasology
|
||||
==================================
|
||||
# Contributing to Terasology
|
||||
|
||||
If you would like to contribute code, documentation, or other assets you can do so through GitHub by forking the repository and sending a pull request (PR). You can also simply report issues (bugs), but please search for any previous reports first.
|
||||
|
||||
|
|
@ -7,8 +6,8 @@ If you would like to contribute code, documentation, or other assets you can do
|
|||
|
||||
Read on for an overview and [check the wiki for more details](https://github.com/MovingBlocks/Terasology/wiki). For questions please join us in our [forum](http://forum.terasology.org/forum/) or on `#terasology` (irc.freenode.net).
|
||||
|
||||
File an Issue
|
||||
-------------
|
||||
## File an Issue
|
||||
|
||||
You can report bugs and feature requests to [GitHub Issues](https://github.com/MovingBlocks/Terasology/issues). As mentioned please look for a similar existing issue before submitting a new one.
|
||||
|
||||
For finding easy to do issues to start with look at the [Good First Issue](https://github.com/MovingBlocks/Terasology/labels/Good%20First%20Issue) issues.
|
||||
|
|
@ -17,40 +16,105 @@ We prefer questions and support requests be posted in the [forum](http://forum.t
|
|||
|
||||
__Please provide as much information as possible to help us solve problems and answer questions better!__
|
||||
|
||||
Commits and Commit Messages
|
||||
---------------------------
|
||||
Follow these guidelines when creating public commits and writing commit messages.
|
||||
## PR Title / Commit Message Guidelines
|
||||
|
||||
1. If your work spans multiple local commits make sure they can be merged directly into the target branch. If you have some commit and merge noise in the history have a look at git-rebase. Ideally, every commit should be able to be used in isolation -- that is, each commit must build and pass all tests.
|
||||
1. The first line of the commit message should be a descriptive sentence about what the commit is doing. It should be possible to fully understand what the commit does by just reading this single line.
|
||||
1. **Optional:** Following the single line description (ideally no more than 70 characters long) should be a blank line followed by a list with the details of the commit.
|
||||
1. **Optional:** Add `Fix/Fixing/Fixes/Close/Closing/Refs #issue` if you want to mark the issue mentioned as complete in the issue tracker when the change is merged.
|
||||
We try to follow the [conventional commits](https://www.conventionalcommits.org/en/v1.0.0-beta.2/) style for commit messages and pull request titles.
|
||||
This leads to **more readable messages** that are easy to follow when looking through the **project history**.
|
||||
But also, we use the git commit messages to **generate the Terasology change log**.
|
||||
|
||||
### Commit Message Format
|
||||
Each commit message consists of a **header**, a **body** and a **footer**. The header has a special
|
||||
format that includes a **type**, a **scope** and a **subject**:
|
||||
|
||||
```
|
||||
<type>(<scope>): <subject>
|
||||
<BLANK LINE>
|
||||
<body>
|
||||
<BLANK LINE>
|
||||
<footer>
|
||||
```
|
||||
|
||||
The **header** is mandatory and the **scope** of the header is optional.
|
||||
|
||||
Any line of the commit message cannot be longer 100 characters! This allows the message to be easier
|
||||
to read on GitHub as well as in various git tools.
|
||||
|
||||
The footer should contain a [closing reference to an issue](https://help.github.com/articles/closing-issues-via-commit-messages/) if any.
|
||||
|
||||
Samples: (even more [samples](https://github.com/angular/angular/commits/master))
|
||||
|
||||
```
|
||||
doc(changelog): update changelog to beta.5
|
||||
```
|
||||
```
|
||||
fix(release): need to depend on latest rxjs and zone.js
|
||||
|
||||
The version in our package.json gets copied to the one we publish, and users need the latest of these.
|
||||
```
|
||||
|
||||
### Revert
|
||||
If the commit reverts a previous commit, it should begin with `revert: `, followed by the header of the reverted commit. In the body it should say: `This reverts commit <hash>.`, where the hash is the SHA of the commit being reverted.
|
||||
|
||||
### Type
|
||||
Must be one of the following:
|
||||
|
||||
* **build**: Changes that affect the build system or external dependencies (example scopes: gradle, git, idea)
|
||||
* **ci**: Changes to our CI configuration files and scripts (example scopes: Jenkins)
|
||||
* **doc**: Documentation only changes
|
||||
* **feat**: A new feature
|
||||
* **fix**: A bug fix for the game
|
||||
* **perf**: A code change that improves performance of the game
|
||||
* **refactor**: A code change that neither fixes a bug nor adds a feature
|
||||
* **style**: Changes that do not affect the meaning of the code (white-space, formatting, copyright, etc)
|
||||
* **test**: Adding missing tests or correcting existing tests
|
||||
|
||||
### Scope
|
||||
The scope is optional.
|
||||
It should describe the area of the code base this change affects.
|
||||
For instance, it may be the name of the package(s) affected (as perceived by the person reading the changelog generated from commit messages).
|
||||
The package prefix `org.terasology` should be ommitted.
|
||||
|
||||
Samples:
|
||||
```
|
||||
feat(world): add JOML API to WorldProvider
|
||||
|
||||
fix(block/family): fix off-by-one error in block placement
|
||||
|
||||
build(gradle): migrate all scripts to Kotlin
|
||||
```
|
||||
|
||||
### Subject
|
||||
The subject contains a succinct description of the change:
|
||||
|
||||
* use the imperative, present tense: "change" not "changed" nor "changes"
|
||||
* don't capitalize the first letter
|
||||
* no dot (.) at the end
|
||||
|
||||
### Body
|
||||
Just as in the **subject**, use the imperative, present tense: "change" not "changed" nor "changes".
|
||||
The body should include the motivation for the change and contrast this with previous behavior.
|
||||
|
||||
### Footer
|
||||
The footer should contain any information about **Breaking Changes** and is also the place to
|
||||
reference GitHub issues that this commit **Closes**.
|
||||
|
||||
**Breaking Changes** should start with the word `BREAKING CHANGE:` with a space or two newlines. The rest of the commit message is then used for this.
|
||||
|
||||
A detailed explanation can be found in this [document][commit-message-format].
|
||||
|
||||
## License
|
||||
|
||||
License
|
||||
-------
|
||||
Submissions must be licensed under the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.html).
|
||||
|
||||
If you are adding a new file it should have a header like this (automatically available as a template in IntelliJ):
|
||||
~~~
|
||||
/*
|
||||
* Copyright 2016 MovingBlocks
|
||||
*
|
||||
* Licensed under the Apache License, Version 2.0 (the "License");
|
||||
* you may not use this file except in compliance with the License.
|
||||
* You may obtain a copy of the License at
|
||||
*
|
||||
* http://www.apache.org/licenses/LICENSE-2.0
|
||||
*
|
||||
* Unless required by applicable law or agreed to in writing, software
|
||||
* distributed under the License is distributed on an "AS IS" BASIS,
|
||||
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
* See the License for the specific language governing permissions and
|
||||
* limitations under the License.
|
||||
*/
|
||||
~~~
|
||||
|
||||
How to Submit a Pull Request
|
||||
----------------------------
|
||||
```java
|
||||
// Copyright 2021 The Terasology Foundation
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
```
|
||||
|
||||
## How to Submit a Pull Request
|
||||
|
||||
Pull requests are highly appreciated! Please follow the simple guidelines below.
|
||||
|
||||
1. Fork the repository to your personal GitHub account.
|
||||
|
|
@ -63,8 +127,8 @@ Pull requests are highly appreciated! Please follow the simple guidelines below.
|
|||
|
||||
__Please note:__ if you want to change multiple things that don't depend on each other, make sure you create a new branch off the main develop branch before making more changes - that way we can take in each change separately.
|
||||
|
||||
How to Merge a Pull Request
|
||||
---------------------------
|
||||
## How to Merge a Pull Request
|
||||
|
||||
For trusted contributors with push access to our root repos you are welcome to help merge pull requests.
|
||||
|
||||
1. Consider what scope is suitable for the change being PRed.
|
||||
|
|
|
|||
Loading…
Reference in New Issue