[RFC] Publish Pyrefly on crates.io

[rchen152]

tl;dr We need to publish Pyrefly on crates.io to remove a blocker to including Pyrefly in Monty (pydantic/monty#501). To make it clear that our library API is unstable, I propose publishing using a 0.0.100X00Y versioning scheme derived from our regular 1.X.Y releases (e.g., 1.4.1 would map to 0.0.1004001).

Context

Monty publishes to crates.io, so we need to publish Pyrefly’s crates for Monty to be able to depend on them. However, Pyrefly does not have a stable library API, so if we published our crates using the same 1.X.Y versioning that our PyPI and VSCode releases follow, the version numbers would be misleading.

Proposal

Publish our crates with 0.0.N versioning to make it obvious that the API is highly unstable. N will be computed from our regular 1.X.Y version as N = 1,000,000 + 1,000 * X + Y. I like this particular mapping for two reasons:

• It’s easy to convert back and forth at a glance; 1.X.Y is 0.0.100X00Y.
• It doesn’t reuse the 0.X.Y version numbers that we’ve already used for our alpha and beta releases.

The versioning leaves room for 999 patch releases to the same minor version and 999 minor releases (about 80 years’ worth at one release a month). Dev releases will have their -dev.N suffix copied over unchanged.

Ongoing cost

Even with 0.0.N versioning, publishing our crates means committing to some level of ongoing support for them:

• Every non-dev dependency must have a working crates.io version, so anything we publish can't rely on git dependencies or [patch] overrides.
• Splitting out new crates becomes more costly, and published crate names stay on crates.io forever.
• Our dependency choices, such as exact pins and our ruff version, constrain library users. We may be asked to support specific dependency versions.

The boring stuff (i.e., the technical details)

We have 11 crates that need to be published. The main pyrefly crate already has a placeholder 0.0.1 release, which is harmless. We should configure trusted publishing and publish via a GitHub workflow, as we already do for PyPI.

In order to rewrite the version number for crates.io publishing and nothing else, we can run a small script in the publishing workflow to edit Cargo.toml before publishing. We would never commit these edits.

[rchen152]

@MarcoGorelli would this unblock you on Monty?

[MarcoGorelli]

I believe so, yes, thank you!