API breaking changes management and feature freeze

[seanbudd]

Link to issue number:

Circulated to email list

Summary of the issue:

API breaking releases are slow and slow down the entire release process for the rest of the year.
To push API breaking releases out faster, and thus the rest of our yearly releases, we must cut the scope of them significantly.

This proposes:

• a feature / major changes freeze during API breaking releases, to focus on API breaking changes
• requiring all API breaking changes to be pre-scheduled
• allowing the minimal set of feature changes in an API breaking release, for accompanied unavoidable prescheduled API breaking changes

Description of developer facing changes:

Developers must pre-schedule API breaking changes.
NVDA development goes into a feature freeze from when the first 20XX.1 alpha is released until the first 20XX.2 alpha is release. This would be roughly a 2-3 month period at the end of the year.

Downside / cons

No features means less incentive for users to try the new release. the API breaking release basically cements itself as a "soft beta" release, really only used by early adopters. This is somewhat the case already, but this change leans into that further. Most people won't upgrade until features come out in 20XX.2

[Copilot]

Pull request overview

This PR updates contributor documentation to better manage scope during API-breaking release cycles, aiming to reduce risk and keep annual API-breaking releases moving faster.

Changes:

• Adds guidance for when new feature work is acceptable (alpha-only) and when features may be reverted/removed.
• Introduces policy text for API-breaking releases, including advance acceptance of breaking changes and limiting scope during those releases.

[LeonarddeR]

Interesting approach, I like it.
Could you also elaborate on how the scheduling is done? Will there be a project board, a label?

[seanbudd]

@LeonarddeR - pre-scheduled would just mean a triaged issue (+ approved ADR if relevant) on the 20XX.1 milestone before 20XX.1 alpha goes out.
If it's not on the 2027.1 milestone before we get to alpha, we won't accept it.

[bramd]

I like this plan. It might also be good for add-on devs to have a release to make their changes without it introducing much new features/behavior.

However, and this may sound silly, some NVDA users may look at the version numbering and think that 20xx.1 must be something major since we bumped the major version component. Especially in company wide deployments where the IT staff rolling this out is not really interested in the features, only in updates and determining if they should apply them or not. If they prioritize the .1 because they see it as a major one, they may lag or never get to a .2 release. This would mean that all users in such organizations might sit on .1 quite long without many new features. Basically, we communicate with our major/minor versions to developers, not end-users. The major version bump becomes an API breaking signal, not a heads up for end-users that nice new stuff is there. I don't know how big this problem may be, but NVAccess might be able to determine this based on past usage statistics data? E.g. how many people stay on a .1 release longer then would make sense?

I don't have a good solution without making it confusing, but just something to keep in mind.

[CyrilleB79]

The first 20XX.1 alpha is released when 20(XX-1).3/4 is branched to beta.
This gives a timing constraint between 2 separate events which may have teir own constraint. Could you rather announce a feature freeze with a specific date, as you already do for translation freeze?

[CyrilleB79]

Globally, I understand the rationale behind this.
Though, I'm afraid it may make the process more heavy or penalize the development of API-breaking features. We have seen in the past that API-breaking changes have been decided after an issue has been found while testing a new feature's PR, an alpha release or even a beta one.

If we stick with this approach, the deadline for API-breaking feature freeze should be announced clearly and without any ambiguity long before anyway.