Missing release notes for 16.0 release

[nulltoken]

Is there a chance to get some release notes about the new major version 16.0 in https://github.com/hapijs/wreck/milestone/67?closed=1 (As it happened, for instance, with #244 in https://github.com/hapijs/wreck/milestone/59?closed=1)?

[nulltoken]

Kind bump?

[Marsup]

Not sure it's worth release notes, issues speak for themselves: https://github.com/hapijs/wreck/issues?utf8=%E2%9C%93&q=is%3Aissue+milestone%3A16.0.0+is%3Aclosed

[framerate]

Not sure it's worth release notes

When you use this in a production environment, major semver is ALWAYS worth release notes.

For example, around the same time Joi was bumped from 15 ->16 too... same version numbers makes me nervous since wreck/Joi updates could be related and the Joi update is VERY breaking...

[Marsup]

Don't cut sentences and only extract what serves your point please. Changes are documented, just not regrouped in one single place this time. There is absolutely no relationship just because the versions bumps are the same.

[framerate]

Sorry, I'll be clearer:

Not sure it's worth release notes, issues speak for themselves: https://github.com/hapijs/wreck/issues?utf8=%E2%9C%93&q=is%3Aissue+milestone%3A16.0.0+is%3Aclosed

No, they don't. Maybe to a developer, but when I'm tasked with updating modules and see a major semver I'm going to look:

FIRST -> Github releases tab. This is where many developers put the breaking changes
SECOND -> CHANGELOG.md. This isn't often used any more, unfortunately, but I sitll check
THIRD -> Looking for release notes in the issue tracker by searching for "RELEASE NOTES" since this is what @hueniverse seems to do (and is appreciated!)

What I'm NOT going to do is google "github search syntax" and then assume you actually use their milestone feature 100% properly.

I'm a user of your software, and I'm not trying to be a dick but please don't take feedback by someone who actively uses your software and tell them they're wrong. I'm taking time out of my day to try and offer feedback that can help AT LEAST one of your users (me). Snarky responses from someone with a "member" label is definitely a turn off.

Hopefully that's better at getting my point across.

[framerate]

Also, I wouldn't make as big a deal except as I'm sure you're aware the definition of major semver:

MAJOR version when you make incompatible API changes,

If we as developers increment that first number I think it's very important to be clear wherever our users may look for it. It's usually as simple as one line.

[AdriVanHoudt]

I agree that an issue with release notes label should be there as the changelog.md points to these. Even if that issue then just links to the 2 breaking issues or the milestone page.

I don't agree with your tone @framerate, if you find yourself typing I'm not trying to be a dick but... just stop as you are probably being one.
I think constructive feedback is always appreciated but thinking you are entitled to something for freely using software that someone else wrote is not.

[sholladay]

FWIW, I think the reason that people get kind of upset about the conventions for release notes in the hapi ecosystem is because it's done in an unusual manner, so it sticks out. A lot of this comes down to expectations, even if those expectations are unfair.

I, too, have often discovered that there was a breaking change and then spent the next hour trying to figure out what the heck it was and what I was supposed to do. The information is technically there, even if it's buried within the commit history. But to a user, the details are very opaque. The commit history is potentially even useless to some less technical users. And even for people like me who have been using hapi for years, it can be very time consuming. To be clear, there is no obligation on anyone's part to write release notes for free. But if you're trying to upgrade, of course you want the information to be clear and easily accessible.

Some compounding factors:

• When there are release notes, they are in the issue tracker, which is weird. Even worse, they tend to become closed issues very quickly, making them much harder to discover. Because of that, it took me months to figure out these even existed when I first started using hapi, which initially lead me to believe that hapi was more of a prototype than a production project. It influenced my perception, even though I was wrong.
• There are many issues with no description whatsoever, even if they are labelled as breaking changes. This sets an implicit tone that we are not supposed to participate in the development, which also raises the expectation that there will be release notes to explain these opaque decisions. Of course, in reality hapi and its ecosystem are a breeze to contribute to and everyone is very responsive. It just doesn't look that way on the surface.
• The release notes for the core framework are very well written, standing in stark contrast to plugins. I love the breakdown of upgrade time, complexity, risk, a migration checklist, etc. It's amazing. Unfortunately, this attention to detail also increases expectations for the rest of the ecosystem. Super unfair, I know, but humans are weird. You wouldn't be shocked to see a $20 burger at a restaurant, yet the same exact burger would shock you at McDonald's. People use hapi for its attention to detail, so when it is missing, it is particularly noticeable.

Alright, so what about solutions?

Keeping in mind that we don't want to increase the burden on maintainers, I think one of the easiest wins would be to consider using np for doing releases. It's just npm publish with some sugar on top. Among other nice things, it automatically creates a GitHub Releases entry with the changes since the previous release. Users can then subscribe to the releases feed and easily see what is in each specific version, in a conventional place. Maintainers can edit the release notes to categorize the changes and explain them if they have time, but even without that, I would be excited about this improvement since it aligns hapi with common practices in other projects.

Another small improvement could be to use "help wanted" labels for some issues instead of just closing or implementing them right away. This would get new users more involved and thus increase the number of people who can write release notes or at least explain the changes in a given release to other users. As of late, GitHub exposes these issues in special ways in its UI to encourage contributions.

Finally, if the release notes are to remain in the issue tracker, then it would be good to at least point this out in each README, with a link to closed issues labelled "release notes", so that they are more discoverable. Perhaps there is something that hapi.dev can do to surface these as well.

[nulltoken]

Kind bump?

👋

My initial request may not have been clear enough and I do apologize for that. Let me try and provide you with some context.

There are two issues.

I do agree "💀 Node 8" is explicit enough. ;-)

However, I'm not so sure about the other one. It's labeled "Add types", but it's also decorated by a "breaking change" tag. By taking a look at the diff, it seems that it's not only about adding types.

From what I've quickly peeked at, at least downstreamRes was dropped.
I may have overlooked other changes.

And... I'm not familiar enough with this codebase to be able to feel confident parsing this change and being 100% sure I haven't missed anything.

Hence my initial request for some release notes.

Cheers!

[hueniverse]

Let me bring this discussion to a conclusion.

First some housekeeping:

Any kind of tone, hostility, or signs of entitlement are simply counterproductive. There are people with answers. If you want them to help you, for free, at their own expense, you need to show up and be the nicest version of yourself possible. Or pay.

@nulltoken the issue template is there for a reason. Next time, please make sure to use it, even if it is just a few lines for documentation related questions.

@framerate your comments came off hostile. Doesn't matter if you meant it or not. The fact that you are using this software doesn't mean anything. It doesn't entitle you to anything. The two ways to earn rights in this organization are to contribute (code, docs, help others) or to get a commercial support plan. Basically, you need to cover the cost of your request through actions or funds to get service. Using the software adds no value to anyone but yourself. You are always welcome to use it, but the way you phrased yourself made it sound you deserve to be treated well and we should help you simply because you are using free code.

@sholladay I agree that the current setup isn't great. It evolved before github releases were available and other tools. I am unlikely to change the manual process through which I publish releases. But I am planning on changing how you get to access that information. Like everything else, I am pushing people off GitHub and on https://hapi.dev. I don't want people to come here for anything other than opening issues. There is already work underway to remove all the changlog files and replace them with a simple link in the readme to a new hapi.dev resource.

Now, as to the actual changes -

There are two trivial breaking changes in this major release:

• Drop node 8 support
• Add TS types

That's it. If you have been following my work long enough, you know that I don't sneak in breaking changes and not document them. There is never a need to look at commits. If you are not sure what an issue means, you can just ask on that issue.

In this case, dropping node 8 is pretty obvious. Adding types means just that - adding TS types to the module. This is a breaking change to TS users because they are probably using the DT types which are not compatible. This is how I've been doing it throughout the org when adding types.

Those of you digging around the code noticing the removal of downstreamRes should note that it wasn't doing anything for years. It was leftover from the very first version of wreck when it was part of hapi core and was used in the code that is now h2ho. I just removed it because it was a useless appendix. It was part of the types issue because it was discovered when I was documenting all the options (as well as cleaning up the code format).

In conclusion -

This major release is indeed trivial and simple. It is a major release because it breaks node 8 support and existing type definitions. That's it. Just because you expect major releases to be big, doesn't mean they are. I don't see the need to spend extra time writing release notes for something that is as trivial as reading the two issue titles.

Moving forward this will be available in a much simple format on hapi.dev. As always, if you do not understand what a specific issue means, just ask.

And finally -

I look at every issue when it is opened. If it is covered by a commercial support plan it gets immediate attention. If it is not, it goes to the end of my queue. My queue is pretty full. I am working to get more information into the hapi.dev site so it is easier to find. That's a work in progress.

[framerate]

Thanks @hueniverse. And apologies to anyone who took my initial comment as hostile. The nature of text-only comms, I guess. My later ones WERE hostile 100% though and I apologize. I felt attacked for having a different opinion and that's never fun for anybody.

To perhaps help further on my end, would you accept a PR to fix the changelog which currently lists:

Breaking changes are documented using GitHub issues, see issues labeled "release notes".

Maybe something as simple as

Breaking changes are documented using GitHub issues when necessary, see issues labeled "release notes".

Or something similar? That's what led me here in the first place as the semver implied breaking but the changelog was a dead-end. I'm willing to help to prevent stuff like this from frustrating future users, I'm just not sure the best way to contribute here.

Thanks again

[hueniverse]

@framerate this should resolve itself in a week or so when the changelog files are completely replaced.

[framerate]

Got it. Thanks Eran. Appreciate you <3. Sorry for contributing some negative energy yesterday!

…

---- *- justin *| @framerate <http://twitter.com/framerate> | framerate.io

On Tue, Nov 12, 2019 at 2:22 PM Eran Hammer ***@***.***> wrote: @framerate <https://github.com/framerate> this should resolve itself in a week or so when the changelog files are completely replaced. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#265?email_source=notifications&email_token=AAASEMZOEZAVUNMU667GX6TQTMUCRA5CNFSM4JCKKCZKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOED4FAEY#issuecomment-553144339>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAASEM3NG3ZHXP4VFTVOV6LQTMUCRANCNFSM4JCKKCZA> .