Skip to content

Commit

Permalink
docs: enhance contributing guidelines
Browse files Browse the repository at this point in the history
docs: add git-branching diagram

- add git workflow instructions
- add branching strategy
- add instruction for git squashing

docs: don’t scare off potential contributors

because:
- having to open a GitHub issue first every time could prevent
contributors to make the effort of submitting their thoughts

this commit:
- removes the respective paragraph in the `CONTRIBUTING.md`

docs: change GitHub issue template

because:
- we want a consistent formatting with our commit guidelines

this commit:
- changes the `.github` template files accordingly and
- adjusts the docs in the `CONTRIBUTING.md` file

style: improve wording

docs: clarify prefered way to offer help
  • Loading branch information
csshugs committed Feb 3, 2020
1 parent b438492 commit 50273b4
Show file tree
Hide file tree
Showing 7 changed files with 88 additions and 5 deletions.
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/bug_report.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
name: Bug report
about: Create a report to help us improve
title: "[Bug] <enter name of bug here>"
title: "bug: <enter name of bug here>"
labels: bug
assignees: ''
---
Expand Down
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/feature_request.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
name: Feature request
about: Suggest an idea for this project
title: "[Feature] <enter name of new feature here>"
title: "feat: <enter name of new feature here>"
labels: feature
assignees: ''
---
Expand Down
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/improvement.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
name: Improvement
about: Tell us what can be done better
title: "[Improvement] <enter name of improvement here>"
title: "improvement: <enter name of improvement here>"
labels: improvement
assignees: ''
---
Expand Down
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/question.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
name: Question
about: Ask about FluidMS and what might be unclear in its usage
title: "[Question] <enter your question here>"
title: "question: <enter your question here>"
labels: question
assignees: ''
---
Expand Down
84 changes: 83 additions & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,50 @@

This document provides a collection of rules and guidelines that need to be adhered to when working with or contributing to FluidMS.

## Commit guidelines
## Git workflow

### Creating a GitHub issue

For issues, please adhere to the following formatting of the issue title:

```
<type>: <description of the issue>
```

`<type>` can be one of the following:

- `bug`
- `feat`
- `improvement`
- `question`

**Example:**

```
feat: add new testing tool
```

### Branching strategy

Any work is performed on dedicated feature branches. This work is lead back to our `develop` base branch via pull requests. The `master` branch is our release and stable branch.

![Diagram showing our Git branching strategy](git-branching.png)

If you create a new branch, stick to the following naming convention:

```
<branch-type>/<GitHub-issue-number>/<branch-title>
```

`<branch-type>` can be any type that is also [allowed for commit types](#user-content-commit-guidelines):

**Example:**

```
ci/12/travis-ci-integration
```

### Commit guidelines

For our commit guidelines, we are using [Conventional Commits](https://www.conventionalcommits.org/). Please strictly adhere to these conventions.

Expand All @@ -19,3 +62,42 @@ Allowed types:
- **test**: Adding missing tests or correcting existing tests

_(based on [Angular contribution guidelines](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#type))_

#### Reference the GitHub issue

To get a good paper trail and trace back any commits to their respective discussions, we reference each commit with the GitHub issue number that the commit is for. For that, put the issue number in parentheses with a hash prefix at the end of the commit description:

```
<type>[optional scope]: <description> (#<issue number>)
```

[Example:](https://github.com/csshugs/FluidMS/commit/6d6fe3c362907c6c0e07896c7ba4785d5d0b3f1d)
```
fix: webserver not serving `index.html` on baseUrl (#13)
```

#### Give context to your commits

To be able to identify the **WHY** behind a commit at a later point in time, we use the following template for our commit body:

```
<type>[optional scope]: <description> (#<issue number>)
because:
- [relevant context]
- [why you decided to change things]
- [reason you’re doing it now]
this commit:
- [does X]
- [does Y]
- [does Z]
```

_[Source](https://twitter.com/r00k/status/1175100703829909505)_

### Squash your commits

When a pull request is approved, all the commits need to be [squashed](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History#_squashing) in a meaningful manner before the pull request is merged. That is, combining those commits that form a complete feature into **one commit**. That doesn’t necessarily mean that all the commits of every pull request should ever result in one single commit! For example, if a pull request provides a new feature but alongside this new feature, a bug was fixed, too, this would result in two sqashed commits: One for the feature and one for the bugfix. The aim of this practice is to produce a sensible fragmentation of commits so we can later automatically create our changelog from these commits.

If you feel unsure about this process, just ping **[@fuhlig](https://github.com/fuhlig)** or **[@csshugs](https://github.com/csshugs)** in the comments of the pull request to request help. We’d love to do the squashing for you!
1 change: 1 addition & 0 deletions git-branching.drawio
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
<mxfile modified="2019-10-04T05:47:19.075Z" host="www.draw.io" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/77.0.3865.90 Safari/537.36" etag="vXUvJpnD_O89VUzHBoJD" version="12.0.2" type="device" pages="1"><diagram id="5iTnMoIIy0U06hVHBUrH" name="Page-1">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</diagram></mxfile>
Binary file added git-branching.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 50273b4

Please sign in to comment.