Prepare CHANGELOG and release planning

[jeddy3]

Tried to remove the redundancy from the changelog to make it clearer and easier to read. Updated the release planning doc to only include things that requires the community’s help e.g. new plugins or helping out with existing ones (e.g. stylelint-order)

[hudochenkov]

Much cleaner! Thank you!

[davidtheclark]

I think we should be more verbose here, because these are major changes and users will want to know what's going on. How about grouping rules by category and providing suggestions about what to do (what to use & contribute to) if you liked the rule(s). For example, all of the spec validation rules could be grouped with a statement like this:

It is beyond the scope of stylelint's core package to effectively validate against the CSS spec. Please investigate csstree and css-values for this functionality, and contribute to those projects. csstree already has a stylelint plugin, and css-values needs one to be developed.

[jeddy3]

because these are major changes and users will want to know what's going on

Agreed, but I thought that is what the release planning document was for? i.e. a canonical place we can keep up to date with evolving suggestions about what to do leading up a release.

For example, all of the spec validation rules could be grouped with a statement like this:

Agreed. At the moment I've split out the wrapping rules into their own group and kept declaration-block-properties-order by itself. Splitting out the validation rules into their own group makes sense. Any other suggestions?

[davidtheclark]

I thought that is what the release planning document was for

I think many, many fewer people will read the release planning document than the changelog. I, for example, have never bothered to read a release planning document ever. Changelog is the place you look when changes have been made, and you want to know what they are, how to adapt — a release planning document sounds like the place you look when you are trying to contribute or wondering what is coming next.

Splitting out the validation rules into their own group makes sense. Any other suggestions?

Yeah, I think every rule should have an explanation about what to do next. So:

• Rules that simply wrap a third-party library. We encourage users to create and help maintain plugins for these rules.
  • no-browser-hacks
  • no-indistinguishable-colors
  • no-unsupported-browser-features
• Rules that did not seem useful. If you liked these rules, please create plugins for them.
  • root-no-standard-properties
  • custom-property-no-outside-root
• stylelint-disable-reason did not work well. Please consider contributing to Add reportUnscopedDisables flag #2292 for a replacement.

I think that the above, combined with spec validation and rules that already have a note, should cover it.

[jeddy3]

I think many, many fewer people will read the release planning document than the changelog. I, for example, have never bothered to read a release planning document ever. Changelog is the place you look when changes have been made, and you want to know what they are, how to adapt

I agree. I'm trying to remember why we did the releasing planning document split for 7.0.0, but it escapes me. Anyhow, I'm agreement. I'll update CHANGELOG and retire the releasing planning doc.

[ntwb]

❤️

[jeddy3]

Sorry guys, it got late here. I've pushed up what I've got so far. I can pick things up tomorrow if no else gets around to it before then.

[jeddy3]

It took a little longer than expected (as there were a few things to iron out across the repos), but things are looking good for a release now.

The demo, standard config and stylelint.io repos now all look good when used with this branch (which is rebased off master). Tests are passing and the links on the website appear dandy.

@davidtheclark I'm going to have to bail for the night. Are you able to update the CHANGELOG in this PR/branch to your liking? I can then give it a quick once over in the morning before releasing. Sound good?

[davidtheclark]

@jeddy3 I just committed modifications to the changelog. Thanks for preparing this release!

[jeddy3]

I just committed modifications to the changelog.

Awesome. Looks great!

[ntwb]

"Updated the release planning doc to only include things that requires the community’s help "

@jeddy3 Rather than "Updated" the entire "release planning doc" markdown file and link from the user guide have been removed, I just wanted to ask to confirm that this was intentional?

[hudochenkov]

@ntwb it was intentional. Look at thread #2299 (comment)

[ntwb]

@hudochenkov Awesome, thanks, I didn't expand the diff to see those comments.

I think this is a fantastic change, my goto is to always to read the release notes, if there are none then I'll start scouring a repo for a changelog.md or changelog in the readme.md but as David pointed out never a release planning doc 💯