├── .editorconfig ├── .eslintignore ├── .eslintrc.js ├── .gitattributes ├── .github └── codeowners ├── .gitignore ├── .husky └── pre-commit ├── .mailmap ├── .npmrc ├── .prettierignore ├── .remarkignore ├── .remarkrc.mjs ├── changelog.md ├── license ├── lint-staged.config.js ├── package-lock.json ├── package.json ├── prettier.config.js └── readme.md /.editorconfig: -------------------------------------------------------------------------------- 1 | # Copyright (c) 2016-present Sven Greb 2 | # This source code is licensed under the MIT license found in the license file. 3 | 4 | # Configurations for EditorConfig. 5 | # See https://editorconfig.org/#file-format-details for more details. 6 | 7 | # +--------------------+ 8 | # + Base Configuration + 9 | # +--------------------+ 10 | root = true 11 | 12 | [*] 13 | charset = utf-8 14 | end_of_line = lf 15 | indent_size = 2 16 | indent_style = space 17 | insert_final_newline = true 18 | max_line_length = 160 19 | trim_trailing_whitespace = true 20 | 21 | # +-----------+ 22 | # + Languages + 23 | # +-----------+ 24 | # +--- Markdown ---+ 25 | [*.{md}] 26 | max_line_length = off 27 | trim_trailing_whitespace = false 28 | -------------------------------------------------------------------------------- /.eslintignore: -------------------------------------------------------------------------------- 1 | # Copyright (c) 2016-present Sven Greb 2 | # This source code is licensed under the MIT license found in the license file. 3 | 4 | # Path match pattern to ignore (i.e. not lint) certain files and folders. 5 | # References: 6 | # 1. https://eslint.org/docs/latest/use/configure/ignore 7 | 8 | node_modules/ 9 | 10 | # Explicitly include specific "dotfiles". 11 | # ESLint automatically applies ignore pattern for "dotfiles" by default to prevent accidentally lint over paths like 12 | # `.git` or any other critical paths. 13 | !**/.eslintrc.js 14 | !.remarkrc.mjs 15 | -------------------------------------------------------------------------------- /.eslintrc.js: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2016-present Sven Greb 3 | * This source code is licensed under the MIT license found in the license file. 4 | */ 5 | 6 | /** 7 | * Configurations for ESLint. 8 | * @see https://eslint.org/docs/latest/use/configure 9 | * @see https://eslint.org/docs/latest/use/configure/#using-configuration-files 10 | * @see https://eslint.org/docs/latest/use/configure/#specifying-environments 11 | * @see https://eslint.org/docs/latest/use/configure/#configuring-plugins 12 | * @see https://eslint.org/docs/latest/rules 13 | */ 14 | module.exports = { 15 | root: true, 16 | extends: [ 17 | "@svengreb/eslint-config-base", 18 | /* 19 | * Enable support for projects using Prettier. 20 | * Note that this must always be placed after the `@arcticicestudio/eslint-config-base` preset to take precedence, otherwise it won't prevent errors 21 | * due to useless and possibly conflicting rules! 22 | */ 23 | "@svengreb/eslint-config-base/prettier", 24 | ], 25 | overrides: [ 26 | { 27 | files: ["*.js"], 28 | rules: { 29 | "capitalized-comments": "off", 30 | }, 31 | }, 32 | ], 33 | }; 34 | -------------------------------------------------------------------------------- /.gitattributes: -------------------------------------------------------------------------------- 1 | # Copyright (c) 2016-present Sven Greb 2 | # This source code is licensed under the MIT license found in the license file. 3 | 4 | # Configuration to define attributes per path. 5 | # 6 | # References: 7 | # 1. https://git-scm.com/docs/gitattributes 8 | # 2. https://git-scm.com/book/en/v2/Customizing-Git-Git-Attributes#Keyword-Expansion 9 | 10 | # Automatically perform line feed (LF) normalization for files detected as text and 11 | # leave all files detected as binary untouched. 12 | * text=auto eol=lf 13 | -------------------------------------------------------------------------------- /.github/codeowners: -------------------------------------------------------------------------------- 1 | # Copyright (c) 2016-present Sven Greb 2 | # This source code is licensed under the MIT license found in the license file. 3 | 4 | # Configuration for the GitHub feature to automatically request reviews from the code owners 5 | # when a pull request changes any owned files. 6 | # 7 | # References: 8 | # 1. https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners#codeowners-file-location 9 | # 2. https://github.com/blog/2392-introducing-code-owners 10 | 11 | # +----------------------+ 12 | # + Core Team Code Owner + 13 | # +----------------------+ 14 | * @svengreb 15 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Copyright (c) 2016-present Sven Greb 2 | # This source code is licensed under the MIT license found in the license file. 3 | 4 | # Path match pattern to intentionally ignore untracked files and directories. 5 | # See https://git-scm.com/docs/gitignore for more details. 6 | 7 | # +---------+ 8 | # + Node.js + 9 | # +---------+ 10 | node_modules/ 11 | -------------------------------------------------------------------------------- /.husky/pre-commit: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | # Copyright (c) 2016-present Sven Greb 4 | # This source code is licensed under the MIT license found in the license file. 5 | 6 | # Git "pre-commit" hook for husky. 7 | # References: 8 | # 1. https://github.com/typicode/husky 9 | # 2. https://git-scm.com/docs/githooks#_pre_commit 10 | 11 | . "$(dirname "$0")/_/husky.sh" 12 | 13 | npm exec lint-staged 14 | -------------------------------------------------------------------------------- /.mailmap: -------------------------------------------------------------------------------- 1 | # Copyright (c) 2016-present Sven Greb 2 | # This source code is licensed under the MIT license found in the license file. 3 | 4 | # Configuration for the Git mail mapping feature to coalesce together commits by the same person in the shortlog, 5 | # where their name and/or email address was spelled differently or has been changed. 6 | # See https://git-scm.com/docs/git-shortlog#_mapping_authors for more details. 7 | Sven Greb 8 | Sven Greb 9 | -------------------------------------------------------------------------------- /.npmrc: -------------------------------------------------------------------------------- 1 | # Copyright (c) 2016-present Sven Greb 2 | # This source code is licensed under the MIT license found in the license file. 3 | 4 | # Configurations for npm. 5 | # See https://docs.npmjs.com/cli/v7/configuring-npm/npmrc for more details. 6 | 7 | # Only use a lockfile for single-consumer projects, like applications, but not for multi-consumer projects like 8 | # libraries. 9 | # It helps to pin dependency versions, improves the security through integrity checksums, prevents possible errors 10 | # caused by updated transitive dependencies and allows to get deterministic build results, but it can hide problems in 11 | # multi-consumer projects when any later versions of a used dependency, or its transitive dependencies, is not 12 | # compatible with the own project anymore. 13 | package-lock=true 14 | 15 | # Do not resolve to the latest minor and patch updates. 16 | # Automatically pin dependencies to exact versions instead of resolving to latest minor and patch updates. 17 | # This prevents possible errors caused by updated transitive dependencies. 18 | save-exact=true 19 | -------------------------------------------------------------------------------- /.prettierignore: -------------------------------------------------------------------------------- 1 | # Copyright (c) 2016-present Sven Greb 2 | # This source code is licensed under the MIT license found in the license file. 3 | 4 | # Path match pattern to ignore (i.e. not reformat) certain files and folders. 5 | # See https://prettier.io/docs/en/ignore for more details. 6 | 7 | .husky/_/ 8 | node_modules/ 9 | -------------------------------------------------------------------------------- /.remarkignore: -------------------------------------------------------------------------------- 1 | # Copyright (c) 2016-present Sven Greb 2 | # This source code is licensed under the MIT license found in the license file. 3 | 4 | # Path match pattern to ignore when searching for files. 5 | # See https://github.com/unifiedjs/unified-engine/blob/HEAD/doc/ignore.md for more details. 6 | 7 | node_modules/ 8 | -------------------------------------------------------------------------------- /.remarkrc.mjs: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2016-present Sven Greb 3 | * This source code is licensed under the MIT license found in the license file. 4 | */ 5 | 6 | /** 7 | * Configurations for remark-lint. 8 | * @see https://github.com/remarkjs/remark-lint 9 | * @see https://remark.js.org 10 | */ 11 | export default { 12 | plugins: ["@svengreb/remark-preset-lint"], 13 | }; 14 | -------------------------------------------------------------------------------- /changelog.md: -------------------------------------------------------------------------------- 1 |

2 | 3 | 4 | 5 | 6 | 7 |

8 | 9 |

10 | 11 | 12 | 13 |

14 | 15 | 16 | 17 | # 0.2.0 18 | 19 | ![Release Date: 2017-07-24](https://img.shields.io/badge/Release_Date-2017--07--24-88C0D0.svg?style=flat-square) [![Project Board](https://img.shields.io/badge/Project_Board-0.2.0-88C0D0.svg?style=flat-square)](https://github.com/users/svengreb/projects/10/view/10) [![Milestone](https://img.shields.io/badge/Milestone-0.2.0-88C0D0.svg?style=flat-square)](https://github.com/svengreb/styleguide-git/milestone/2) 20 | 21 | ⇅ [Show all commits][16] 22 | 23 | ## Features 24 | 25 | ### Documentation 26 | 27 | **Branch naming conventions and guidelines** — #3 ⇄ #6 (⊶ d1493353) 28 | ↠ Added [branch naming][4] conventions and guidelines for [core][2]- and [story branches][3] following the [Git Flow][1] branching model. 29 | 30 | **Tag naming conventions and guidelines** — #4 ⇄ #5 (⊶ 89924cb9) 31 | ↠ Added conventions and guidelines for [tags][13], following the [_Semantic Versioning_ specification][14]. 32 | 33 | # 0.1.0 34 | 35 | ![Release Date: 2017-07-22](https://img.shields.io/badge/Release_Date-2017--07--22-88C0D0.svg?style=flat-square) [![Project Board](https://img.shields.io/badge/Project_Board-0.1.0-88C0D0.svg?style=flat-square)](https://github.com/users/svengreb/projects/10/view/10) [![Milestone](https://img.shields.io/badge/Milestone-0.1.0-88C0D0.svg?style=flat-square)](https://github.com/svengreb/styleguide-git/milestone/1) 36 | 37 | ⇅ [Show all commits][15] 38 | 39 | ## Features 40 | 41 | ### Documentation 42 | 43 | **Initial style guide and project documentation** — #1 ⇄ #2 (⊶ 7c746dae) 44 | ↠ Added the initial style guide [introduction][10], information about the [structural split of changes][12], [bad practices][11] and the main chapter about [commit messages][9] with the [summary][8], [body][5] and [footer][6] elements and their [structure][7]. 45 | 46 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | [5]: https://github.com/svengreb/styleguide-git#message-body 71 | [6]: https://github.com/svengreb/styleguide-git#message-footer 72 | [7]: https://github.com/svengreb/styleguide-git#elements-and-their-structure 73 | [8]: https://github.com/svengreb/styleguide-git#message-summary 74 | [9]: https://github.com/svengreb/styleguide-git#commit-messages 75 | [10]: https://github.com/svengreb/styleguide-git#introduction 76 | [11]: https://github.com/svengreb/styleguide-git#bad-practices 77 | [12]: https://github.com/svengreb/styleguide-git#structural-split-of-changes 78 | [13]: https://github.com/svengreb/styleguide-git#tags 79 | [14]: https://semver.org/spec/v2.0.0.html 80 | [16]: https://github.com/svengreb/styleguide-markdown/compare/v0.1.0...v0.2.0 81 | 82 | 83 | 84 | [15]: https://github.com/svengreb/styleguide-markdown/compare/f990e101...v0.1.0 85 | [1]: http://nvie.com/posts/a-successful-git-branching-model 86 | [2]: https://github.com/svengreb/styleguide-git#core-branches 87 | [3]: https://github.com/svengreb/styleguide-git#story-branches 88 | [4]: https://github.com/svengreb/styleguide-git#branch-naming 89 | -------------------------------------------------------------------------------- /license: -------------------------------------------------------------------------------- 1 | MIT License (MIT) 2 | 3 | Copyright (c) 2016-present Sven Greb (https://www.svengreb.de) 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /lint-staged.config.js: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2016-present Sven Greb 3 | * This source code is licensed under the MIT license found in the license file. 4 | */ 5 | 6 | /** 7 | * Configurations for lint-staged. 8 | * @see https://github.com/okonet/lint-staged#configuration 9 | */ 10 | module.exports = { 11 | "*.json": "prettier --check --ignore-unknown --no-editorconfig", 12 | "*.{js,mjs}": ["eslint", "prettier --check --ignore-unknown --no-editorconfig"], 13 | "*.md": ["remark --no-stdout", "prettier --check --ignore-unknown --no-editorconfig"], 14 | ".husky/pre-*": "prettier --check --ignore-unknown --no-editorconfig", 15 | }; 16 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "@svengreb/styleguide-git", 3 | "version": "0.12.0", 4 | "description": "An opinionated, yet universally applicable Git style guide", 5 | "author": { 6 | "name": "Sven Greb", 7 | "email": "development@svengreb.de", 8 | "url": "https://www.svengreb.de" 9 | }, 10 | "homepage": "https://github.com/svengreb/styleguide-git", 11 | "repository": { 12 | "type": "git", 13 | "url": "git+https://github.com/svengreb/styleguide-git.git" 14 | }, 15 | "bugs": { 16 | "url": "https://github.com/svengreb/styleguide-git/issues" 17 | }, 18 | "license": "MIT", 19 | "private": true, 20 | "engines": { 21 | "node": ">=15.13", 22 | "npm": ">=7.7" 23 | }, 24 | "scripts": { 25 | "format": "run-s format:*", 26 | "format:js": "eslint --fix .", 27 | "format:pretty": "prettier --ignore-unknown --no-editorconfig --write \"**\"", 28 | "lint": "run-s lint:js lint:md lint:pretty", 29 | "lint:ci": "run-s --continue-on-error lint:js lint:md lint:ci:pretty", 30 | "lint:ci:pretty": "prettier --check --ignore-unknown --loglevel silent --no-editorconfig --no-error-on-unmatched-pattern \"**\"", 31 | "lint:js": "eslint .", 32 | "lint:md": "remark --no-stdout . .github/", 33 | "lint:pretty": "prettier --check --ignore-unknown --no-editorconfig \"**\"", 34 | "prepare": "run-s prepare:*", 35 | "prepare:husky": "husky install" 36 | }, 37 | "devDependencies": { 38 | "@svengreb/eslint-config-base": ">=0.12.0 <1.0.0", 39 | "@svengreb/remark-preset-lint": ">=0.5.0 <1.0.0", 40 | "eslint": "8.39.0", 41 | "eslint-config-prettier": "8.8.0", 42 | "eslint-plugin-import": "2.27.5", 43 | "eslint-plugin-prettier": "4.2.1", 44 | "husky": "8.0.3", 45 | "lint-staged": "13.2.2", 46 | "npm-run-all": "4.1.5", 47 | "prettier": "2.8.8", 48 | "prettier-plugin-sh": "0.12.8", 49 | "remark-cli": "11.0.0" 50 | } 51 | } 52 | -------------------------------------------------------------------------------- /prettier.config.js: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2016-present Sven Greb 3 | * This source code is licensed under the MIT license found in the license file. 4 | */ 5 | 6 | /** 7 | * Configurations for Prettier. 8 | * @see https://prettier.io/docs/en/configuration.html 9 | * @see https://prettier.io/docs/en/options.html 10 | * @see https://prettier.io/docs/en/options.html#parser 11 | * @see https://prettier.io/docs/en/plugins.html 12 | * @see https://github.com/un-ts/prettier/tree/master/packages/sh 13 | */ 14 | module.exports = { 15 | printWidth: 160, 16 | overrides: [ 17 | { 18 | files: [".husky/*"], 19 | options: { 20 | parser: "sh", 21 | }, 22 | }, 23 | ], 24 | }; 25 | -------------------------------------------------------------------------------- /readme.md: -------------------------------------------------------------------------------- 1 |

2 | 3 | 4 | 5 | 6 | 7 |

8 | 9 |

10 | 11 | 12 | 13 | 14 | 15 | 16 |

17 | 18 |

19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 |

29 | 30 |

An opinionated, yet universally applicable Git style guide.

31 | 32 | To present Git [commits][2] and [branches][1] in an organized, standardized, and easy-to-read manner, this style guide describes how the content should be structured, spelled and formatted. 33 | 34 | There are only some strict rules but mostly guidelines since we are more interested in content than formatting while the review process might help contributors to conform to this guide later on. 35 | 36 | ## Introduction 37 | 38 | Commit messages are important parts of communication between contributors and the lifecycle of a project: its past and its future. It is the only place that captures not only what was changed, but why. 39 | 40 | For open source project communities it‘s important to maintain good habits of communication in all forms. A well-crafted commit message can save a lot of time, overhead and helps to speed up development processes. 41 | 42 | ## Structural Split Of Changes 43 | 44 | > If a code change can be split into a sequence of patches/commits, then it should be split. 45 | > _Less is not more_. 46 | 47 | The cardinal rule for creating good commits is to **ensure there is only one logical change** per commit. There are many reasons why this is an important rule: 48 | 49 | - **The smaller the amount of code** being changed, **the quicker and easier it is to review** and identify potential flaws. 50 | - **Revert broken commits is much easier if there are not other unrelated code changes entangled with the original commit** if a change is found to be flawed later. 51 | - **Small well defined changes will aid in isolating exactly where the code problem was introduced** when troubleshooting problems using Git‘s `bisect` capability. 52 | - **Small well defined changes aid in isolating exactly where- and why a piece of code came from** when browsing history using Git `annotate` or `blame`. 53 | 54 | ### Bad Practices 55 | 56 | - **Mixing whitespace changes with functional code changes**. The whitespace changes will obscure the important functional changes, making it harder for a reviewer to correctly determine whether the change is correct. 57 | - The change should be split into two commits, one with the whitespace changes, one with the functional changes. 58 | - **Mixing two unrelated functional changes**. Without a structural split of changes it will be harder to identify flaws if two unrelated changes are mixed together. If it becomes necessary to later revert a broken commit, the two unrelated changes will need to be untangled, with further risk of bug creation. 59 | - **Sending large new features in a single giant commit**. The code for a new feature is only useful when all of it is present, but this does not imply that the entire feature should be provided in a single commit. 60 | - New features may entail refactoring existing code so it is highly desirable that any refactoring is done in commits which are separate from those implementing the new feature. This helps reviewers and test suites validate that the refactoring has no unintentional functional changes. 61 | - Newly written code can often be split up into multiple pieces that can be independently reviewed. For example, changes which add new internal APIs/classes, can be in self-contained commits leading to easier code review and allows other developers to cherry-pick small parts of the work, if the entire new feature is not immediately ready for merge. 62 | - Code that affects public APIs should be done in commits separate from the actual internal implementation. This will encourage the author and reviewers to think about the generic API design, and not simply pick a design that is easier for their currently chosen internal implementation. 63 | 64 | ## Commit Messages 65 | 66 | > The commit message must contain all the information required to fully understand & review the patch. 67 | > _Less is not more_. 68 | 69 | As important as the content of the change is the content of the commit message describing it. The purpose of a commit message is to summarize a change, but the purpose of summarizing a change is to help to understand the code. The information to be put into a message should be valuable and useful for reviewers and the projects community. 70 | 71 | Having a story in the Git history will make a huge difference in how others perceive the project. Taking great care in commit messages will help to increase the long-term overall quality. 72 | 73 | - **The first line is important**. The [message summary](#message-summary) of the commit has special significance. It is used in many places like the Git history headline, git annotate- and merge messages or email subject lines where space is at a premium. As well as summarizing the change itself, it should take care to detail what part of the code is affected. 74 | - **Describe the intent and motivation behind the changes**. Describe _why_ the code has been written this way and document the overall code structure in the [message body](#message-body), particularly for large changes. 75 | - **Include the GitHub issue ID and additional references** in the [message footer](#message-footer). This will automatically fire some hooks to track the commit in related GitHub repository issues- and pull requests and is **required to contribute to a project**. 76 | - **Reviewers can understand what the original problem was**. The commit message should have a clear statement as to what the original problem is. The GitHub issue ID is merely interesting historical background on _how_ the problem was identified and has been discussed within the community, but it should be possbile to review a proposed patch for correctness without having to read the whole ticket. 77 | 78 | ### Elements and their structure 79 | 80 | A Git commit message follows this format: 81 | 82 | ```raw 83 | 84 | 85 | 86 | 87 |