Release version 1.0

[rickeylev]

This issue is for tracking the effort to release a version 1.0 of rules_python.

There are several reasons for wanting to have a major version release:

• Better communicates when breaking changes are made
• Easier support for multiple versions and backporting of functionality
• Major versions are an indicator of fitness for use.

Anyways, there's a few large items to complete before a 1.0 release can be considered:

• [x] Implementation is all in rules_python Starlark, not Bazel itself.
• [x] Written policies that cover breaking changes, backwards compatibility, support for older rules_python versions, and supported Bazel versions
  • Bazel rules are rather leaky: it's easy for implementation details to unintentionally be visible and accessible to users, even if weren't intended so. This is especially true for rules_python, which carries various legacy and historical behaviors.
  • Requiring e.g. the latest patch or minor version release of Bazel allows us to take advantage of newer functionality and reduce the size of the test/support matrix
  • Steps necessary to introduce a breaking change (e.g. docs about how to migrate, issues to file, etc).
• [x] Human friendly changelog, i.e. CHANGELOG.md in keepachangelog.org-style format.
• [x] API review: reduce our API footprint to what makes sense (there's a variety of things exposed publicly that probably shouldn't be public)

EDIT: additional scope

• [ ] Rename pip_parse to something else.
• [ ] Mark gazelle as experimental or splitting the versioning scheme so that it is clear that it does not have similar semver guarantees.
• [ ] Mark pip.parse APIs as experimental and to stabilize later.
• [ ] We should have a category of public but unstable API. Certain things should be called out: gazelle, sphinxdocs, toolchain implementation details, requirements locking?
• [ ] Should we explicitly say that we would implement bzlmod first and WORKSPACE is something that needs to be supported until bazel 9 is the lowest supported version. It's OK to have new features in bzlmod only, but WORKSPACE has to be present. PRs would be welcome for WORKSPACE additions.
• [ ] Allow overriding TOOL_VERSIONS for the python bzlmod extension to have API parity.

[chrislovecnm]

Do we want https://github.com/bazelbuild/rules_python/issues/1360 as well?

This is a big change to have after a 1.0 release. It is more a 1.1.

[rickeylev]

Do we want #1360 as well?

Nah, it's separate from 1.0 requirements. The key point of these 1.0 requirements are rules_python being able to control its implementation and establishing a framework for how to move forward. The latter is necessary to create predictability and plan for the future (something both maintainers and users need). The former is a basic necessity (it's hard to support or address anything when half our implementation isn't under our direct control and has 3 to 9 month lead times with an order of magnitude higher barrier to entry).

This is a big change to have after a 1.0 release. It is more a 1.1.

We're going to have a variety of other large changes, too, as we address some of the hairy issues (pip support, bzlmod, cross-building, patch-level-Python-version specificity, etc etc). So I'm not really worried about having to release a 1.1, or 2.0, or etc in the future. Creating sustainable and predictable processes for that is what's important.

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had any activity for 180 days. It will be closed if no further activity occurs in 30 days. Collaborators can add an assignee to keep this open indefinitely. Thanks for your contributions to rules_python!

[alexeagle]

Can the maintainers give an update on this? Breaking changes have been a major obstacle for my clients, and not having a stable Python ruleset is inhibiting the Bazel ecosystem generally.

Perhaps it's part of this issue to remove "NOTE: bzlmod support is still beta. APIs subject to change." from release notes as well?

[aignas]

We have had a breaking change policy that we created to avoid causing too much pain for the users when we have to make a change. Do you have examples of what breaking changes were painful to your clients when going from one release to another? I would be interested in learning about them so that we can avoid breaking things in a similar way.

Given the current bzlmod state of things, I think we can discuss this issue in our next maintainer meeting.

[aignas]

A summary of things that we discussed in the maintainers meeting:

• [ ] Maybe rename pip_parse to something else.
• [ ] What do we do with gazelle? Do we make it as part of 1.0 release? Should we split the versioning scheme?
• [ ] Should we "stabilize" the experimental_index_url?
• [ ] We should have a category of public but unstable API. Certain things should be called out: gazelle, sphinxdocs, toolchain implementation details, requirements locking?
• [ ] Should we explicitly say that we would implement bzlmod first and WORKSPACE is something that needs to be supported until bazel 9 is the lowest supported version. It's OK to have new features in bzlmod only, but WORKSPACE has to be present. PRs would be welcome for WORKSPACE additions.

EDIT: added to the top comment.

[groodt]

Maybe rename pip_parse to something else.

Yes please. My favorite candidate is pypi_install

We should have a category of public but unstable API. Certain things should be called out: gazelle, sphinxdocs, toolchain implementation details, requirements locking?

Yes for all of those items in the list. I don't think compile_pip_requirements should be considered stable. Really anything to do with pip or the third-party ecosystem isn't really stable imo.

• Should we explicitly say that we would implement bzlmod first and WORKSPACE is something that needs to be supported until bazel 9 is the lowest supported version. It's OK to have new features in bzlmod only, but WORKSPACE has to be present. PRs would be welcome for WORKSPACE additions.

Should we consider going 1.0 after Bazel 8 is released later this year? Then that is our baseline LTS? I think we need to be more strict when we receive issues and cover what "supported" means. If we follow what bazel does, new features are added to to the rolling HEAD and the LTS bumps. But releases in maintenance mode are not automatically added. Only serious bug fixes and security fixes are backported.

Some other items for consideration:

• Update the CODEOWNERS to active maintainers / participants of meetings and reduce single POF

[alexeagle]

Hi @aignas - any update to this since the last two months? I'd like to ship our 1.0 of aspect_rules_py, but since it's a layer on top of rules_python we cannot give any stability guarantee in practice until our dependency does.

[aignas]

We are getting closer, but not yet ready to release 1.0 as we need to finish/stabilize the python and pip extension APIs and potentially the py_binary implementation based on the two stage bootstrap. Can't give you an ETA for those things right now, but we can discuss this more in our upcoming maintainers meeting.

What APIs are you depending on? Maybe we could prioritize stabilizing those first so that you could give your users the stability guarantees?

EDIT: One extra thing that we have discussed about is that we should release 1.0 when bazel 8.0 is released as that will allow us to build on a stable foundation - py_binary, py_library, py_test rules will be in rules_python for all supported bazel versions and it will be less confusing to everyone.

[aignas]

A quick update that we will finish the work on pip.override (see the draft PR attached to #2081) and we should be ready for 1.0. I think then we can also mark bzlmod as non-beta anymore.