Version 1 road map, or whatever you decide to call “stable”…

[ghost]

This is not really a bug, more a request for clarity.

First, I really like ruff and I do want to make it my go-to tool for linting. Currently, using it takes some effort to update as the release versions are coming fast and frequently. This is, of course, fine and understandable as it is under massive development. Kudos to everyone working on it, your efforts are much appreciated.

What I am looking for is a vague and non-binding roadmap to a “stable” version (let's call it v1!) so that I can plan a massive upgrade.

[charliermarsh]

Totally hear you and thanks for the kind words. I have a bunch of thoughts here of course 😂 I'll try to write something up later today if I can!

[Dilski]

I would like to adopt Ruff as our main tool for linting, but our main blocker is the v1/stable release. For now however, we're going to be running ruff alongside our other linting tools (flake8, bandit, etc).

[charliermarsh]

I got delayed on this, but I'll post some thoughts on what I want to see in a "stable" release by the end of the week!

[ghost]

I got delayed on this, but I'll post some thoughts on what I want to see in a "stable" release by the end of the week!

No worries whatsoever. Please do take your time.

[charliermarsh]

Here's what I'd like to see going into a Version 1 (which I assume would be v0.1.0, but let's punt that discussion for now):

• Support for structural pattern matching (Support pattern matching #282)
• Backwards-compatible migration to a subcommand-oriented CLI (rework CLI (3/3): Use clap subcommands #2190)
• Add support for "severity" levels (Feature request: Support a "warning" level for linting #1256)
• Add support for "autofix safety" levels, to let people opt-in or opt-out of potentially-dangerous fixes ([feature] Differentiate between safe and unsafe fixes #4181)
• Add backwards-compatible, first-class abstractions that don't rely on mapping back to Flake8 concepts (Human-friendly rule names #1773, Rule categorization #1774)
  • Add support for "rule aliasing" (Add support for rule aliasing #2186)
• "Versioning" for Ruff configuration files (similar to Rust editions)
• Better documentation for rules (Derive explanation method on Rule struct via rustdoc #2642)

As you can see, there are a few potentially-breaking changes in there. The intent is for them to be fully backwards-compatible, but I can't process complete backwards compatibility yet.

To put this in higher-level terms, I want Ruff to hit two milestones before bumping to v0.1.0:

1. We should support all known Python language features (of course!).
2. We should have an API that we're confident in -- one that we don't expect to change significantly in the future. (By API here, I mean the command-line interface and the way in which Ruff is configured.) The current API doesn't meet this bar. It totally works, but it's heavily anchored on Flake8 (see the error code system, e.g., E501 and friends), and is missing some key concepts (like "safety levels" for autofixes). We want to implement those missing concepts, and put some new abstractions in place (e.g., users should be able to do things like enable all "correctness" or "style" rules without having to parse through the list of implemented Flake8 plugins) while maintaining compatibility with the Flake8-oriented system. (Compatibility is an important piece here. We now have a lot of users -- which is great! -- but it comes with responsibility.)

I don't know when exactly we'll be able to bump to v0.1.0. I mean, definitely this year, but not this month.

Here are a few things that aren't important to me, with respect to bumping to v0.1.0:

• A plugin API or plugin system. We need to stabilize the API (part of v0.1.0 :)) before we consider doing this.
• A programmatic API (call into ruff from Python, or from Rust). Same as above.
• More lint rules. We'll continue adding rules and capabilities, but to me, they're not blockers for this kind of version bump.
• ...what else am I missing?

This is all based on current thinking and I reserve the right to deviate from this path as time goes on 😅 But hopefully this is helpful. Feedback always welcome.

[charliermarsh]

I'll \cc @not-my-profile on this issue too, actually, as he's doing a lot of work related to those rule and diagnostic API improvements.

[not-my-profile]

I'd add More thorough documentation for rules (#1467).

[ghost]

(which I assume would be v0.1.0, but let's punt that discussion for now)

My only very minor concern here is that poetry expects things to be 1.x.x before auto-updating packages. Not an unsurmountable issue, just a minor annoyance.

Otherwise, I fully support this vision. It's perfect! Thank you.

[hugovk]

And using SemVer:

How do I know when to release 1.0.0?

If your software is being used in production, it should probably already be 1.0.0.

There's a couple of dozen big projects listed on https://github.com/charliermarsh/ruff already using Ruff in production :)

If you have a stable API on which users have come to depend, you should be 1.0.0. If you’re worrying a lot about backwards compatibility, you should probably already be 1.0.0.

All planned for "Version 1": #1992 (comment) :)

[Sawbez]

@charliermarsh You might consider pinning this, putting this in a milestone, or putting this general information in a ROADMAP.md and link it in the README. We could also use the roadmap for version 2 and 3 (presumably 2 is formatting, 3 is type checking if we go that far) and possibly other big changes that contributors or users might want to help with/look forward to.

That might be too much maintainer time on top of all the things you have to manage, so not doing any of these would also be 100% okay.

[sbrugman]

Add support for "autofix safety" levels, to let people opt-in or opt-out of potentially-dangerous fixes

The closest issue that we have open related to this is #1997 (I think)

[ghost]

GitHub Project can help organize it all. It's fine as it goes. I am 💯 sure that a fair few people would help the project if @charliermarsh was getting overwhelmed…

@charliermarsh please do not burn out.

[charliermarsh]

We're making good progress on this!

Now that we support all Python 3.10 and Python 3.11 syntax, we can start seriously considering a "stable" release (that is, if we wanted to punt some of the features listed above to "post-0.1").

I think "Editions" would be a good thing to do since it gives us a mechanism to change configuration in the future in a backwards-compatible way.

[pauloxnet]

I'm waiting for the first stable release to propose ruff adoption to big python project (e.g. Django).😅
Thanks for all the work you all are doing. 👍

[tgross35]

Is there any specific place you're tracking the editions concept? Quick notes:

• Editions sound awesome since there will definitely be lints that are uplifted over time
• Yearly (edition = "2023") or quarterly (edition = 2023-Q3) editions seems like a reasonable duration (as compared to Rust's every 3 years)
• I think that it is OK to default to the latest edition if unspecified (as compared to Rust always using the earliest 2015 edition) as long as it happens with a minor version bump. Reason being, I think users are likely to have their ruff versions pinned for relatively long times

[zanieb]

Hi! We're looking at publishing a versioning policy for v0.1.x. Check out the proposal at #6998, we'd love your feedback.

@tgross35 We have not invested more effort into editions yet. It may need to be a v1.0.0+ feature.

[charliermarsh]

We shipped v0.1.0 a while back, which included a clear versioning policy -- and we're now looking ahead to a bunch of stabilizations in v0.2.0 in the near future -- so I'm going to close this out for now.

We still have some big changes planned for the future that will likely change the API (e.g., we want to do a holistic recategorization of the rules at some point; we may add support for custom rules; we'd like to ship a programmatic API, to call Ruff from Python). But all of those changes will follow the versioning policy defined above, and will be shipped with appropriate deprecations and compatibility guarantees over time.