chore: release 1.0.0 of specification #175

bcoe · 2019-08-14T01:30:39Z

I would like to advocate releasing version 1.0.0 of Conventional Commits.

Reasoning

we've been working on the project for ~3 years, and I think it's reached healthy maturity.
the specification is being used in the wild for a variety of major open source projects (yargs, electron, Istanbul) and folks seem happy.
we've seen adoption of Conventional Commits across a variety of languages (as an example we're using it for PHP, JavaScript, and Java at Google) demonstrating that the spec in its current form appeals to more than just JavaScript.
the convention has reached a healthy point of stability (since introducing ! (which is working great) there haven't been other major updates).

Let's Practice What We Preach

Releasing a 1.0.0 version of the specification doesn't mean that we can't iterate, it just means that we drop the ugly beta/alpha suffix and start following SemVer for updates to the specification.

CC: @tommywo, @jbottigliero

content/v1.0.0/index.md

stevemao · 2019-08-14T07:08:58Z

I think it would be good to include revert just for completeness. #88

Mouvedia · 2019-08-14T15:56:33Z

build and ci should be listed there:

conventionalcommits.org/content/v1.0.0-beta.4/index.md

Line 37 in 5bed96e

    
           1. Others: commit _types_ other than `fix:` and `feat:` are allowed, for example [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (based on the [Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) recommends `chore:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, and others.

bcoe · 2019-08-14T20:56:03Z

@stevemao left a comment on the revert discussion. I think we should explicitly call out revert: in FAQ, with a recommendation that someone use Refs: to indicate the PR or SHA being reverted.

JeanMertz · 2019-08-14T21:48:38Z

Hey @bcoe, I can't dive into this too deep right now, but I just noticed you created this PR, and wanted to link you to an issue on a project of mine in which I'm working on a parser for Conventional Commit.

I think the contents of that discussion might be interesting to you. Not sure if it'll make any difference in whatever ends up getting merged as v1.0.0, but at the very least it might give you some new insights.

rustic-games/conventional-commit#1 (comment)

(the parser is used in another library, Jilu, to auto-generate a change log based on conventional commits, which is why being able to correctly parse breaking changes (and possibly other metadata) is important to get right)

Mouvedia · 2019-08-14T22:25:37Z

to indicate the PR or SHA being reverted

@bcoe Instead of the # of the PR or MR, I would instead recommend to reference the merge commit or a range of commits or the branch if it still exists.

damianopetrungaro · 2019-08-15T20:36:44Z

@Mouvedia feel free to open an issue and work on a PR about it :D
#175 (comment)

damianopetrungaro · 2019-08-15T20:38:35Z

@Mouvedia it is totally up to the userland to specify it IMHO.
The important thing is that it respects the specs

#175 (comment)

> If included in the type/scope prefix, breaking changes MUST be > indicated by a `!` immediately before the `:`. To support this, you can now access `commit.breaking()` to get a boolean signaling if the commit contains breaking changes. You can still access `commit.breaking_change()` to get any optional message provided using the `BREAKING CHANGE: ` paragraph. If no `!` is provided, but the commit does contain a `BREAKING CHANGE` paragraph, the `commit.breaking()` method will also return `true`. While the API is a bit awkward right now due to having `breaking` _and_ `breaking_change`, this is only temporarily, until Git trailers are implemented, and the special `breaking_change` method will be removed in favor of a generic map of trailer key/values with one of those trailers having the key `BREAKING CHANGE`.

bcoe · 2019-08-20T00:59:23Z

@damianopetrungaro I think @JeanMertz has put together a very sound proposal for eliminating ambiguity around body vs., footer. @JeanMertz, perhaps make a PR against this branch adding some of your edits?

I'm less convinced that we need to strictly define the behavior around revert, beyond giving some sound recommendations in the FAQ.

bcoe · 2019-09-07T02:48:07Z

I think it would be good to include revert just for completeness.

@Mouvedia @stevemao I've added an FAQ section providing suggestions for handling reverts, based on the angular convention.

For releasing v1.0.0 of this specification, I'd like to argue that this is a reasonable start (we can expand on it further in the future if we want to support Revert "feat: foo", but I have fears that we're adding a lot of complexity to the spec, for a situation that's fairly rare).

Breaking changes MUST be described, but body is optional, therefore BREAKING CHANGES: in body shouldn't be mandatory.

@tommywo @damianopetrungaro I think we've done a good job of word-smithing the relationship between ! and the BREAKING CHANGE footer in #185.

regarding body ambiguity

@epage @JeanMertz, with your help I think we've done a much better job of making the difference between footers and body well defined.

So what do folks say, shall we get this to v1.0.0? (keeping in mind we an always release v1.0.1 35 minutes later.)

JeanMertz

Very nice improvements to the spec. Looking forward to seeing this merged. I left a few comments, but nothing blocking.

content/next/index.md

content/v1.0.0/index.md

Mouvedia · 2019-09-07T09:20:08Z

content/next/index.md

@@ -2,7 +2,7 @@
 draft: true
 ---

-# Conventional Commits 1.0.0
+# Conventional Commits 1.0.1


Are you sure about the patch?

zeke

✨ 1️⃣ ✨

bcoe · 2019-09-17T18:30:04Z

Haven't forgotten about this, have just been swamped 😆

@damianopetrungaro you're comfortable with landing this once I address comments?

damianopetrungaro · 2019-09-17T19:54:15Z

@bcoe sure I am!
It looks good, there are all already comments for thing to review and change 😄

Thanks for pushing it forward! 💪

tunnckoCore · 2019-09-30T04:44:21Z

Ahhhhhhh... Sadly, couldn't get sooner to that, nor pinged... Just was reading it when you merged it and was going to point a few things:

12 and 13 could be 11.1 and 11.2 instead;
So, no switching the places of "optional scope" and "optional bang"? I think we commented around that somewhere? 🤔
- feat!: foo bar and feat!(cli): something
- it looks and feels better, and familiar to function invocation syntax of some languages (Rust, first in mind). Yea, CC isn't a programming language to be similar, but still, it feels good on eyes. As dev creatures, I think that we appreciate such little things.
Definitely don't like the language around "footers". It's a single footer with possibly multiple trailers. Why not inherit that language from the git trailers, but instead calling it "multiple footers"? It sounds strange.
Don't think that Acked-by is the best example. Probably Reviewed-by or Signed-off-by are better choices.

bcoe · 2019-09-30T16:27:35Z

@tunnckoCore if you look at the final edit that landed, we refer to things as "multiple footers" not as trailers (we only reference tailers a couple times, pointing out that they inspired the footer parser).

For the other minor changes, send a patch and we can release 1.0.1 (would be worth doing ASAP before translations start to roll in).

Mouvedia · 2019-09-30T18:49:09Z

Probably Reviewed-by or Signed-off-by are better choices.

@tunnckoCore I think a better example would be Co-authored-by:.

tunnckoCore · 2019-09-30T22:35:37Z

@bcoe: if you look at the final edit that landed

Exactly, that's my proble 😆 I don't like it and sounds me strange. It would be better to just follow the git trailers language: "Multiple trailers inside a single footer. And what's a footer? Well, it starts where the first trailer starts. What's body? It begins after the first line, and ends where the footer starts (first found trailer)".

@bcoe: For the other minor changes

Yep.

@Mouvedia: I think a better example would be Co-authored-by:

Agree, haha.

bcoe · 2019-09-30T22:39:18Z

@tunnckoCore I think we're different enough from trailers, that I kind of agreed with @JeanMertz's recommendation to not tie us to them too tightly.

tunnckoCore · 2019-09-30T23:02:37Z

I don't see any difference. Each token/value pair is a trailer. What's the difference between "multiple footers" and "git trailers"? In abstract world, they are childs of a footer.

                  CommitMessage
              /          |        \
           /             |           \
       Header           Body           Footer
     /   |   \           |               |  
type  scope  subject   paragraphs      trailers

* "subject" is officially called description

Example commit message:

feat: meow meow, yawn

foo qux

bar
var

zero barry
deal

Reviewed-by: Zzz oops
Some-thing: Multiline important

trailer woohoo
meow meow

Why not?
yup!

Signed-off-by: Foo <bar@qux.com>

Parsed to object:

const commit = {
  header: {
    type: 'feat',
    scope: null,
    subject: 'meow meow, yawn'
  },
  body: 'foo qux\n\nbar\nvar\n\nzero barry\ndeal',
  footer: {
    trailers: [
      'Reviewed-by: Zzz oops',
      'Some-thing: Multiline important\n\ntrailer woohoo\nmeow meow\n\nWhy not?\nyup!',
      'Signed-off-by: Foo <bar@qux.com>'
    ],
    trailer: {
      'Reviewed-by': 'Zzz ooops',
      'Some-thing': 'Multiline important\n\ntrailer woohoo\nmeow meow\n\nWhy not?\nyup!',
      'Signed-off-by': 'Foo <bar@qux.com>',
    },
    raw: `Reviewed-by: Zzz oops
Some-thing: Multiline important

trailer woohoo
meow meow

Why not?
yup!

Signed-off-by: Foo <bar@qux.com>`,
  },
};

In the commit.footer object, some more advanced parser, could add more things such as mentions, references (based on trailers), and etc.

bcoe · 2019-09-30T23:18:35Z

@tunnckoCore could you please open several issues for these conversations, rather than commenting on a closed pull request?

The current implementation accepts compound nouns as types, but the first version of the spec is about to be released[1], and explicitly requires the type to be a noun. [1]: conventional-commits/conventionalcommits.org#175

bcoe requested review from zeke, stevemao and damianopetrungaro August 14, 2019 01:30

bcoe commented Aug 14, 2019

View reviewed changes

content/v1.0.0/index.md Outdated Show resolved Hide resolved

content/v1.0.0/index.md Show resolved Hide resolved

epage mentioned this pull request Aug 15, 2019

Parser doesn't support ! in the subject rustic-games/conventional-commit#4

Closed

bcoe added 2 commits September 6, 2019 19:01

chore: release 1.0 of specification

8a2472c

chore: update v1.0.0 doc

41f5176

bcoe force-pushed the one-point-oh branch from d0b1da4 to 41f5176 Compare September 7, 2019 02:20

bcoe changed the title ~~chore: release 1.0 of specification~~ chore: release 1.0.0 of specification Sep 7, 2019

docs: add missing ci

9678e4b

JeanMertz approved these changes Sep 7, 2019

View reviewed changes

Mouvedia reviewed Sep 7, 2019

View reviewed changes

zeke approved these changes Sep 9, 2019

View reviewed changes

JeanMertz mentioned this pull request Sep 9, 2019

Invalid Git tag - no exact reason why it's invalid? rustic-games/jilu#9

Closed

bcoe added 3 commits September 29, 2019 20:52

chore: address review

340c09e

chore: small copy edits

c0cfcff

chore: smally copy tweak

79d5240

bcoe merged commit 73c252d into master Sep 30, 2019

bcoe deleted the one-point-oh branch September 30, 2019 04:11

tunnckoCore mentioned this pull request Oct 1, 2019

After v1: About footer(s), git trailers and "multiple footers" #203

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore: release 1.0.0 of specification #175

chore: release 1.0.0 of specification #175

bcoe commented Aug 14, 2019

stevemao commented Aug 14, 2019

Mouvedia commented Aug 14, 2019

bcoe commented Aug 14, 2019

JeanMertz commented Aug 14, 2019 •

edited

Loading

Mouvedia commented Aug 14, 2019 •

edited

Loading

damianopetrungaro commented Aug 15, 2019

damianopetrungaro commented Aug 15, 2019

bcoe commented Aug 20, 2019

bcoe commented Sep 7, 2019

JeanMertz left a comment

Mouvedia Sep 7, 2019

zeke left a comment

bcoe commented Sep 17, 2019

damianopetrungaro commented Sep 17, 2019

tunnckoCore commented Sep 30, 2019 •

edited

Loading

bcoe commented Sep 30, 2019

Mouvedia commented Sep 30, 2019

tunnckoCore commented Sep 30, 2019 •

edited

Loading

bcoe commented Sep 30, 2019

tunnckoCore commented Sep 30, 2019 •

edited

Loading

bcoe commented Sep 30, 2019

chore: release 1.0.0 of specification #175

chore: release 1.0.0 of specification #175

Conversation

bcoe commented Aug 14, 2019

Reasoning

Let's Practice What We Preach

stevemao commented Aug 14, 2019

Mouvedia commented Aug 14, 2019

bcoe commented Aug 14, 2019

JeanMertz commented Aug 14, 2019 • edited Loading

Mouvedia commented Aug 14, 2019 • edited Loading

damianopetrungaro commented Aug 15, 2019

damianopetrungaro commented Aug 15, 2019

bcoe commented Aug 20, 2019

bcoe commented Sep 7, 2019

JeanMertz left a comment

Choose a reason for hiding this comment

Mouvedia Sep 7, 2019

Choose a reason for hiding this comment

zeke left a comment

Choose a reason for hiding this comment

bcoe commented Sep 17, 2019

damianopetrungaro commented Sep 17, 2019

tunnckoCore commented Sep 30, 2019 • edited Loading

bcoe commented Sep 30, 2019

Mouvedia commented Sep 30, 2019

tunnckoCore commented Sep 30, 2019 • edited Loading

bcoe commented Sep 30, 2019

tunnckoCore commented Sep 30, 2019 • edited Loading

bcoe commented Sep 30, 2019

JeanMertz commented Aug 14, 2019 •

edited

Loading

Mouvedia commented Aug 14, 2019 •

edited

Loading

tunnckoCore commented Sep 30, 2019 •

edited

Loading

tunnckoCore commented Sep 30, 2019 •

edited

Loading

tunnckoCore commented Sep 30, 2019 •

edited

Loading