Incomplete changelog--what are the breaking changes in v3 and v4?

[ecraig12345]

Since the changelog and release list are both incomplete, it's difficult to figure out what breaking changes were made between 2.x and 4.x.

With the recent CVEs and large number of packages that still depend on 2.x (#165), suddenly a lot more people have this question, and need to understand what might break if they force a local update to 4.x. I personally could figure this out from the commit history if I have to, but this impacts thousands of repo maintainers who now have security alerts, and may not have the time or expertise to painstakingly shift through the commit history (with its varying quality of messages).

A complete changelog would also make it a lot easier for other package maintainers to evaluate whether it's safe to update their package's picomatch dependency to solve this problem for their users, and what to put in their own changelogs about potential breaking changes.

The request: to the maintainers who do understand the history of changes, please update the changelog with at least the list of breaking changes in each major release. The commit history alone is not a usable changelog.

[jonschlinkert]

"what broke from 2.x to 4.x?"

Is this a real question or a hypothetical?

"With the recent CVEs"

Ask the people who created the nonsense CVEs to create the changelog.

[ecraig12345]

Of course it's a real question--if I'm wrong, please link to the location where this is clearly explained.

I'm well aware that the CVEs are largely nonsense for actual usage, but that doesn't change the fact that many thousands of repo maintainers are required to respond to them, which becomes problematic for the reasons I explained above.

[TheLarkInn]

+1 here from my org as well @jonschlinkert and @doowb

Is there any contributions you would accept or design review for a changelog publishing system? I'm getting cooked by CVE's and I'm at the point where I'd be willing to help and reorganize some things we I can know which versions are safe and resolve my CVE's. Appreciate all the work you're doing. 🤗

[jonschlinkert]

"that doesn't change the fact that many thousands of repo maintainers are required to respond to them"

How is this related to release history? I really feel like I'm completely missing something here.

"what broke from 2.x to 4.x?"

1. Which thing broke? I don't know, so you'll need to explain what broke. I'm really not trying to be critical, you have not stated an issue.
2. Which version specifically broke?

After we figure that out, we can then determine if something in a CVE is somehow related. I'll reopen this to allow others to chime in so we can get clarity.

---

This is the current release history, which states that notable changes will be documented here.

[jonschlinkert]

Is there any contributions you would accept or design review for a changelog publishing system?

Yes absolutely @TheLarkInn, that would be great, thanks!

[doowb]

@ecraig12345 are you just saying that we need to add the CVE to the changelog?

[ecraig12345]

So...after taking another look at alerts for different versions, I see that picomatch@2.3.2 is already patched, and has a github release. Not sure how I missed this before--if anything this underlines the problem of mostly-nonsense CVE noise, that I'd been looking at so many alerts across so many repos and packages that I thought I'd looked carefully here, but got confused by the partial CHANGELOG.md and the invalid related issue #165... Sorry about that.

Going back to the original question, since it's still somewhat relevant: a better way to phrase it is "what are the breaking changes in 3.0.0 and 4.0.0," including behavior changes and Node version requirement changes? This is the same question I'd ask when considering any major upgrade; CVEs just mean more people are suddenly looking at the changelog and potentially getting confused by missing entries:

• 3.0.0: this has no changelog entry or github release (and the description of 3.0.1 just sounds like a non-breaking patch change), so it wasn't clear what prompted the major bump. From digging into the commit history I can see that the reason is Remove process and path dependencies, document windows option #73, but it would be helpful if that was explicitly listed. Same with the engines.node bump in 3.0.1.
• 4.0.0: has a changelog entry, and I guess feat!: remove process global to work outside of node #129 is the breaking change, but it would be helpful to specifically call that out. I also don't see any changelog entry or github release for 4.0.1 (engines.node bump) or 4.0.2.
• The most recently released versions have github releases, but no changelog entries--if this is the intended approach going forward, it would be helpful to add a note at the beginning of the changelog linking to the releases page.

Would you be open to a PR updating the changelog to add the missing entries? Ideally this would come from the maintainers who have more context about the history and nuances of the library, but I recognize this is probably not your day job and you're also busy with other things.

[jonschlinkert]

Sure @ecraig12345 that would be great.