search

shellscape / webpack-plugin-serve

A Development Server in a Webpack Plugin
http://shellscape.org
Mozilla Public License 2.0
338 stars 53 forks source link

Keep a CHANGELOG #43

Closed G-Rath closed 5 years ago

G-Rath commented 5 years ago

Documentation Is:

Please Explain in Detail...

Changelogs are useful for knowing what changed in a... log?

But seriously: It's be awesome if a changelog was used to track changes between releases, as it makes things easier for developers to find out what to expect when comparing versions, without having to read through all the commit logs.

Your Proposal for Changes

Keep a Changelog

G-Rath commented 5 years ago

webpack-nano also doesn't use a changelog, but it at least has release information in the Releases section on github - let me know if you'd like me to make a separate issue for this on that repo 😉

shellscape commented 5 years ago

We'll be updating the releases page for the next version. 🍺

G-Rath commented 5 years ago

@shellscape while that's a nice start, personally I prefer having a CHANGELOG.md, as releases is a github feature; meanwhile, a CHANGELOG file will follow the code around, until it's explicitly left behind.

In particular, this means CHANGELOG usually ends up being published in the npm package, and so is available with each version of the package (as well as being available offline).

shellscape commented 5 years ago

Thanks for explaining. My personal preference is different. While we might be able to automate a changelog from the releases, I can pretty much guarantee it won't ship with the NPM package :smile: I like to keep packages as lean as humanly possible.

shellscape commented 5 years ago

Have given this a great deal of thought (as all suggestions for change in direction should!) and I still prefer the releases tab. We use https://www.conventionalcommits.org/en/v1.0.0-beta.2/ style commit messages (which is also what Angular uses) along with tagged npm versions and squashed commits - so either using git log or Github's commit history would be just as effective as a Changelog in that way. It took me a while to find, but this comment perfectly summarizes why I prefer the Releases tab over a CHANGELOG artifact.

G-Rath commented 5 years ago

@shellscape Here's the reply I should have given 6 months ago, if I'd managed to remember about how npm works :joy:

I can pretty much guarantee it won't ship with the NPM package

I can guarantee that it would, since npm always includes CHANGELOG if it exists, regardless of your settings:

The following paths and files are never ignored, so adding them to .npmignore is pointless:

  • package.json
  • README (and its variants)
  • CHANGELOG (and its variants)
  • LICENSE / LICENCE

(This also applies to the files property, where npm will add the above files to the array internally)

To me, this indicates that npm feels CHANGELOG is something that should be distributed with the rest of the package, which is something I agree with.

The releases tab is a github-only feature, and not accessible offline - say for example you removed your github repo (maybe a left-pad kind of situation, who knows, but it could technically happen). If you have an application that's dependent on an old version of that package, and you decide to update that dependency, by having the CHANGELOG bundled with every version of the package you'd at least have a chance of figuring out everything you've got to do for that update, even tho the original repo is gone.

It's a somewhat extreme, but still relevant (of which left-pad is a great example) argument.

Git is great, when its there - but once a package is bundled & on npm it's out of the git infrastructure. It's also great to keep packages lean, but CHANGELOGs are typically really small compared to the rest of the package.

I understand both sides of the fence, and so I'm happy so long as changes are recorded somewhere sane, but I stumbled across the npm link while setting up a new package of my own for publishing, and was like "omg why didn't I remember this half a year ago when talking with Andrew about changelogs!?"