dist rename rollout plan

[mistydemeo]

In #1267, we're working towards renaming cargo-dist to dist. We have a few steps to do in this release and in the releases to follow.

Now

• Replace all user-facing references to cargo-dist with dist, except in the names of the installers and related packages
• Thoroughly test the new dist binary and its cargo-dist alias, ensuring it works both ways
• Update the documentation with the new name
• Write a blog post announcing the new name

When 0.24.0 is released

• Publish doc changes
• Publish blog post

After 0.24.0 is released

• Prepare to rename the package so that future installers use the name dist instead of cargo-dist
• Ensure the Homebrew package can retain its name for compatibility OR use a Homebrew tap rename to handle the Homebrew name change
• Decide how to handle crates.io package name changes
• Cut a minor release with these changes

Sometime after that minor release

• Cut a release under the new package name, so the intermediate release has a package to upgrade to

[mistydemeo]

The rename infrastructure is available in #1647. The actual rename is in #1648.

I've tested out the rename in a fork of cargo-dist using the content of those two PRs. I staged the rename over several versions.

• 0.91.0: Standard release named cargo-dist, nothing changed: https://github.com/mistydemeo/cargo-dist/releases/tag/v0.91.0
• 0.92.0: First release with rename infrastructure present, still named cargo-dist: https://github.com/mistydemeo/cargo-dist/releases/tag/v0.92.0
• 0.100.0: First release named dist: https://github.com/mistydemeo/cargo-dist/releases/tag/v0.100.0
• 0.101.0: Another release named dist, no other changes: https://github.com/mistydemeo/cargo-dist/releases/tag/v0.101.0

In tests, 0.91.0 can upgrade to 0.92.0 as expected. 0.92.0 can then upgrade to either 0.100.0 or 0.101.0 safely. The new version installs a new receipt under the new name.

So, in other words, I think we can safely do this in two releases:

• A pre-1.0 release which adds the rename support mechanism from feat: add rename infrastructure #1647, which existing users can upgrade to.
• A 1.0 release which performs the rename from feat: rename cargo-dist => dist #1648.

Here's a sample of the formula rename: mistydemeo/homebrew-cargodisttest@64ac747

We just need to delete the Formula/cargo-dist.rb version and add the formula_renames.json file. Then, Homebrew will just go ahead and use the new formula file generated by dist and will be able to apply upgrades.

[mistydemeo]

Based on the testing I've done, here's the step-by-step release plan to follow.

1. Decide when we plan to do the rename. Once we begin the process, we can't pause it: we're committing to doing the rename within two releases, so it's important that we have the confidence that we can do it in precisely two releases.
2. Undraft and merge feat: add rename infrastructure #1647. This adds the infrastructure for the rename.
3. Create a point release containing that PR. At this point, the package will still be named "cargo-dist", but it will look for updates under the name "dist". (Because of this, the next release must contain the rename: there's no going back from here!)
4. Undraft and merge feat: rename cargo-dist => dist #1648. This renames the package to "dist".
5. Create a major release containing that PR. This will publish to all locations (GitHub, crates.io, npm, etc.) under the name "dist" instead of "cargo-dist".
6. Clone https://github.com/axodotdev/homebrew-tap, then manually commit the following two changes:
   a. git rm Formula/cargo-dist.rb
   b. Add a file in the root of that repository named formula_renames.json with the following contents:

{
  "cargo-dist": "dist"
}

7. Commit and push those changes.

With all of this done, the rename is complete: the package is now published as "dist" to GitHub Releases, crates.io, npm, and our Homebrew tap, and the Homebrew tap is set up to process the rename so users can brew upgrade from the old name to the new name.

[mistydemeo]

I don't think we have many nix users, but we can ask nix how to rename the package after the renamed release is out.

[mistydemeo]

Steps 1 and 2 are complete. Step 3 will be done when we release 0.28.0 from this PR: #1682

[mistydemeo]

Steps 3 and 4 are done. Step 5 is in #1684. Since that PR is a prerelease, it'll go to some sources but not others - we won't push it to crates.io, npm, Homebrew, etc.

[mistydemeo]

Step 5 is done, but the complete version of that won't be rolled out until there's a non-prerelease 1.0. So we'll say that 5 through 7 remain to be done, and can be done #1653's completion.

We can also reenable the selfupdate test once we have a stable 1.0 release. It's commented out right now. #1692.