Clarify Rustfmt 2.0 status

[Timmmm]

We've been using Rustfmt 2.0 from the rustfmt-2.0.0-rc.2 branch in a project for over a year. We need that because integration of Rustfmt with arc lint requires just formatting a set of filenames, and at the time only the 2.0 branch supported that (has that changed?). But it's a pain to install for developers because it requires nightly and that is broken a fair bit of the time.

It's a bit confusing what the state of Rustfmt 2.0 is. The rustfmt-2.0.0-rc0.2 branch name makes it sound like it is really close to release! However that seems not to be the case based on this comment:

2.0 development has been happening on the master branch for a long time, the rustfmt-2.0 branch hasn't had any activity because it hasn't been used/needed.
To be perfectly transparent though, rustfmt 2.0 may not happen ever, but even if it does it certainly won't happen any time soon.

But I don't see how Rustfmt 2.0 could be being developed on master given that it includes backwards incompatible changes, unless they're all behind flags somehow?

It would be really helpful if you could add a section to the Readme (or anywhere) about what's going on with Rustfmt 2. What changes does it include? How do you use them? Why it might / might not happen, etc.

Thanks!

PS: You might want to remove the bit about "when we reach 1.0" from the readme while you're at it.

[calebcartwright]

Thanks for the question. I understand the desire for clarity so I want to stress that there's never been any official, declared plans or announcements that a major/breaking release of rustfmt is going to happen; it's just been comments in issues and commits in source control. If there were to be a breaking major version release of an official tool, especially outside a hypothetical 2.0 release of Rust et al, rest assured that will be prefaced with a more formal, official announcement.

There was a genuine desire by the rustfmt team to have a breaking/major release, and some effort to prepare such a release, but it never really made it beyond the source control repository.

It would be really helpful if you could add a section to the Readme (or anywhere) about what's going on with Rustfmt 2. What changes does it include? How do you use them?

Understand your perspective, but I don't plan on doing this because I think placing it in the readme will imply a degree of formality that's not really there (even if it is just explaining why not). The type of information you're requesting is precisely the type of material that would accompany an official/formal announcement if a 2.0 release were to happen, which is more reason why I don't want the readme populated with that type of info.

Will consider some kind of post, perhaps even utilizing this issue or a Discussion to underscore the posture described above that we can point back to.

Why it might / might not happen, etc.

In short, a desire for consistency and stability within the tooling ecosystem. There was some very understandable concerns and push back within the dev tools team (and beyond) about having one tool diverge from the rest of the ecosystem.

Additionally, the main purpose for the major version bump was to be able to introduce some breaking formatting changes, but there's other ways that goal could be accomplished which are worth deeper investigation.

We need that because integration of Rustfmt with arc lint requires just formatting a set of filenames, and at the time only the 2.0 branch supported that (has that changed?

That's never been the case. rustfmt has always required input, either via stdin or a set of filenames. By default rustfmt will also format out-of-line mods, but rustfmt has also supported disabling that behavior via the --skip-children flag for a long time. The only thing that was changing with 2.0 was that we would have inverted that to make the skip-children behavior the default (e.g. rustfmt foo.rs --recursive

However that seems not to be the case based on this comment:

As I'm sure everyone already knows, the default branch in a GitHub repository is not immutable. The referenced comment from me was accurate when it was posted ~8 months ago, but is subsequently no longer the case because I decided to change the default branch to better reflect the current state (refs #4801)

But I don't see how Rustfmt 2.0 could be being developed on master given that it includes backwards incompatible changes, unless they're all behind flags somehow?

rustfmt is officially distributed through rustup, and to a degree, the precompiled binaries attached to our releases, but we make no guarantees (certainly not strict semver guarantees) about active development within source control. Obviously folks can always build/consume directly from source, but that's not a primary/supported pattern and things could be broken at times (especially given the heavy coupling to nightly)

I think I've addressed all your questions so I am going to close, but please feel free to follow up if that's not the case!

[Timmmm]

That makes sense thanks!

rustfmt has also supported disabling that behavior via the --skip-children flag for a long time.

Ah yes, that flag had actually just been added when I wrote our linter (we've been using 2.0 for a while!) but unfortunately it still seems to require --unstable-features which requires Rust nightly, and we don't use nightly. I guess we will have to stick with compiling 2.0.0-rc.2 from source.

Thanks for the reply anyway!

[dcow]

If there are no plans to develop rustfmt 2 at the moment, then it would be nice to see some effort put into stabilizing all the unstable formatting options that exist. For reference, there are 25 stable options and 51 unstable options. The 1:2 stable:unstable ratio really makes this project feel unfinished as a user trying to configure rustfmt. If there were 60 stable options and 15 unstable, and active updates/movement on the stabilization tracking issues, I think things would feel a lot healthier.

[calebcartwright]

I've been deliberately holding back on responding to this to ensure I'm in a good frame of mind before doing so. However, it's been well over a week and I still find it somewhat irksome and feel like I have to say that I really did not appreciate the characterization of the project as unhealthy and unfinished, particularly based on such a one-dimensional metric devoid of any context.

However, I've decided to choose to believe you said this with the best intent in mind responding to above comments. I'm not keen on having orthogonal discussions on closed issues, but I feel like this needs to be corrected and contextualized so I'll respond inline here while also trying to reframe and identify some actionable steps you could consider taking if you still have interest in seeing unstable options stabilized.

I realize the following is not a short read, but I think thoroughness is more important here given the mischaracterization.

---

Instead of making (incorrect) assumptions, I'd encourage folks to think about this in terms of the following questions:

• Why are there so many options that are still unstable?
• What can I do to help stabilize an option that I want to be able to use on stable?

As to the first, I think it's important to note there are several common misconceptions we see pretty frequently around config options.

• the default posture should be to stabilize
• an option has been around for X amount of time, ergo it should be stabilized
• option works fine for me/I've had no issues with it, ergo it should be stabilized

These are all categorically false. We have a documented, explicit process for what's required to stabilize an option, and we won't stabilize any option unless and until we feel it clears all those thresholds. That's true regardless of whether the option is 5 days old or 5 years old. Put differently, the default posture is that unstable options will remain unstable unless and until they are provably demonstrated to be ready for stabilization; not the other way around.

Additionally, not all options are intended to be stabilized. Some have been flagged for removal (e.g. #5103, #5102, #5101), while others have already been deprecated but in a "soft" manner to try to give users more time to convert to the newer option (e.g. https://rust-lang.github.io/rustfmt/?version=v1.4.38&search=#merge_imports).

Furthermore, a large number of the unstable options have known bugs, commonly due to developers insisting on putting comments in strange places. An individual user/team can happily use such an option and never encounter one of those bugs, but that doesn't negate the fact that the bug exists and is experienced by others. These types of bugs have proven to be particularly thorny in the past and aren't necessarily quick/easy fixes.

The simplistic "there are X unstable options" line doesn't take any of that critical context into account.

The next point I'd stress is that many seem to be unaware of rustfmt's core scope, and thus the scope of the rustfmt team. First and foremost, rustfmt exists to pretty-print a parsed program's AST according to the rules defined in the Rust Style Guide. Full stop. That's our core mission and that, along with supporting/maintaining that function, is what takes priority. Other features we've been willing to take on, such as auxiliary formatting configuration options, are unequivocally secondary to that core mission.

This has two salient impacts on quantities of unstable config options. First, we're generally receptive to community desired configuration options (so long as the implementations won't require an unnaceptable maintenance burden), but only if someone from the community submits a PR with an implementation. Second, stabilization of config options is an inherently low priority, especially some of the community submitted options for more bespoke styling that diverges from, or even contradicts, the Style Guide. It's not uncommon for such options to be submitted by someone who only works on/cares about nightly who are happy to submit an implementation for nightly usage, but who aren't concerned about stabilization.

With the established priority level, the next relevant piece is the amount of bandwidth/capacity we have. Like the overwhelming majority of open source projects, rustfmt has far more work to do than it has people to do said work. For the last few years I've been the sole maintainer of rustfmt trying to accomplish what I can with whatever time I'm able to carve out of my personal life on nights and weekends. As many are hopefully aware, maintaining a project involves a significantly broader set of activities than writing code (or stabilizing config options), and I've had to handle the entirety of that breadth while also trying to avoid burning myself out and reducing the size of the team to 0.

Suffice to say, if we had more people we could get more done, including on lower priority items like config option stabilization. However, I fully anticipate that we'll continue to have a healthy number of unstable/experimental config options for years to come (even if that's due to currently unstable options being stabilized while new ones are added).

That is a good segue into the second topic relative to what one can do if they'd like to help, either just in general or for a particular option or two they'd personally like to be able to use on stable toolchains.

All unstable config options should have a stabilization tracking issue, the set of which can be found using the unstable option label (https://github.com/rust-lang/rustfmt/issues?page=2&q=is%3Aopen+is%3Aissue+label%3A%22unstable+option%22). Interested parties can start with one of those issue and compare it against the aforementioned stabilization criteria.

Note that one gap we have is bugs/issues for config options are not always explicitly enumerated in the stabilization tracking issues for every option, though they are in some (e.g .#4991). However, most of the time that blocking/bug/etc. information can be found within the issue tracker even if not explicitly linked/noted in the tracking issue, so even something as simple as adding comments to the tracking issue with links to bugs (or to confirm the absence of no bugs) is a helpful first step. Obviously submitted a fix for a blocking bug is massively useful as well. The utilization and well tested criteria are a bit harder to quantify, but again something as straightforward as github search results highlighting option utilization are helpful.

---

If you're willing/interested in helping, please let us know!

[dcow]

@calebcartwright thank you for your thoughtful reply. Respectfully, I think you're essentially confirming my critique. First, to be clear, my intention was not to take a stab at any individual or comment on their (your) ability as a maintainer. I didn't realize this comment would be difficult for you to process. From my side, I'm just calling things as I see/experience them as a user struggling to figure out how to use this tool and WTF is going on with it.

Regardless of your feelings surrounding the purpose of this project as a maintainer, this project is difficult to understand as a user. The problem of overwhelming unstable options, while I understand the concept of stabilization taking a longer time while also not being an explicit priority, does exists. It is cumbersome to parse through the long list of config https://rust-lang.github.io/rustfmt/?version=v1.4.38&search= and figure out what is going to work and what isn't. This isn't a damning problem in and of itself and some pretty simple solutions come to mind like housing unstable options below stable ones or on a different page. So it's not a problem per say that there is a 2:1 ratio of unstable to stable options, the issue is that it's silly to have to wade through 5.5k words of docs on a single page as a new (or any, really) user to the tool to try and figure out which ones are okay to use and which ones are going to be buggy best avoided. It's also true that some of the most useful options for my needs are unstable but that's besides the point.

So this tool has a learning curve... so what? Now you've committed to wading through the "mess" of options. You come across an unstable option you'd like to use. Thankfully it does have a tracking issue. You visit the issue link. You read the thread. It was opened in 2017. There are comments every 3 months asking what needs to happen for the issue to be stabilized. Clearly there's community interest in supporting this configuration option. But, there's no movement from the project maintainers on stabilizing for 5 years. Somewhere in another thread you see the maintainers talking about how good things will be in rustfmt 2.0 and that's where the focus is. Then in another thread you see that rustfmt 2.0 is on ice. But... still no movement on stabilizing the existing options. This is what makes things feel unhealthy. Put yourself in the shoes of a user instead of a maintainer for a second: this state of the world is confusing and does not inspire confidence when asking the question "is this tool ready for prime time? should I adopt it on my team?".

In other words, you have a point that simply the number of unstable options is not a useful first order metric to gauge project health. However, from a user perspective it feels very much like a symptom of exactly what you go on to describe: this project lacks resources. Bingo! Take all the words/feelings and misconceptions and semantics out of it so we can laser in on the issue. You've admitted that you don't have the time you used to and are struggling to find opportunities to work on this project. You've felt the burn at times. There's a ton more administrative work than meets the eye and the team size is 0. The phrase "it's not your fault but it is your problem" comes straight to mind. Nobody is blaming you for doing a bad job. But the reality is that, by your own admission, this project doesn't have the resources needed to truly thrive. My comment was not intended to tell you something you already know. It was intended to make you aware that it's also pretty clear to users that something is missing with respect to this project.

The reason I'm being critical here is that while in the abstract single maintainer projects are fine and generally it's understood that people providing free time to the community don't owe anybody anything, rustfmt is part of the rust toolchain and should not be just some side hobby project. If you're feeling burnt out and without resources, the rust community should probably address that and do so very seriously. Honestly, I'd expect a bigger "call for help on rustfmt" type of announcement to the whole community rather than these small "read between the lines" glimpses of what's going on hidden in github issues here an there. The collective bar for this tool is higher and if the job of maintaining it has grown as rust has and you're needing help keeping up, that feels like it deserves more attention than a comment in a closed gh issue thread. Some times I'm bad at saying what I mean so to be direct: I'm trying to encourage you to reach out and find the help you need.

One of the asks I've seen from users while skimming the issues seems to be communication. So thank you, truly, for writing your thoughts down. I don't envy your position.

[calebcartwright]

@dcow - I found your last response rather puzzling. Not only did you completely overlook my prior points, but you grossly misrepresented what I said around resources/bandwidth.

Simply put, I acknowledge we could do better on some issue triaging and documentation, but strongly reject your conflations and characterizations that I believe ultimately tie back to the project's goals and priorities not emphasizing things you'd like prioritized.

---

The phrase "first seek to understand, then to be understood" feels quite apropos here particularly given the number of more constructive ways you could've chosen to engage.

I feel we would've had a much more positive tone and productive dialog if you'd first reached out to us to ask some questions/get more information, shared feedback/ideas like "as a new user I found it difficult to differentiate stable vs. unstable options on the config page, and here's how I think it could it be better...", etc. Instead, you opted to comment on a closed issue flatly requesting we spend our time on your preferred feature set and stating your negative perception about the project because we hadn't spent time on your preferred feature set.

Let me restate this unequivocally: config options are bonus, low priority features. That's not my "perception as a maintainer", that's the truth. That priority holds regardless of resources, and even if I had 6 developers instead of 2, stabilization of config options still wouldn't get a ton of attention. Though I have no intention of doing so, we could in theory remove all the unstable config options tomorrow and the project would continue on executing on our goals and higher priority items.

Folks may not like the low priority status of config options, but they'll have to accept it regardless. We'll work on certain options when we can/when there's alignment with a higher priority goal, and I previously provided details on how others can help with an option they're particularly interested in (something others have taken us up on in the past).

You are of course entitled to your opinion and can certainly choose to believe whatever you want based on these bonus features not being a priority for us. However, we strongly dispute your overarching characterization for the reasons I've already thoroughly articulated and it seems pretty unreasonable to me to cast aspersions and make presumptions based on those low priority items not being worked on, or implying that a project can only be healthy or thriving if the maintainers work on the features you care about.

Could we do some things better? Absolutely! However, I think on the stabilization front that comes in flavors of issue categorization and adding relevant links to docs/bugs as we've alluded to in other threads. We're not going to do the highly ineffectual practice of periodically posting "no updates" nor acknowledging the repeated "bump" style comments either.

I'm not even going to attempt to respond to the rest of the points in your comment individually because they're all based on absolutely incorrect characterization that I will address to correct for any other readers.

rustfmt is categorically not my "hobby" project, nor am I "burned out" as you've apparently decided to state/imply. My prior point about resources was to note that we do not have a ton of extra bandwidth that could be allocated to low priority features and we've plenty of higher priority work to do. Furthermore, we aren't going to try to burn out the resources we do have by trying to work on both high and low priority items.

---

I don't think there's really anything else that can be said at this point that wouldn't be duplicative of prior comments, so I'm probably going to disengage from this thread.

To be frank, so far it feels like you've been more interested in stating your critiques than engaging in a mutual dialog, but I'm still open to discussing specifics in more focused forums (e.g. a new issue with suggested improvements for the config page) if you're interested. However, I'll also note that regardless of whether it was intended, your tone in the prior comment reads as somewhat patronizing and I'd ask that you be mindful of that if you do choose to engage in such discussions.

[dcow]

I have no idea how you interpreted my comment in the way you have. Maybe I've inadvertently struck a nerve with you. My apologies if I have. In the short while my initial
comment has been posted, it's received 4 thumbs ups. So I don't think I'm coming in here non-constructively. Perception is reality and I offered you my perception and some tiny insight into my internal calculus with the goal of vocalizing a way I think an improvement could be made. I don't know how to be more real than that.

I can assure you I'm not simply annoyed that you won't work on config options. It's not about not getting my way. That's not what any of this is about. And if you choose to interpret my comments that way then unfortunately there's not much further this conversation can go.

I've genuinely tried to offer you advice from an outside perspective based on essentially my anecdotal experience and additionally the contents of your response to my initial comment which honestly to me sounds like that of a tired maintainer. That's all. I'm sure I'm not 100% on the mark, but instead of trying to take my comment constructively with a grain of salt, you pick at my tone and accuse me of being patronizing. Again I'm not sure if I've offended you and sincerely apologize if I have. My intention is simply to vocalize my experience grokking rustfmt with the hopes that my feedback may, even if only slightly, contribute towards improving this tool in the future.

[dcow]

I think it might help if I gave my critique a different spin. Ignore everything I have to say about the soft stuff since I don't know what I'm talking about. Here's the hard tractable issue: I had some time I was willing to give (and may have more in the future) to help this project get some unstable options stabilized based on my initial experience discovering so many unstable options. When I went and tried to figure out how I could help, lack of clear communication surrounding the state of the project along with a "no update no response" type of philosophy when people ask what the status is on getting an option stabilized deterred me from investing the time I had. If the status and work left to do on the outstanding unstable options was clear, I suspect I would have been able to contribute in a more meaningful way. That's all there really is to it and hopefully that's a framing that speaks more directly your language as a maintainer. Seriously, no hard feelings.

One final comment: if the goal of this project is "pretty print the ast according to the rust style guide and config is bonus" then I probably came in with a misunderstanding regarding the utility of rustfmt. I could be entirely to blame for that, but my interpretation, just so you know where I was coming from, was: "I see a tool rustfmt, I see a rather extensive list of options, skimming the options it looks like this tool will work for us since e.g. we use this brace style and etc.". I'm not sure where I was supposed to pick up on the idea that the config options are purely bonus. I think it's pretty fair to expect that if the tool is configureable and there is documentation published explaining how to configure it, that people will expect to be able to rely on that aspect of the tool being supported.

[calebcartwright]

@dcow there's no hard feelings and nothing has been taken personally.

I feel like you're now trying to retcon things a bit, but you have finally gotten to a couple more concrete topics so I will reiterate my prior comment and suggestions around constructive routes you could take if you do indeed want to help or share some more actionable ideas.

You opened with a short abstract ask that we work on config options and shared your perception about the project.

I responded directly to that with background about the focus of the project, our team, and priorities to explain why we're not going to do that and why I disagree with your perspective. I also acknowledged some things we'll try to do better on, and enumerated some specific, concrete steps that you or anyone else can take if you'd like to help, either in general or on stabilizing a specific configuration option.

You then decided in response to expand to a broader critique and issuing more directions for me/our team. You're welcome to share your opinions, and yes, share experiences. However, doing a drive by critique of project you aren't familiar with to share unsolicited, largely abstract "advice" and lecturing isn't particularly helpful especially when you didn't seek to gain any understanding or context from us first. It shouldn't be too surprising to hear that isn't helpful and didn't land well.

I tried several times to pivot the conversation to some more actionable steps, but you still seemed more focused on making assertions and offering your critiques and advice based on your assumptions. Again no hard feelings, but there were more constructive avenues to share your experience and ideas.

Finally, there's one point I'll respond to directly below, but also note that I'm going to lock this issue because as I stated originally, this is an off topic thread on a closed issue. I think you've been given more than ample opportunity to express your complaints and critiques, and this has reached a logical conclusion.

I had some time I was willing to give (and may have more in the future) to help this project get some unstable options stabilized based on my initial experience discovering so many unstable options. When I went and tried to figure out how I could help, lack of clear communication surrounding the state of the project along with a "no update no response" type of philosophy when people ask what the status is on getting an option stabilized deterred me from investing the time I had. If the status and work left to do on the outstanding unstable options was clear, I suspect I would have been able to contribute in a more meaningful way

I think this gets to the heart of part of this. First, I'm sorry to hear that and I also understand the perspective/critique you've been sharing. However, one of the points I've been trying to make is that I'd suggest you consider asking how you can help next time (regardless of whether it's this project or another) instead of jumping to conclusions. The comments you are referring to are people asking repeated questions like "when will this be stabilized?" not "is there anything I can do to help?". The former are repetitive, excessive, and have been already been answered (though as I've acknowledged several times not in every instance) so are sometimes ignored. The latter are helpful, appreciated, but rare.

I don't understand why the presence or lack of response to the former would make you refrain from asking the latter, but thanks for sharing.