etclabscore / etclabscore/pristine

Conventional commits

Open
#28 1 comment 0 reactions 0 assignees View on GitHub
discuss
Dominant language
No language data
Stars
11
Forks
9
PR merge metrics
No merged PRs in 30d

Description

**Is your feature request related to a problem? Please describe.**

Currently [conventional commits](https://github.com/etclabscore/pristine/blob/master/CONVENTIONAL_COMMITS.md) refers and adheres to http://conventionalcommits.org/.

My issue is that this "Conventional commits" style isn't really conventional; it's actually pretty opinionated.

Since the _Conventional Commits_ spec allows arbitrary `xxx[yyy]:`, it seems like the only thing that structuring a message in this way does is enable easier machine readability1 (and not work directly to _Documentation Driven Development_ in the sense of legible and accurate documentation around development). It's just a punctuation spec, not a content spec, and despite it's name is not very generalized.

**Describe the solution you'd like**

Something as generic as possible, while still being able to describe something that's actually useful.

In my opinion there are more useful resources we can draw from for outlining a rubric for a "good" commit message, for example
- https://secure.phabricator.com/book/phabflavor/article/writing_reviewable_code/.
- https://github.com/torvalds/subsurface-for-dirk/blob/a48494d2fbed58c751e9b7e8fbff88582f9b2d02/README#L88

**Describe alternatives you've considered**

- `scope: message`; useful for big repos, not so much for small ones
- Commit messages should start with a capital letter
- `problem: xxx / solution: yyy` structure
- https://rfc.zeromq.org/spec:44/C4/

**Resources**

I spent 10 minutes looking through ["top starred" repos on Github](https://github.com/trending?since=monthly) for examples (for lack of a better "canon of the conventional").

A list of example repos that don't follow this pattern:
- https://github.com/golang/go/commits/master - Note here that `cmd/api: fix no go files package panic` is used, where `cmd/api:` is the package containing the changes. In fact, this kind-of-almost fits the Conventional Commit style, except that "scope" (optional) is used in place of "type" (mandatory).
- https://github.com/torvalds/linux/commits/master
- https://github.com/python/cpython/commits/master
- https://github.com/php/php-src/commits/master
- https://github.com/git/git/commits/master
- https://github.com/netdata/netdata/commits/master
- https://github.com/openssl/openssl/commits/master
- https://github.com/ethereum/go-ethereum/commits/master
- https://github.com/pomber/git-history/commits/master
- https://github.com/30-seconds/30-seconds-of-code/commits/master
- https://github.com/toddmotto/public-apis/commits/master
- https://github.com/transloadit/uppy/commits/master
- https://github.com/facebook/react/commits/master
- https://github.com/trekhleb/javascript-algorithms/commits/master
- https://github.com/axios/axios/commits/master
- The default style generated by Github for `suggestion`ed commits or when using their browser editor, like:
![screen shot 2019-03-04 at 11 02 24 am](https://user-images.githubusercontent.com/45600330/53749462-0a7f8f00-3e6d-11e9-8bbb-bdc047cbb85c.png)

Repos I found that do use it:
- https://github.com/vuejs/vue/commits/dev
- ... and from their docs, [a list of some more repos that do use it](https://github.com/etclabscore/pristine/blob/master/CONVENTIONAL_COMMITS.md#projects-using-conventional-commits), all of which are Javascript projects

---
1. From the docs, [3/5 of "Why Use Conventional Commits" are for computer automation](https://github.com/etclabscore/pristine/blob/master/CONVENTIONAL_COMMITS.md#why-use-conventional-commits).

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.