conventional-commits / conventionalcommits.org Goto Github PK
View Code? Open in Web Editor NEWThe conventional commits specification
Home Page: https://conventionalcommits.org
License: MIT License
The conventional commits specification
Home Page: https://conventionalcommits.org
License: MIT License
Since improvement
(11 chars) is even longer than feature
(7 chars), which is shortened as feat
.
This post my be somewhat controversial, being Canadian I'm prefacing the whole thing with an apology ๐
The conventional-changelog organization is a set of modules for parsing various flavors of commit message formats (angular, atom, jquery, ...), and performing useful operations based on this meta-information:
Despite conventional-changelog's abstract design, many of the tools related to the conventional-changelog ecosystem are adopting the angular commit convention:
When evangelizing adopting a conventional commit format to people, there are a few things I emphasize:
BREAKING CHANGE
, fix
, feat
), you become able to programmatically determine what the version bump for the next release should be.perhaps most importantly!
I emphasize that it doesn't add much work:
semantic-release
, standard-version
, lerna
, etc., to automateI found a few things confusing when introduced to the conventional-changelog
ecosystem and the concept of the angular commit convention:
conventional-changelog
should be more prescriptive; It's great to have flexible core libraries, but as a user I was mainly interested in: eliminating tedium around version bumps, and CHANGELOG management,conventional-changelog
, semantic-release
, angular
, etc.I really like the semver.org specification. It introduces the concept of semantic
versioning in a clear, tool agnostic way, explaining its value to the software development process.
I propose that for the conventional-changelog.github.io
website, we put up a site modeled after semver.org -- potentially hosted at conventionalcommits.org:
conventional-commits
: it has wide adoption, it's simple, and seems like a great format to standardize on.How do folks feel about this proposal? I would love help pulling together documentation
for conventionalcommit.org; I think it will be a great place for us to point our various users to.
I reached out to @mojombo, he'd happily let us use the design from the semver.org website as
a jumping off point for our specification; @JaKXz also indicated that he'd be excited to help us setup a scaffolding using fancy pants new web technologies.
CC: @ajoslin, @stevemao, @Tapppi, @evocateur, @boennemann
I want to have a badge or two that looks great with others, but holds personality so folks are proud to flaunt it. Having an image|icon in the badge is shown to hold more value in the attention economy as well. The resolution of the type is a bit off, but I've attached SVG and AI sources to rectify that as so desired.
There's no mention of it.
cf https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#revert
Reticketed from: #21 (comment)
for machine readability and to differentiate normal commit messages from conventional commits i suggest that there should be one or more characters at the beginning of the line to indicate a conventional commit.
example:
$fix(gui):spelling error in settings wnidow
Continuing the conversation from - #66 (comment)
Why do we recommend improvement
as a type, and how is improvement
better than using other types that signify improvements noticeable to downstream consumers, such as perf
?
Paths like lang/es/index.md have usually referred to Espaรฑol in my experience. Were these files intended to be placeholders for Spanish?
I would like to suggest we consolidate the numbered items under the Summary section into the Conventional Commits Specification section.
Could we add a "BREAK:" shorthand for "BREAKING CHANGE:"?
Reason being if I have a long component there's not a whole lot of space left to write a meaningful description for the CHANGELOG.
I think we should amend the specification to allow BREAKING CHANGE:
with any commit type (right now we indicate that a BREAKING CHANGE should be a fix, or feat).
I'm finding as I drop Node 0.10/0.12 support on some libraries, I have chore
commits that are breaking.
Hello!
I'm having trouble understanding what you actually want to communicate with some sentences, for example:
"As an open-source maintainer, squash feature branches onto master and write a standardized commit message while doing so.".
I would like also to remove all reference to methodologies and workflow for git from the specs (except the FAQ section), because i would like to see (and use) a specific language focusing on commits instead of PR (for example).
An example of this issue is this (it refer to a pull-request instead of a generic "task to resolve"): item 7 and item 5
If it's ok for you i would like to reformulate those sentences for make them more clear and "commit oriented" ๐
Let me know guys!
Hey beautiful people! We are slowly moving forward, but we are doing it!
We bumped up the version to:
We need to update the current translations and we need your help!
@Morishiri and @doodlewind could you please help us? (or tag someone who may do it)
I will update the Italian translations cause I did it ๐
Thank you for your contributions!
Why does the spec have lowercase as the default? I figure as a title for a commit, it'd be uppercase.
Reference:
http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
What are the criteria for migrating conventional-changelog
projects to the new organization?
By default the feat
and fix
types are orthogonal. If we define multi types, say, test
and doc
, how to decide the type when committing a change that:
fix
doc
test
Shall we allow multi types in commit message, or provide suggestion choosing types?
Hello, I am not sure it's the right repo for this. If it is not, please let me know.
I wish to understand better the semantics of "feat".
Regarding the "feat" keyword. I have trouble with it depending on the perspective.
feat: a commit of the type feat introduces a new feature to the codebase (this correlates with MINOR in semantic versioning).
There are two points of view: the product perspective vs development perspective.
Let's say a dev introduces a new cool reusable UI component.
feat(UI): add super new generic graph visualizer
Then later, this component is used to display some data.
feat(reports): display reports graph for x
Now, for a generated changelog, it's a bit of a problem because we are mixing "developer features" with "product features" and releases are unclear or with unnecessary information for people only interested in the "product features".
I was wondering how people make this difference and maybe clarify the semantics on conventionalcommits.org :)
@conventional-commits/committee we need to find a strategy to implement a proper semantic versioning when we'll release the first version (and it's pretty close).
What I propose is to use an upcoming
directory where we change the latest specs version and when we decide to release (thanks to the conventional commits) we'll bump up the version and release.
Any other strategy is the welcome ๐
I'd like to contribute a styling improvement to the project.
To make sure what I did is rendered correctly I'd like to run it locally before submitting a pull request.
I'm unable to find local setup steps in the readme.
Purpose of this issue is to document the problem
issue can be closed if the problem is solved or if there is a decision to not take care of this
Reading the specs I noticed that we seem to refer it only to open-source maintainers.
I thought that rewording some sentences to generic purpose will allow us to be open to all the kind of codebase.
For example:
As an open-source maintainer...
should be As a commitizen...
...to the consumers of your library:
should be ...to the consumers of your codebase:
...that an open-source maintainer knows about,
should be ...that a maintainer knows about,
and so on
What do you think about it?
e.g commits for version bump, update dependencies, update readme etc?
Should they also consider as fix
?
Hello,
Time ago I designed bumped for making release software easy.
In fact, It has a bumped-changelog that use conventional commits under the hood!
I want to ask if it could be added to the tools recommend. Actually, I can make the change, just not sure if it needs to be added to all content versions or just in the current version.
Hi!
I'm a big fan of conventional commits, and have been using it on most of our work projects and all of my personal projects, so thank you.
I've been trying to implement a parser for the spec here and have a question.
Given
A longer commit body MAY be provided after the short description, providing additional contextual information about the code changes. The body MUST begin one blank line after the description.
and
A footer MAY be provided one blank line after the body (or after the description if body is missing).
How can automated process tell the difference between a commit message with just a description and a commit message with just a footer?
Thanks,
Alex
@bcoe @hbetts do you remember who designed the one for conventional-changelog
?
It would be great having a nice one for this one too.
I don't know the origin story of the @conventional-changelog GitHub org nor am I an owner of it, but I have an idea.
It seems to me that the addition of the conventionalcommits.org
repository to this org changes the org's purpose in a way: It's now the home of the Conventional Commits spec. As such, I think renaming the org to @conventional-commits would be appropriate. The changelog tools should still live here too. :)
Furthermore, there are other projects out there in userland that are drinking the conventional Kool-Aid and could be welcome additions here. Moving them here would make them more discoverable for people who want to start adopting Conventional Commits in their projects. A few repos come to mind:
cc @bcoe @kentcdodds @nexdrew @olstenlarck @stevemao @damianopetrungaro
Hi There,
Big fan of this spec. Is there any plans or intentions on writing tooling around this spec i.e. some basic git/hg hooks which can be developed to enforce the conventional commit format?
Would this be a task/project that you would consider to be relevant to the scope of https://github.com/conventional-commits?
See: https://medium.com/walmartlabs/semantic-commit-messages-with-emojis-dba2541cea9a
I seem to recall there being a great tool that I found used in the vuejs community, that made commit message and changelogs more automated, and made use of well-thought-out emoji. I'll try to dig it up later :)
While Conventional Commits itself does not specify verb voice and tense for the description, it's common to use imperative, present tense describing what the commit, if applied, does, rather than past tense describing what was done. So adopt this convention in the example, making the commit message example more relatable.
Before:
### Commit message with scope
```
feat(lang): added polish language
```
After:
### Commit message with scope
```
feat(lang): add polish language
```
See #65 for an implementation.
#77 would go further and recommend imperative present tense, rather than just modeling it in this example commit message.
I just pulled down the latest and tried docker-compose up
to get it running, per the current README.
I got this error:
~/git/conventional-commits/conventionalcommits.org master
$ docker-compose up
Creating network "conventionalcommitsorg_default" with the default driver
Pulling site (jekyll/jekyll:latest)...
latest: Pulling from jekyll/jekyll
911c6d0c7995: Pull complete
66c75bb6a8fc: Pull complete
a1d8100f3d6a: Pull complete
640ab4473371: Pull complete
21c0befec5f5: Pull complete
Digest: sha256:d40966028599e7e76f730ecef920b88bcd08dda82ed5beb6eb073fb4f211a93a
Status: Downloaded newer image for jekyll/jekyll:latest
Creating conventionalcommitsorg_site_1 ...
Creating conventionalcommitsorg_site_1 ... error
ERROR: for conventionalcommitsorg_site_1 Cannot start service site: driver failed programming external connectivity on endpoint conventionalcommitsorg_site_1 (fcf7ab101b75ced4d315a3854366c7b940ed21fa5edc6b3bf89ba83b7ed4102d): Bind for 0.0.0.0:80 failed: port is already allocated
ERROR: for site Cannot start service site: driver failed programming external connectivity on endpoint conventionalcommitsorg_site_1 (fcf7ab101b75ced4d315a3854366c7b940ed21fa5edc6b3bf89ba83b7ed4102d): Bind for 0.0.0.0:80 failed: port is already allocated
ERROR: Encountered errors while bringing up the project.
$ docker-compose --version
docker-compose version 1.14.0, build c7bdf9e
See also #23
Currently if a feature, for example, is a breaking change, a commit would look something like the following:
feat: something cool
BREAKING CHANGE: The cool thing broke stuff.
I am suggesting that the standard also allows the use of a special character, for example !
, in the title to specify a breaking change. It is a matter of discussion as to whether the body should still contain BREAKING CHANGE
.
That is, the above commit could look like the following. Note the !
after feat
:
feat!: something cool
BREAKING CHANGE: The cool thing broke stuff.
I am suggesting this change since the GitHub UI and many other tools are used that show only the title of a commit to reduce noise. This is nice, but by looking only at the title, it can be hard to identify which features and chores etc. are breaking changes. The suffix I am proposing would remedy that.
Also, it might be easier to read using a prefix, i.e. !feat:
instead of feat!:
. This would also be up to discussion.
What commit message should be if I rename/move file into other scope?
The first summary sentence:
As an open-source maintainer, squash feature branches onto master and write a standardized commit message while doing so.
Seems out of place.
I land on the conventionalcommits
website and the first sentence is talking about squashing commits (something I don't do), but only for features (so what am I supposed to do for other commit types), and only talks about open-source maintainer
s, which seems to exclude third-party contributors to a project.
Can we just eliminate that sentence?
We should provide a badge for people to place on their repos when using conventional commits; we have something for this for standard-version, but we should update it to reflect this new org.
I would like to propose an explicit difference in Body and Footer section.
The footer should only contain info as BC, external links.
The body should only to explain what and why changed (more like a Product Manager perspective).
Which projects should we pin to the home page of the conventional-commits
org?
examle:
i'm work on feature and dont know my code is correct or no, but i must go home.
i will push a commit becouse i don't whant to miss my work. But i now that i will work on this code another time. Maybe i will need more then one ore two commits while create finish commit with end fix or feature or another one, now i create chore commit, but maybe add some wip type of the commit or another point what told me about not completed commit?
chore(client.api): try to catch error with timeout
If you whant fetch....
WIP: any description
I kinda disagree with this:
Other commit types have no implicit effect in semantic versioning
because if I add a new commit to my project, and I want to release, it should bump up the PATCH version (if it doesn't contain a breaking change).
This is minor I suppose, but shouldn't the examples use capitals after the :
? Given that text is parsed into a CHANGELOG
and each commit title is supposed to be a standalone sentence, would it make sense to capitalise the first letter of each explanation?
For example, instead of:
feat: allow provided config object to extend other configs
use:
feat: Allow provided config object to extend other configs
Then the generated changelogs would use proper grammar, I think?
What do you think about revamping the UI of the website with a new theme (and\or new tool for generating the static website)?
We can make it as cool as keep a changelog so that more people will read it because it looks good
It would be good to build a client side tool to test/valid commit message. Users can select a preset in a dropdown list. They also need to input commit message(s). The commit messages could be colour highlighted by the parser. And a preview for the changelog that's generated based the commit messages.
Re-evaluate how we are applying the terminology defined in RFC 2119 in the Conventional Commits specification.
Came up in #77 (comment)
The "Breaking Change" bullet point nr 3 states:
- BREAKING CHANGE: a commit that has the text BREAKING CHANGE: at the beginning of its optional body or footer section introduces a breaking API change (correlating with MAJOR in semantic versioning). A breaking change can be part of commits of any type.
Then, the next bullet point "Others" nr 4 states:
- Others: commit types other than fix: and feat: are allowed, for example (...) chore:, docs:, style:, refactor:, perf:, test:, and others. (...) Notice these types are not mandated by the conventional commits specification, and have no implicit effect in semantic versioning (unless they include a BREAKING CHANGE, which is NOT recommended).
I feel like these two points are contradicting each other.
I would like to propose we establish the convention that all sentences in a commit message SHOULD be written in imperative present tense form.
Well-known examples of the imperative present tense form as a requirement:
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
RFC 2119.
I don't understand why only docs
have s
. Have you references/links ?
The website currently has nothing above the fold that helps someone quickly know how to confirm. The spec is really rad an specific, but I feel that when a PR fails due to not conforming, it would be a really great experience if I went straight to the website and felt like "ooooooh, I get it!" The the template-speak is helpful, a prominent example above the fold could really convey the MVP of what a conventional commit is :)
Thanks for your attention and consideration! If you have a favourite commit message that meets the spec and exercises it the a proper extent, pls do drop it, and I'll submit a PR ๐
Add automagic deployment when rebase-merging master
It would be good to showcase a few projects using conventional commits (yargs and istanbuljs are the ones I work on).
Two minor confusion points in commit types:
type
field is specified as a verb, whereas feat
itself is a noun, and so does chore
, style
, perf
, etc.fix:
, feat:
, while its definition is <type>[optional scope]:
, which excludes colon from type name.Feel free to close this issue if it's too captious ๐
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.