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

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!

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).

(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.