Consider using conventional-changelog to generate changelog

[stevemao]

we have conventional-changelog or conventional-github-releaser (there are also grunt/gulp tasks) to automate the process of writing the changelog. As you are using formatted commit messages so the logs can be generated well according to the parts of the message. We use handlebars for templating the logs. It can also ignore reverted commits. There are many other features. We have a jquery preset for people using jquery commit format.
The modules are actively maintained.

[stevemao]

Sample logs

build

• add AppVeyor (028abf5)

deps

• accepts@~1.2.4 (117d0c9)
• ejs@2.3.1 (adb6069)
• istanbul@0.3.6 (1507757)
• jade@~1.9.2 (e56141a)
• serve-static@~1.9.1 (ce1abd9)
• should@~5.0.1 (fa546bf)
• type-is@~1.6.0 (e03ed05)
• update example dependencies (9a8cf77)

docs

• update badges (3882ba4)

examples

• fixes to mvc example (24fce9d), closes #2534

tests

• add extra setCharset tests (53e5991)
• fix error-handling typo (8fe5fd8), closes #2557
• improve res.download tests (ca480d7)

[dougwilson]

Oh, neat! is there a way to disable the git commit links using the tool? I usually don't want to link to commits, as it assumes that we don't rewrite history and that we'll always be on GitHub.com . One other question is for deps, I always include the dependency's own change log inline so the change message is more meaningful. Is it possible to do that as well?

[stevemao]

Its possible to disable the git commit links as it's using handlebarsjs. Btw you could always regenerate all your changelogs. For the deps, the git history isn't in your parent module so it's not possible. Why don't you just give a link of the changelog of the deps when you bump a dep in the parent module in the commit message? Or even copy and paste the deps changelog in the commit message?

[dougwilson]

Btw you could always regenerate all your changelogs.

So a simple git rebase would noe require me to stop a every commit and regen + re commit? We build our change log on every commit, not just on release, so it would be very tedious to throw this in. I think simply leaving out the commit hashes would be best (which I see you said it could do).

Why don't you just give a link of the changelog of the deps when you bump a dep in the parent module in the commit message? Or even copy and paste the deps changelog in the commit message?

So we don't provide links because it doesn't help people understand the difference when they are not online and it requires us to keep changing the history file whenever one of those moves (and also assumes the changelog is even accessible on the Internet at all, which is no guarantee, as something may be published to npm without a public repo).

Or even copy and paste the deps changelog in the commit message?

We could, but how will they show up? I see in the example you pasted above, it seems to just smash everything on one line (like you can see those "closes ..." are in the body of the commit messages, yet appear on the same line in the history). Could we get them to appear as indented bullets like we do today?

Another question for sub dependencies, if those sub dependencies then change to use this format, their change logs will no longer be a simple list, but a list with titles, etc. How can we easily translate that here as well?

I ask because I'm very interested in your module and I understand the purpose of it is to automate these things :) But I'm not willing to loose what we have now in order to get it.

[dougwilson]

Another thing that would help is if you could provide an example of how to generate that log you pasted above, or a PR that does :) Otherwise if I have to figure out how to invoke it, it may be a long time before anything is ever done to start using it.

[stevemao]

We could, but how will they show up? I see in the example you pasted above, it seems to just smash everything on one line (like you can see those "closes ..." are in the body of the commit messages, yet appear on the same line in the history). Could we get them to appear as indented bullets like we do today?

Because we are using handlebarsjs to template, in essence if handlebarsjs is able to do this we could. The format of your sub deps would depends on the markdown you put in the commit message. So I believe this is yes.

An ideal commit message would be something like this

deps: type-is@~1.6.4

The changes are
- blabla
- blabla

Another question for sub dependencies, if those sub dependencies then change to use this format, their change logs will no longer be a simple list, but a list with titles, etc. How can we easily translate that here as well?

Are you saying to transfer another modules changelog to a module and modify the format/contents a bit? This is out of the scope of my modules I believe. I think if you want to link two modules changelog it's really better to put ones in another's commit messages. This way it's even easier for people to view both logs (eg git log).

Another thing that would help is if you could provide an example of how to generate that log you pasted above, or a PR that does

This is generated by conventional-changelog -p jquery as the format of jquery message is almost the same. But since you want some templates/settings just for express we could add an express preset so you'll just need to do conventional-changelog -p express. Again there are grunt/gulp wrappers.

[stevemao]

https://github.com/stevemao/conventional-commits-parser is the parser we use to parse the messages.

The format of your sub deps would depends on the markdown you put in the commit message.

Meaning we don't parse the messages of the body part because this is usually long paragraph(s) so you could format using markdown by yourself in the commit. The header is the place usually you put different short parts of the message. In the footer you could put some important notes. But I believe you could put your sub deps information in the body.

[dougwilson]

Ah, gotcha. What would it look like to even make customizations, like customizing the templates? We don't (currently) use gulp/grunt, so hopefully it won't require that we use that to use this module, or it may be a long time before we get around to adopting.

Also, I forgot to ask, but is it possible to leave things out of the change log? For example, we never list things starting with "tests:" or "build:" or "examples:" or "docs" (really, everything except "perf:" and "deps:") in the changelog, so if it's possible to have this generator skip those commits, that would be ideal as well :)

Meaning we don't parse the body part of the message because this is usually long paragraph(s) so you could format using markdown by yourself in the commit message.

Would the body show as indented for the commit message in the changelog (like we do today with the sub dependencies)?

[dougwilson]

In the end, the change log right now is not hand-done, but done using scripts. This means that without getting some commands provided to us to use this module (perhaps a PR?) without us doing a lot of research just it's a large incentive, because the current changelog is fully automated already. I'm definitely interested in using something not hand-rolled, but I have pretty much no spare time to do any reading on how to get this module put together to give what we have now, so the more you can provide, the better the changes are for us to switch :)!

[stevemao]

What would it look like to even make customizations, like customizing the templates? We don't (currently) use gulp/grunt, so hopefully it won't require that we use that to use this module, or it may be a long time before we get around to adopting.

the gulp/grunt wrappers is pretty much a shortcut of using the cli. As I said we could create an express preset that holds all templates/settings just for express. (gulp/grunt has nothing to do with the template)

Also, I forgot to ask, but is it possible to leave things out of the change log? For example, we never list things starting with "tests:" or "build:" or "examples:" or "docs" (really, everything except "perf:" and "deps:") in the changelog, so if it's possible to have this generator skip those commits, that would be ideal as well :)

Yes. You could also change the name perf to Performance and deps to Dependencies.

Would the body show as indented for the commit message in the changelog (like we do today with the sub dependencies)?

Is the body indented because of markdown (I think it is)? As long as the template generates the same markdown its indented right?

In the end, the change log right now is not hand-done, but done using scripts. This means that without getting some commands provided to us to use this module (perhaps a PR?) without us doing a lot of research just it's a large incentive, because the current changelog is fully automated already. I'm definitely interested in using something not hand-rolled, but I have pretty much no spare time to do any reading on how to get this module put together to give what we have now, so the more you can provide, the better the changes are for us to switch :)!

I understand. I will definitely do a PR.

[stevemao]

It would be helpful if you could provide the markdown of a release as a sample, and I'll make a express preset that generates the same markdown (Although you'll need to write more in the commit message just for the deps you mentioned).

[dougwilson]

Awesome! I'm not quite sure, are you asking me to provide something? Something more than simply the Markdown we have in our History.md file right now? Let me know what I can provide :)

[dougwilson]

If I were to put the changelog of the upstream dependency within it's commit message, it would look like this:

deps: type-is@~1.6.4

  * deps: mime-types@~2.1.2
  * perf: enable strict mode
  * perf: remove argument reassignment

But also note that since I've never done this before, the exact format is up for compromise or whatever :)

[stevemao]

Sorry I didn't see that file. I was looking at your github releases :) we have conventional-changelog or conventional-github-releaser that can do both.

I think that commit message will work. In the meanwhile, I believe you need to add a commit message guideline and state that clearly in it (you could see jquery's as an example). the deps commit would be a bit tricky I think. It would be good for people who contribute and for me as a preset reference.

[stevemao]

Hi @dougwilson

Just letting you know that I've created a express branch and based on sample commits:

deps: type-is@~1.6.3\n\n - deps: mime-types@~2.1.1\n - perf: reduce try block size\n - perf: remove bitwise operations
perf: use saved reference to http.STATUS_CODES\n\ncloses #2602
docs: add license comments
deps: path-to-regexp@0.1.4
Bad commit

it generates:

2015-07-27
===================


### Dependencies

* path-to-regexp@0.1.4

* type-is@~1.6.3

 - deps: mime-types@~2.1.1
 - perf: reduce try block size
 - perf: remove bitwise operations




### Performance

* use saved reference to http.STATUS_CODES

closes #2602

which compiles to

2015-07-27

Dependencies

• path-to-regexp@0.1.4
• type-is@~1.6.3
  • deps: mime-types@~2.1.1
  • perf: reduce try block size
  • perf: remove bitwise operations

Performance

• use saved reference to http.STATUS_CODES

closes #2602

Note that version number or some links are missing that's because it's not in the real express git environment (this is the result of unit test).

[stevemao]

Using the express package.json and tweak the layout a little bit

4.13.1 / 2015-07-27
===================


### Dependencies

* path-to-regexp@0.1.4
* type-is@~1.6.3

 - deps: mime-types@~2.1.1
 - perf: reduce try block size
 - perf: remove bitwise operations



### Performance

* use saved reference to http.STATUS_CODES

  Closes [#2602](https://github.com/strongloop/express/issues/2602)

4.13.1 / 2015-07-27

Dependencies

• path-to-regexp@0.1.4
• type-is@~1.6.3
  • deps: mime-types@~2.1.1
  • perf: reduce try block size
  • perf: remove bitwise operations

Performance

• use saved reference to http.STATUS_CODES

  Closes #2602