The PUB_CACHE have moved.

[jonasfj]

Context: dart-lang/sdk#52386

[atsansone]

suggestion: Clean up for length, clarity, and active voice.

Suggested change

	* Ending backwards compatibility for the old location of pub-cache on Windows.
	Prior to Dart 3 `%APPDATA%\Pub\Cache` was a fallback location for pub-cache.
	As of Dart 3, the default pub-cache is always `%LOCALAPPDATA%\Pub\Cache`.
	If you have added globally activated packages to your `PATH`, you may wish
	to update `PATH` to contain `%LOCALAPPDATA%\Pub\Cache\bin`.
	* Ending backwards compatibility for the old location of pub-cache on Windows.
	Prior to Dart 3, `%APPDATA%\Pub\Cache` was a fallback location for pub-cache.
	Starting with Dart 3, the default pub-cache is located at `%LOCALAPPDATA%\Pub\Cache`.
	If you [added a package][] to your `PATH` as a command line app,
	to update `PATH` to contain `%LOCALAPPDATA%\Pub\Cache\bin`.
	[added a package]: /tools/pub/cmd/pub-global

[jonasfj]

   If you [added a package][]  to your `PATH` as a command line app,
   to update `PATH` to contain `%LOCALAPPDATA%\Pub\Cache\bin`.

You can do dart pub global activate <package>.

If the <package> being activated contains and executable section in pubspec.yaml, then executable files will be created in $PUB_CACHE/bin.

Thus, if you do dart pub global activate mono_repo you can execute: $PUB_CACHE/bin/mono_repo.
But the executable mono_repo is only available on PATH if you've added $PUB_CACHE/bin to PATH.

So I wouldn't really say that "you have added a package to your PATH".

What you did was:

• (a) Globally activate one or more packages (which contains an executable section).
• (b) Added $PUB_CACHE/bin to PATH.

We're trying to suggest that if you did (b), then action may be warranted.

"you have added a package to your PATH"

Implies to me that there was some action you did that added a package to PATH.

I suggest using the term "added globally activated packages to PATH" because it might remind the user of that time they modified PATH in order to get globally activated packages working without having to type dart pub global run <package>.

Note. I figured that referring to "globally activated packages", because it's usually dart pub global activate <package> that will be print a notice suggesting you update your PATH by adding ...\path\to\pub-cache\bin to PATH.

---

We could also change the line to:

If you previously added path\to\pub-cache\bin to PATH you may wish to update PATH to contain %LOCALAPPDATA%\Pub\Cache\bin.

Intentionally, avoiding to use the qualifier "If you previously added %APPDATA\Pub\Cache\bin", because while doing so might work, it's quite likely that users actually added the absolute path (e.g. c:\path\to\pub-cache\bin) to PATH.

I think it's viable to argue that path\to\pub-cache\bin can be a stand-in for both:

• %APPDATA\Pub\Cache\bin, and,
• c:\path\to\pub-cache\bin.

[jonasfj]

If you [added a package][] to your PATH as a command line app,
to update PATH to contain %LOCALAPPDATA%\Pub\Cache\bin.

I don't think "added a package to your PATH" is a good description of what might have happened.

You can't add a package, only the executables declared within a package. This happens when you globally activate a package.
But the action that is concerning is "adding globally activated packages to PATH".

Which is really a shorter variant of "adding all executables from globally activated packages to PATH".

[atsansone]

@jonasfj : A small update. I'll approve once fixed.

[atsansone]

Changed issue to suggestion. LGTM % suggestion.

[jonasfj]

Let's ship this, the goal was the help Dart 3 migration -- and we shipped Dart 3 a while ago 🤣

[parlough]

Thanks!