Stability Guarantee/Version Strategy

[calebcartwright]

AFAIK there's no readily available/discoverable information about rustfmt's stability guarantee defined within the repo, nor is there definitive links or references to external information.

AIUI the stability story is articulated in the RFC rust-lang/rfcs#2437, but IMO it'd be good to document the resulting details of the guarantee here within the rustfmt documentation.

Based on my understanding of the guarantee, a few salient points:

• formatting will be idempotent across all versions of rustfmt that have the same major version (barring things like new syntax, bug fixes, etc.)
  • this means that users should expect to see no formatting changes with minor/patch rustfmt version bumps when using only default stable config options
• as rustfmt follows semantic versioning, any breaking changes to rustfmt lib API will require a major version bump
• any removal or modification of existing CLI flags/options/subcommands/etc. (both rustfmt and cargo fmt) will require a major version bump
• any removal or modification of existing stable configuration options will require a major version bump
  • modification includes changing the default value, changing the option name, changing the allowed values, etc.
• unstable configuration options can be changed or removed at any time, without a major version bump

Some questions I have:

• does the guarantee apply only to rustfmt on stable, or all channels?
• do we need to enumerate which types of changes will be accompanied by a minor version bump?

@topecongiro - Anything I missed and/or got wrong? Do you agree it'd be worthwhile to document information on the guarantee or does an easily consumable version exist elsewhere that we could link to?

[topecongiro]

does the guarantee apply only to rustfmt on stable, or all channels?

The guarantees apply to all channels, including nightly and beta.

do we need to enumerate which types of changes will be accompanied by a minor version bump?

AFAIK, we haven't strictly defined such things. So far, we have loosely followed the semantic versioning:

• Update patch version when we make bug fixes and syntax updates
• Update minor version when we add, remove or change unstable configuration options or command-line interface

I don't think it is necessary to be strict about minor/patch version updates, though it definitely won't hurt to have such rule.

Do you agree it'd be worthwhile to document information on the guarantee or does an easily consumable version exist elsewhere that we could link to?

Yes, I agree that it's valuable to have such documentation in this repo. The original RFC is a bit outdated, so it may be nice to articulate the documentation in this repo and then reflect that documentation to the original RFC once we are confident with the content of the documentation.

[calebcartwright]

The guarantees apply to all channels, including nightly and beta.

👍 basically everywhere, other than perhaps when building rustfmt from source then 😄

I don't think it is necessary to be strict about minor/patch version updates, though it definitely won't hurt to have such rule.

Agreed. I was thinking more along the lines of articulating what you described there, just so end-users generally know what a minor version bump would mean

Yes, I agree that it's valuable to have such documentation in this repo. The original RFC is a bit outdated, so it may be nice to articulate the documentation in this repo and then reflect that documentation to the original RFC once we are confident with the content of the documentation.

I'll take a pass at creating a version of this for review

[calebcartwright]

As a practical example/question, there's been semi recent upstream changes around inline assembly which has two broad impacts on rustfmt

1. there's an inflight RFC to establish the formatting guidelines on the new inline asm
2. AST changes - a new LlvmInlineAsm ExprKind variant which AIUI currently maps internally to what the InlineAsm variant equated to previously/pre-change

To account for the AST changes, I had to incorporate the new variant during a recent rustc-ap-* bump, but both asm variants are treated the same currently since the formatting guidelines have yet to be finalized for the inline variant

rustfmt/src/formatting/expr.rs

Lines 323 to 329 in 8fb4fa5

	// We do not format these expressions yet, but they should still
	// satisfy our width restrictions.
	// Style Guide RFC for InlineAsm variant pending
	// https://github.com/rust-dev-tools/fmt-rfcs/issues/152
	ast::ExprKind::LlvmInlineAsm(..) | ast::ExprKind::InlineAsm(..) => {
	Some(context.snippet(expr.span).to_owned())
	}

If we assume that the inline asm style guide is finalized some time after we release rustfmt 2.0, then AIUI would we be able to incorporate those inline asm formatting changes as part of some rustfmt 2.x release. That could potentially result in some formatting changes to existing inline asm usage, but this would still fall under the "new syntax" type of bucket even though rustfmt 2.x-1 already supported the syntax.

Correct?

[topecongiro]

Correct?

Yes! Regarding new syntax, we can relax the stability rule and allow us to change the way we format the code with new syntax until it hits the stable (though we should not change the formatting style frequently).

[dhardy]

I have two related questions I haven't found answers to (after five minutes searching through the repo):

1. Is there a rough roadmap of the scope and time-frame for 2.0 (and 3.0 etc.)?
2. How do users choose the rustfmt version? E.g. will the next Rust Edition default to using Rustfmt 2.0?

[calebcartwright]

I have two related questions I haven't found answers to (after five minutes searching through the repo):

1. Is there a rough roadmap of the scope and time-frame for 2.0 (and 3.0 etc.)?

2. How do users choose the rustfmt version? E.g. will the next Rust Edition default to using Rustfmt 2.0?

Sorry this seems to have slipped through my notifications unnoticed.

A major breaking release is not going to happen soon, and to be perfectly transparent it's rather unlikely to happen outside a hypothetical 2.0 release of Rust et al

If/when there's approval for such a release, we'll be sure that the types of specifics you've rightfully asked for are codified and broadcasted widely, with opportunity for community weigh in, well before any such breaking changes are actually made.

[calebcartwright]

I'm also going to go ahead and close this issue as it served it's original purpose, though also teed up some broader questions and strategy being discussed with the dev tools team