feat: added examples to the specification #21

tchaffee · 2017-10-11T17:41:11Z

I was pointed to the specification and wanted to just get started, which would have been possible with examples. Instead I did a lot of reading about the motivation for the spec, and the formal spec itself. I am hoping the examples will help other people see how simple the spec is and to just get started quickly.

stevemao

I like to add some examples :)
It would be better to add more. EG: Referencing an issue (EG: Fixes #1)
Also I'm not sure if breaking change is a body (probably footer?). A body is a long description of what's being changed.

stevemao · 2017-10-11T23:48:03Z

index.md

+BREAKING CHANGE: `extends` key in config file is now used for extending other config files
+```
+
+### Commit message with scope


I think this is the most commonly used message so I'd reorder this to top :)

I'll fix this.

stevemao · 2017-10-11T23:48:29Z

index.md

+
+### Commit message with no body
+```
+fix: Correct spelling of CHANGLOG


changing the CHANGELOG should be docs.

Ironically, I got this example from this repo. #13 :-D

But I'll fix it.

Well, it was wrong :)

subject should not start with caps, this spells trouble 🗡

bcoe · 2017-11-28T07:46:02Z

@tchaffee thank you for this work; just some quick drive by comments (I'm finally catching up on some of my massive backlog of git issues phew).

I love the idea of adding some example; I'm excited to see this work to conclusion.

a couple random notes:

as a matter of process, should we update the version of the document when we make significant changes like this; perhaps call this 1.0.0-beta.2?
we should also update the documents in the translation folders (perhaps we can loop @Morishiri back in to provide the updated translation).

@Morishiri perhaps you have some thoughts on this pull too; given that you've made some significant contributions to this site.

Morishiri · 2017-11-28T13:01:44Z

I will update polish language as well with some additional changes which I've noticed after I added this translation, but I think I will do that as separate pull request? Or should I add it here?

bcoe · 2018-03-16T18:02:25Z

@Morishiri @tchaffee this has been hanging out for a long time, shall we get it over the finish line?

tchaffee · 2018-03-19T21:01:15Z

I think this should be good now, but if there are any other minor changes please let me know as soon as you can and I'll get this finished up.

damianopetrungaro · 2018-03-20T08:32:41Z

index.md

+
+### Commit message for a fix using an (optional) issue number.
+```
+fix: issue #12 - minor typos in code


This issue #12 should be used in the footer and not in the commit message. See the doc for more info.

Other examples seem good to be 😄

So that means I have to also include a body? That's kind of annoying if there is otherwise no need for a body. I'll change this for now, but I think this rule should be reconsidered.

damianopetrungaro · 2018-03-20T08:38:17Z

index.md

+
+### Commit message with scope
+```
+feat(lang): added polish language


WDYT about using "imperative sentence" in the examples?
This is a shared best practice (also in the angular repo)
feat(lang): add polish language

PS: This is not enforced by this convention btw

If it's not enforced by this convention, could you please open a new issue to discuss this?

I second this. As I mentioned on my other comment, even if it's not in the spec we shouldn't have "bad" commit messages in the examples. Especially if people would end up relying on tools to enforce them that'd scream at this.

We should have "bad" commit messages if the spec doesn't require "good" ones. By trying to include best practices from other tools we'll end up constantly chasing any changes in those tools / conventions. Best to describe those other conventions in one place only (over in the repo for those tools) and keep it DRY. In any case, the discussion should really go in a new issue.

I think we should just accept and move that verb tense convo elsewhere. I don't feel there's any consensus on past vs present -- there's a strong argument for "past" in the link below fwiw.

Example: https://stackoverflow.com/questions/3580013/should-i-use-past-or-present-tense-in-git-commit-messages/8059167

Created stub issue: #42

damianopetrungaro · 2018-03-20T08:55:17Z

index.md

@@ -37,6 +37,30 @@ consumers of your library:
 A scope may be provided to a commit's type, to provide additional contextual information and
 is contained within parenthesis, e.g., `feat(parser): add ability to parse arrays`.

+## Examples
+
+### Commit message with body and breaking change


### Commit message with body and breaking change
Should be:
### Commit message with description and breaking change in footer
because with commit body we mean the section between the footer and the type + description :D

tchaffee · 2018-03-20T13:52:27Z

@damianopetrungaro thanks for the review and I've made the changes you requested. Hopefully this is ready to be merged now.

damianopetrungaro · 2018-03-20T19:55:33Z

index.md

@@ -37,6 +37,34 @@ consumers of your library:
 A scope may be provided to a commit's type, to provide additional contextual information and
 is contained within parenthesis, e.g., `feat(parser): add ability to parse arrays`.

+## Examples
+
+### Commit message with description and breaking change in body


change in footer*

Please correct me if I'm wrong, but there is no footer. There is only a body.

You are not wrong actually.
The difference is about the content:
The BC can be indicated in Body or Footer section.

Sorry this was my bad 😄

tchaffee · 2018-03-21T15:54:25Z

Is there anything holding this up from being merged? I think I've made all the requested changes.

damianopetrungaro · 2018-03-21T16:24:36Z

@tchaffee please tag owner of the repo 😄

tchaffee · 2018-03-21T17:21:06Z

@damianopetrungaro Do you know who that is?

damianopetrungaro · 2018-03-21T20:15:30Z

@bcoe @stevemao

blackxored · 2018-03-25T03:01:49Z

index.md

+
+see the issue for details on the typos fixed
+
+fixes issue #12


This is typically Closes: #12. The body above should start with caps.

@blackxored those aren't on the specs.

They might not be, but I think we should strive for good commit messages as examples, and this isn't one IMHO, at least for the examples providing one that wouldn't clash with good practices (for ex. commitlint and config-conventional which people will learn to associate with this even if they're not) might be good.
In that spirit, I'd replace the body to be explicit (it's meaningless in its current form) and make the footer just Closes: #12.

I may agree with you, but if isn't specified in the specs it won't be used.
You can open another PR and propose those changes and discuss it, but atm those are just your usage of the specs.

Hmm, as I've pointed out in #21 (comment) I think it's a natural step for people to refer to @commitlint/config-conventional while adopting this spec, it's not just my usage but what's expected by the ecosystem I reckon, commitlint would error at these commit messages, and it's counterintuitive IMHO. Thoughts?

The point is:

If we want to add this to the spec we should open issues -> discuss it -> create PR improving the specs.

Since my examples follow the spec, I think they should stay as-is and be merged and another issue should be opened to discuss whether or not the examples should demonstrate more than the spec and why. I typically don't like examples to include anything other than exactly what the spec requires. If the spec is missing some best practices, the spec itself should be improved, and that's a separate discussion.

Yup, avoiding to block a PR and to delay the merge for discussions.

@blackxored In case it sounded like people were being pedantic or difficult, I think it's just that they wanted us all to exercise the spec. If something feels "right", it should be codified in spec before changing behaviour :)

It's perhaps hardline, but an excellent way to keep the spec moving along!

blackxored · 2018-03-25T10:10:05Z

Selfless plug: if you need more examples, which are valid for tools, take a look at this section on a post I wrote.

tchaffee · 2018-03-26T01:30:41Z

@bcoe Any feedback here? I'd like to get this closed out and move on before I get distracted again with other projects and can't revisit this for a while.

tchaffee · 2018-04-04T21:16:17Z

Ping. Any chance we can get this merged?

patcon · 2018-04-09T20:29:50Z

Yay! Ready! Let's get this sucker merged 🎉

bump @bcoe @stevemao 🙂

patcon · 2018-04-09T20:32:42Z

@bcoe @stevemao also, if you think this project could benefit from more maintainers to share the load, perhaps we could open another ticket to do a "Call for co-maintainers" with a lightweight nomination process, pending your +1's?

damianopetrungaro · 2018-04-09T20:51:30Z

@patcon please, move to another issue, this is not the right place.

bcoe · 2018-04-09T22:14:34Z

@damianopetrungaro @patcon would definitely love more maintainers chipping in. Full disclosure, my wife passed away at the start of 2018 and it's been taking me a while to get back into open-source again -- hoping I'll be a bit more on the ball again in the near future.

I have a slack I've been managing for open-source projects like conventional commits:

http://devtoolscommunity.herokuapp.com/

This is a good place to come have a real-time conversation about better maintaining this projects (and to express an interest in being a maintainer).

damianopetrungaro · 2018-04-09T22:18:39Z

oh man, I'm really sorry for your loss.
Feel free to mail me if I can help you in any way.

tchaffee · 2018-04-10T15:27:18Z

@bcoe I'm so sorry to hear that. It can take a long time to get back to anything even resembling a normal routine. I'm also happy to help out in any way I can.

patcon · 2018-04-11T19:10:59Z

My heart just fell. I am so so sorry @bcoe. Please take care of yourself, ~~and I'll try to make time to help with finding a previous project contributor to help out.~~ Much love to you.

EDIT: Respect, @tchaffee. Just realized your offer.

blackxored · 2018-04-11T21:05:00Z

@bcoe So sorry to hear about this man, very sorry for your loss.

bcoe · 2018-04-11T21:26:56Z

@patcon @tchaffee @blackxored thanks for your thoughts 👍 I'm happy to add more folks to the project, I think we all have the same goals: getting the language and rules around conventional commit messages as straight-forward as possible, and making sure the other libraries in this repo match those rules.

Private message me in http://devtoolscommunity.herokuapp.com/, and I'll get a few more folks added as contributors.

stevemao requested changes Oct 11, 2017

View reviewed changes

stevemao reviewed Oct 11, 2017

View reviewed changes

tchaffee force-pushed the feat/add-examples branch from 015d7ae to d684c53 Compare March 19, 2018 21:00

damianopetrungaro reviewed Mar 20, 2018

View reviewed changes

feat: added examples to the specification

197c1eb

tchaffee force-pushed the feat/add-examples branch from d684c53 to 197c1eb Compare March 20, 2018 13:51

damianopetrungaro reviewed Mar 20, 2018

View reviewed changes

damianopetrungaro approved these changes Mar 23, 2018

View reviewed changes

blackxored reviewed Mar 25, 2018

View reviewed changes

damianopetrungaro mentioned this pull request Apr 9, 2018

Lead with an example on website #40

Closed

patcon mentioned this pull request Apr 9, 2018

Discussion: Address verb tense in spec #42

Closed

bcoe merged commit b833cb6 into conventional-commits:master Apr 9, 2018

tchaffee deleted the feat/add-examples branch April 10, 2018 15:25

feat: added examples to the specification #21

feat: added examples to the specification #21

Conversation

tchaffee commented Oct 11, 2017

stevemao left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tchaffee Oct 16, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bcoe commented Nov 28, 2017

Morishiri commented Nov 28, 2017

bcoe commented Mar 16, 2018

tchaffee commented Mar 19, 2018

damianopetrungaro Mar 20, 2018 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

damianopetrungaro Mar 20, 2018 • edited

Choose a reason for hiding this comment

tchaffee Mar 20, 2018 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tchaffee Mar 26, 2018 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

damianopetrungaro Mar 20, 2018 • edited

Choose a reason for hiding this comment

tchaffee commented Mar 20, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tchaffee commented Mar 21, 2018

damianopetrungaro commented Mar 21, 2018

tchaffee commented Mar 21, 2018

damianopetrungaro commented Mar 21, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

blackxored Mar 25, 2018 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tchaffee Mar 26, 2018 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

blackxored commented Mar 25, 2018

tchaffee commented Mar 26, 2018

tchaffee commented Apr 4, 2018

patcon commented Apr 9, 2018

patcon commented Apr 9, 2018 • edited

damianopetrungaro commented Apr 9, 2018

bcoe commented Apr 9, 2018

damianopetrungaro commented Apr 9, 2018

tchaffee commented Apr 10, 2018

patcon commented Apr 11, 2018 • edited

blackxored commented Apr 11, 2018

bcoe commented Apr 11, 2018

tchaffee Oct 16, 2017 •

edited

damianopetrungaro Mar 20, 2018 •

edited

damianopetrungaro Mar 20, 2018 •

edited

tchaffee Mar 20, 2018 •

edited

tchaffee Mar 26, 2018 •

edited

damianopetrungaro Mar 20, 2018 •

edited

blackxored Mar 25, 2018 •

edited

tchaffee Mar 26, 2018 •

edited

patcon commented Apr 9, 2018 •

edited

patcon commented Apr 11, 2018 •

edited