Deprecated command and broken link

[sgammon]

Hello there,

When trying to follow the example for this CloudFlare workers package, I cannot proceed past the wrangler generate step because CloudFlare saw fit to deprecate completely remove this feature.

Now, instead of working, it fails with an error message:

⚠️  DEPRECATION:
`wrangler generate` has been deprecated, please refer to https://github.com/cloudflare/wrangler2/blob/main/docs/deprecations.md#generate for alternatives

If you think this is a bug then please create an issue at https://github.com/cloudflare/wrangler2/issues/new.

This is not entirely true as the definition of the word deprecate[^1] when used in a software context implies that "... [a feature] be usable but regarded as obsolete and best avoided..." (emphasis mine). Since the feature cannot be used at all, it would better be described as retired or deleted.

Normally, I realize this would just be a deeply frustrating experience for the developer, and not actually considered a bug, per se. But the link doesn't work, and instead yields a 404 on Github.

Since wrangler2 was, until this month, marked as unstable, maybe it would be best to keep this link alive. In fact, it looks like the entire docs directory was removed from the source (maybe it existed at one time?), so there is no easy way to go find the file even if you look for it manually:

trying to follow your deprecation retirement and forced migration guide

[^1]: deprecate: verb, "(chiefly of a software feature) be usable but regarded as obsolete and best avoided, typically due to having been superseded." Oxford Dictionary via Google.

[sgammon]

for anyone else stumbling on this issue, i am betting this page is what was intended to be linked: https://developers.cloudflare.com/workers/wrangler/migration/deprecations/

[rozenmd]

Hi @sgammon, sorry you ran into this issue.

I recently (as of wrangler v2.0.3) updated the error messages to point to the right place (https://developers.cloudflare.com/workers/wrangler/migration/deprecations/, as you eventually found).

I'll also try get that example updated too.

[sgammon]

Hey that's great. Instead of getting the project to change, though, why not just support previous commands?

Cloudflare has established a working protocol with wrangler which was violated in several ways with this release. I realize wrangler was rewritten into Rust.

The advisability or net positive impact of that decision aside, Cloudflare is a multi billion dollar company.

We pay cloudflare.

Yet when I try to deploy environment based workers, the only package that can deploy it (this one) is in beta and doesn't work with any of the previous commands that I would, you know, normally use to build my workers.

There is no reason it should or has to be this way.

[sgammon]

Here could be some good options:

1) restore support for commands deleted from wrangler in Rust

2) if by some insane logic I can't fathom Cloudflare is limited to minimal bandwidth on wrangler, the primary CLI for interacting with workers and several other paid services, then perhaps just dispatch wrangler v1 through npx, so we can at least not get stuck trying to use ecosystem software?

3) provide some kind of alternate route, say, a guide for yeoman or NPM based spawning of wrangler projects?

like the concept of deprecation is violated here in two ways. one, the feature doesn't work. two, it wasn't replaced by anything that did work.

as a user who is simply trying to pay CloudFlare and use CloudFlare, I am left wondering what possible benefit this rewrite could have delivered that would have justified removing such critical value from your own ecosystem.

[sgammon]

Or, as you suggested, you could just urge the entire ecosystem to change everything. But that will split all your guides and docs and Google-able advice into two, which, again, if you play these "deprecation" word tricks, actually just gets more confusing, because it's not clear if there's some flag I can provide to opt back in (there isn't).

[sgammon]

I hope this thread will be useful to someone who is surely arguing not to break customers from within this team. Thanks for reading

[petebacondarwin]

Hi @sgammon - I have reached out directly to you, to dig into these concerns a bit more. Please let me know if you didn't get the messages.

We need to improve the documentation and messaging around the commands that we have removed. Thank you for raising this issue.

In the meantime, could you have a look at the following project, which I think might be the alternative going forward to wrangler generate - https://github.com/cloudflare/templates/tree/main/packages/create-cloudflare.

[sgammon]

@petebacondarwin thank you for the response but i'd rather keep this conversation public so it can benefit other developers who use wrangler. our use case is not special or exotic.

i don't think you need documentation improvements, aside from the broken link. i think you need to restore functionality that you removed.

i'll take a look at the other package, but if it doesn't dispatch with wrangler generate, and there is not advice in lieu of that missing functionality that is provided to the user, i think this is still a rather major bug. if i were you, i would have considered it a release stopper, because it effectively turns wrangler into an error prone tool for the user by default.

[sgammon]

@rozenmd hope this isn't a politically charged bug homie boy that would be strange for rust

[sgammon]

@rozenmd / @petebacondarwin did one of you reach out to the package author? the package i linked here has now been deleted

[rozenmd]

@sgammon Sorry, didn't understand your comment here, please explain?

I reached out to the author to ask if they could update it, they chose to make it private for now.

[sgammon]

@rozenmd i am apologizing if this bug is political, i realize that there must be people arguing that breaking wrangler1 customers was a bad idea. i'm not used to getting direct emails from senior engineers for bugs relating to docs 404s.

it does look like they've taken the package private, which of course prevents me from using it even with wrangler1. i'm disappointed that this was the outcome.

[sgammon]

(but should say, thank you for your proactive action in any case, obviously it wasn't your choice to make the package private.)

[petebacondarwin]

Thanks for reporting this and providing the detailed information and suggestions. We agree that we should do a better job for people who are used to using wrangler generate to kick off their Workers. Partly this is improved documentation:

• the broken link should now be fixed But also we should have a well lit path of what to do to create new Workers. Our proposed plan:
• Work with the create-cloudflare project to lean on that for creating new Worker projects from Github repositories, since this is closest to what Wrangler 1's generate command does. We will update Wrangler 2 to delegate to that project when you run wrangler generate.
• Further we need to work with the documentation teams, our own teams that create templates, and 3rd party template providers to ensure that they provide valid templates for Wrangler 2 (and Wrangler 1 if backward compatibility is important for them).

Adding this issue to our project plan back log so that we can prioritise this work alongside other issues.

[polybuildr]

One comment from the linked duplicate issue,

• The guide on https://dash.cloudflare.com/{redacted}/workers/cli says "Create your first project. Generate a project using any of our Starters. You'll be set up with a Wrangler configuration file that you can quickly modify and publish." Below this is the command wrangler init my-app.
• I run wrangler init my-app, assuming it will ask me which starter I'd like to initialize with.
• wrangler just initializes a hello world example 😟

which is a related suboptimal experience but isn't actually a wrangler issue itself.

[caass]

@polybuildr would you mind opening an issue in the cloudflare-docs repo? As we've addressed everything in @petebacondarwin's comment, i'm going to close this issue out