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:

• Implementation is all in rules_python Starlark, not Bazel itself.
• 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).
• Human friendly changelog, i.e. CHANGELOG.md in keepachangelog.org-style format.
• 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 #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]

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!