Webpack.js.org: Proper Webpack 2 release announcement

[dmitriid]

This issue is meant to discuss and construct a proper announcement for the release of Webpack 2

I’m a bit under pressure to write this quickly, so there are bound to be typos and I probably sound more terse than I intend to. Feel free to ping me to change wording, and feel free to edit the issue to your heart’s content.

---

Webpack 2 has finally been released and this is the announcement: https://medium.com/webpack/webpack-2-2-the-final-release-76c3d43bf144

However, the link above is not really the announcement of Webpack 2. It's an announcement for a minor release, apparel, VIP hours and training. There's nothing in that post to indicate that this is a release announcement. We had a brief Twitter conversation with @TheLarkInn about this: https://twitter.com/dmitriid/status/821597584414441474 It looks like a shouting match, because Twitter :)

Below I'll try to lay out an idea for what a release announcement could look like and why I think the latest blog post on Medium isn't it.

---

Overview

Webpack 2 is the biggest baddest release ever. It's arrival should create an oomph to reverberate through the JS world

So, a release announcement should/could contain:

• A clear indication that it is the official release of Webpack 2
• A list of features that make this version different from version 1
• A clearly spelled out strategy for version 1 (support, sunset, phase out, deprecation)

Also, this announcement should be clearly visible and accessible everywhere: in the README, in v1 docs, on the new doc site

The current announcement as it exists can only be deciphered by people:

• who follow the blog
• who follow webpack 2 development

If we approach the text by someone who doesn’t follow webpack 2’s development closely, the announcment provides little to no clue as to what’s going on :)

Case in point (the tweet that started this train of thought):

For a person coming from outside of webpack’s development, those three bullet points with features are the only information I can find about, well, webpack 2’s features.

Concerted effort

• The README has 1.x banners
• The README has “the README is for version 1”
• webpack.github.io has no announcement that v2 is released and that v1 is deprecated
• https://webpack.js.org has no announcement that webpack 2 is out of beta

An official release with announcement should be reflected across all of webpack’s properties

When

For the first week Webpack 2 is only available under webpack@beta The Medium post shows me it was written 12h ago, so this means I can use the “proper” webpack … moment().subtract(12, ‘hours’).add(7, ‘days’)? Maybe? :)

The release announcement should clearly state: “you can get it now”. Or: “you can properly get it starting Monday, Jan 23rd, Greenwich time”

---

So what can we do?

Create a proper release announcement :)

The template should be something like this:

# Webpack 2 is released!

- Get it here <link>
- Read the docs here <link>
- Getting started <link>
- v1 is deprecated. Migrate from v1 <link>. Sunset roadmap for v1 <link>

We also announce

- VIP hours <link to details on website>
- Services  <link to details on website>
- Merchandise  <link to details on website>

Read on for details

## New feaures

Here’s what you get in webpack 2

- ES6 <link to description in docs>
- Tree shaking <link to description in docs>
- feature X  <link to description in docs>
- feature Y  <link to description in docs>

### ES6

Short description.. For details <link to description in docs>

### Tree shaking

Short description.. For details <link to description in docs>

### Other features if they are big enough, 
    you can bundle several together in one section

Short description.. For details <link to description in docs>

## Policy for v1

It’s deprecated. <Here’s migration guide>. 
Docs will be shutdown in 6 months. No bugs accepted. 
More info here <link to docs>

## VIP hours and Services

This and that, <link to description in docs>

## Merchandise

This and that, <link to description/shop>

In addition to the release:

• All pages on the v1 docs site should carry a big red banner at the top saying: v1 is deprecated, go to v2 docs site
• The README should reflect it’s version 2. It should have a big link to the announcement for the first couple of weeks
• The v2 docs site should have a big banner saying it’s been released with a link to the announcement. Preferrably on all pages, only for a couple of weeks.

This way there will be exactly zero confusion as to what is released, when, and where :)

[dmitriid]

I also just realised it's in webpack.js.org, not in webpack. It's still fitting? If not, I can recreate it in webpack

[dmitriid]

Additionally: a proper release announcement will help with the doc website itself. For example: webpack 2 introduces tree shaking. There is no info on the current documentation site about this feature. It's only mentioned twice in the docs here and here

UPD. With the help of a specific Google search I discovered a link to an external blog post about tree shaking in Webpack 2 on this page

There are undoubtedly other features.

[dmitriid]

Any love for this issue?

[TheLarkInn]

We are planning on a medium article for when we switch tags from beta to latest, but candidly speaking, this article will be more focused on the infrastructure changes we are adding to the organization. This includes:

• github.com/webpack-contrib
• webpack adopts continuous deployment. (Can get nightly releases on @next tag.
• webpack-china (just a recap)
• and a second contributor spotlight
• What's ahead:
  
  
  
  • voting update
  
  
  • Milestones (2.3, 2.4 and beyond)
  
  

[dmitriid]

But... But... Why?

Why not do a proper release announcement?

Argh. Nevermind. I'm tired of trying to teach programmers that they must communicate their intents clearly.

I still rememer when "package.json in master is set to 2.x, so it's clearly version 2" :-\ It's a losing battle

[dmitriid]

One thing though.

There's not even a list of features of webpack 2 (such as tree shaking etc.). So there, my last attempt at improving webpack communication.

[TheLarkInn]

No I understand what you are saying. But consider the optics of releasing what would appear a duplicate announcement from us. It dilutes the quality of the publication. I agree that we need to (looking forward) take into action some of the exact points you mention.

In terms of feature list, we can cover that, I think thats more than reasonable. And when I make the draft I will link it here for you to assist in editing if that is okay with you.

[TheLarkInn]

Argh. Nevermind. I'm tired of trying to teach programmers that they must communicate their intents clearly.

PS: Be careful how you word things. To someone like myself who represents the voice of both webpack and its users, this doesn't bother me because I've heard it all, however there are other who could be offended by that kind of language. We want to aim to be as positive as possible!

[dmitriid]

Think of the optics of releasing what would appear a duplicate announcement from us.

Appear to whom?

It dilutes the quality of the publication

There's no quality in your current publication. See original post, I won't re-iterate.

I agree that we need to (looking forward) take into action some of the exact points you mention.

Looking forward to what? Webpack 3?

How can I, as a developer, know:

• that 2.2 === 2,
• that v1 is deprecated,
• what webpack 2 does, and why I should ever go to the trouble upgrading?
• etc.etc.etc.

?

Because the "release announcement" contains the word "finally"?

I only know this because I've been fighting a losing uphill battle to get info out of webpack team. And every step of the way you refused to acknowledge this as a problem.

when we switch tags from beta to latest

"We will leave the final release on npm published under the beta tag for the first week.". This was 10 days ago. So, even the "release announcement" is incorrect.

So, the next time (at one unknown point in time) when someone upgrades and gets 2.x.... There will be exactly zero info on why this happened. Anywhere.

Because, apparently, info about voting is much more important than to let people know exactly what was released and what to expect. But what do I know. I'm just a dev, who's struggled to wriggle info out of webpack for several months now.

I'm closing this ticket, you clearly don't care. I'm also willing to bet that when "the beta tag is removed", there will be no info about the release in the README, or on webpack.js.org, or on webpack.github.io etc.etc.etc., see original issue.

[dmitriid]

The problem is, as always, the bubble. A.k.a. textbook example of developers failing to understand the need to communicate.

"I work on project X, my buddy works on project X. Thus, everybody in the world is intimately familiar with project X".

• What does X do? — Oh, we tweeted about it a month or so ago
• What are the features? — Oh, it's in the changelogs, duh
• Where can I learn about?... — Oh, for effs sakes, there's a link to a website discussing this. Just search the issues

etc. etc. etc.

I see no point in keeping this issue open. You will not address a single issue discussed in this ticket. Your next "release announcement" will contain zero info about the release. In a year or so everyone will be on webpack 2 and the same story will repeat all over again with webpack 3.

Just close the issue.

[TheLarkInn]

Okay, a bunch of points here.

Everything you are saying is valid and I agree with. This is what we are going to do:

• Announce that webpack 2 final is moved to latest tag.
• Describe the features that are different between 1 and 2 (briefly)
  
  
  
  • explain why you want to upgrade
  
  
  • mention that webpack 1 is deprecated
  
  
• Describe the other things happing in the webpack ecosystem
• Talk about the roadmap further

Okay now to address some other stuff:

There's no quality in your current publication. See original post, I won't re-iterate.
This is subjective.

Because the "release announcement" contains the word "finally"?
Contained Final release. Again out of the 100k reads, i've only had 2 people question this information. Based on that sample size I think it's a valid hypothesis beyond reasonable doubt that this was the final (out of beta out of rc) webpack 2 release.

The problem is, as always, the bubble. A.k.a. textbook example of developers failing to understand the need to communicate.

As someone who has poured a lot of hours and time into ensuring that the messages that we spread to our community is understood and heard, I can say that our communication efforts have been extremely successful. Including this latest post that was the impetus for this issue. Is it newspaper publication quality? Probably not. Is there work to be done still, yes.

Let me remind you: This is an Open Source Project, in which no maintainer or contributor works full time on. We are doing the best that we can, and will continue to improve with the help from the community. The most time spent, is by myself, ensuring that every user (including yourself)'s needs or concerns have been addressed.

I see no point in keeping this issue open. You will not address a single issue discussed in this ticket. Your next "release announcement" will contain zero info about the release. In a year or so everyone will be on webpack 2 and the same story will repeat all over again with webpack 3.

Honestly my reaching out to you when you initially made this statement was an exciting opportunity for us to work together to improve something that (since June) has been a work in progress (and a great improvement since our first post).

However what I have witnessed is the following that will not make this a possibility in the same way I imagined:

• Blanketed, non-constructive criticisms,
• Condescending tone
• Inability to be flexible when another person (especially a maintainer of an OSS project), suggests some sort of middle-ground.
  
  
  
  • 2nd to last paragraph
  
  
  • last paragraph
  
  

None of these things are tolerated when communicating with developers, _ever_.

Regardless, because I agree with many points of your criticism, I will leave this issue open until our next publication is released. I will provide a draft of the article when the publication needs review, and I would like for you to review it.

[dmitriid]

Everything you are saying is valid and I agree with. This is what we are going to do:

Yes, thank you!

Honestly my reaching out to you when you initially made this statement was an exciting opportunity for us to work together to improve something that (since June) has been a work in progress

"I agree with everything you say", "you make excellent points", "I agree with your points" and then... "We are not going to do any of your points that I so agree with". Until I basically have to scream to make myself heard :-\

I didn't event know anyone paid any attention to this issue until today.

Blanketed, non-constructive criticisms

Please re-read the issue.

Condescending tone

Please re-read the issue.

Inability to be flexible when another person (especially a maintainer of an OSS project), suggests some sort of middle-ground.

Please re-read the issue.

I gave all the benefits of a doubt. I reached out to you, made my point very clear, I presented a clear definition of a problem, I presented a possible solution. I clearly stated I would be willing to help with this.

I outlined the whys and the hows. While preparing the issue I uncovered additional problems (like the docs lacking any and all descriptions of the major features shipped with webpack like tree-shaking).

Result? "Oh, we are not going to do anything, it dilutes the quality of publication". _There was no quality to dilute_ and _you personally agreed with all the points I made several times_.

Is it newspaper publication quality? Probably not.

I never asked for a newspaper quality. I asked for a release announcement.

And yes. I fully understand what it means to be OSS and to write docs, announcements etc.

[dmitriid]

Old documentation update: https://github.com/webpack/docs/pull/93

[dmitriid]

I could not wrap my head around the new doc site's structure, but it would by nice to add Typescript-like bar at the top of all pages annnouncing webpack 2's release (with relevant links)

[TheLarkInn]

https://medium.com/@TheLarkInn/webpack-2-and-beyond-40520af9067f

As promised here is the medium draft. Because webpack 2.2.1 is already in latest as we speak, I am going to just release this information and focus on webpack-canary and webpack-contrib in a separate post.

[simon04]

The performance budgets are off by default? https://github.com/webpack/webpack/pull/3604

[dmitriid]

This is absolutely brilliant 👍💪 Can't wait to see this published!

I was going to grumble about not including the deprecation info :) , but then realised it's already there in the old docs (+ pending this minor pull request: https://github.com/webpack/webpack.github.com/pull/13)

[TheLarkInn]

@simon04 the console warnings are off by default but there is still some general feedback inline by highlighting the modules and a [big] statement.

[simon04]

This has been done using https://medium.com/webpack/webpack-2-and-beyond-40520af9067f#.hx4i1hv12 and #847.

[dmitriid]

Perfect!