-
-
Notifications
You must be signed in to change notification settings - Fork 1.4k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[RFC] Versioning strategy #2858
Comments
All looks good to me, as we discussed yesterday. Regarding the release strategy, Option 3 makes the most sense, where after each minor release at the end of the month we merge the 'feature' branch back into I would propose one more option: Option 4: Go with the flow:We work as we usually do and restrain ourselves from introducing truly breaking changes, we will need the self-disciple either way. When the time for a release comes each week we see what has been merged and if there is a feature we bump minor, if no features have been added then we bump the patch. |
@flaviendelangle Thanks for the summary.
I think that we should respect the capitalization in the context. For instance, we have Unstable_TrapFocus, React has
These proposals make sense to me. I had the same thoughts as you when we introduced these public APIs a year ago.
https://semver.org/. This would also go against the statement in https://mui.com/versions/#versioning-strategy where we say MUI follows semver. I think that Semver is only valuable because it creates a clear and shared signal on how easy/likely to work the upgrade is. So at the end of the day, it seems to be about one question. Is it better to create our own versioning strategy to communicate which version X depends on the Core, or to go with something that asks to check the compatibility table? From my perspective, the answer is easy, not it's not worth it. Developers that get started installs with
On a different note, the methodology with the "MUI X Decision-making" meeting. I don't think that we should discuss topics that are not already discussed async. Why? Because if what we need is to prioritize 1-hour in our agenda to give feedback to peers, then we can create a personal event. We don't need to jump into a meeting :). For instance, here, I think that a great workflow would have been:
|
Realy clear summary 👍 For the part "Limit the surface of the public API" it makes sense to me. In the beginning, I was in favor of Option 3, because I thought "only small breaking changes, dev can handle them". But I see two problems.
|
The main difference between this and Option 1 is that in this we keep the same major version as the core Why do I think this is important?
|
I think Option 2 is a bad idea because a potential breaking change every week, even small, feels very uncomfortable for our users. And like @alexfauquette, I fear that they will stop upgrading the library to save time. My idea with Option 3 is to find a middle-ground with breaking change less frequent than Option 2 but more than the core. Another option would be to avoid all breaking changes in the few following changes and to see in a few months if it seems realistic to do 0 breaking change during 12-18 months.
OK for me 👍 |
Since we have to respect semver, the only option available is 1. We treat the X as a different set of packages, thrilling its own path. I think comparing it with the Core is not good, we don't have yet a stable codebase. If I was going to compare with something, I would use the lab. The lab is in alpha forever because it needs to move faster, like the X.
We could try zero breaking changes. Looking at the last releases, the BC were only related to the export cleaning. We could stop this effort for now, release the stable version, bump to v6-alpha and continue the cleaning. About the compatibility table, we could try to create one, but I don't know if we need one. If the Core doesn't make big changes again (e.g. a new styling solution), I think we will be able to keep supporting all versions. |
If we want to show that we are entering a more mature phase, I can even stop the export cleaning for a few months so we have a few But if the team prefer to start the v6 alpha as soon as the v5 stable is released, that would also be fine for me. For the compatibility table, we can wait to have a real case of incompatibility before creating one. I suppose before the v6 of the core, the only incompatibility is with core v4 and X v5+. It can be described in a sentence. |
My proposal is the following:
Do we have an agreement? Looking at the core's v6 milestone, we MIGHT be able to sync the release. If not, we add the compatibility table. What will happen once we add a second component? |
Yes For the new components, they will be in their own package |
Yes, true. So which version to start them? The same as the core? v1.0.0? |
I think @oliviertassinari was in favor of keeping the same version across all X components. |
@m4theushw I have upvoted the comment 👍
@flaviendelangle Correct. One of the value propositions of MUI is that we reduce the number of vendors that developers have to depend on: this is simpler. I believe using the same major version between all the X components would fall under the same spirit of simplicity when it comes the time to update. You can find the same approach in Kendo. |
The whole team has now validated this versioning strategy. I will edit the first message with the accepted proposal. Once v5.0.0 is released, we will respect semver and do no breaking change until the release of v6.0.0-alpha.0. The v6.0.0 alpha process may occur before the |
There is a tradeoff on the release strategy that we took a long time ago, that I wonder if there are better alternatives. There are libraries that release once a month. The advantage for them is that they can market bigger changes. Their release is more worth celebrating. But they also significantly deffer the feedback loop on regressions they introduce. |
They do a minor release once a month ? Currently we do not have patch releases so it is very important to release often for the bugfixes. If we had minor release and patch release, I guess the minor release could be less frequent. |
Yeah, I'm going off-topic. I think that you got my point, we can stop the discussion here and resume it with the dev rel. For the examples, we can look at VSCode, React, Bootstrap, Next.js, Ant Design it's never really clear what they do. Should we close this issue? |
I'm closing it yes |
Release schedule after the v5.0.0 stable version (final decision)
Once v5.0.0 is released, we will respect semver and do no breaking change until the release of v6.0.0-alpha.0.
The next features that don't require any breaking change will be release in minor versions 5.1, 5.2, ...
We will start the v6.0.0 alpha process when we will really have to do some breaking changes.
The v6.0.0 alpha process may occur before the
@mui/material
v6.0.0 alpha process.We are willing to do more major version on the X packages if it allows us to build important features quicker. But with the current internals, we should be able to release the next big features (at least #210, #212, #193, #211) in v5.
Limit the surface of the public API
As of today, almost all our internal states / internal components / internal methods are somehow public because they are either exported (we export all our components) or exposed in props or callback (
props.state
andprops.onStateChange
on theDataGrid
component)To help building new advanced features with as little breaking change as possible, we will reduce the surface of our public API through several measures
Prefix all internal apiRef methods with
UNSTABLE_
For instance
apiRef.current.getLogger
will becomeapiRef.current.UNSTABLE_getLogger
.Any method prefixed by
UNSTABLE_
can be broken at any point and should be used with care.Replace
props.state
withprops.initialState
that only contains a subset of the stateMore details on #2848
Any substate not listed in
props.initialState
can be broken at any point.In most cases, you should not interact directly with the state but rather use a selector or an
apiRef
method (pro-plan only for now).Stop exporting every component
The list is yet to be finalized but you can follow our discussion on this issue #2227 (comment).
Release schedule after the v5.0.0 stable version (outdated)
Our current release strategy is to do one minor version per week with a lot of breaking changes in them.
After the stable release, we will have to follow a clean breaking change policy. But we think that the surface of the public API makes it hard to have one major per year and not a single breaking change between them. We do not want to slow down the development of new feature too much and we need to find a good balance between breaking changes and feature development efficiency.
We discussed several options in today's meeting.
We think that these options make sense and that the most important point is to have a consistent schedule so that developers using the product can anticipate their migration.
Option 1 : More frequent major release than the core
Option 2 : Minor version every week with small breaking changes and keep major releases in sync with the core
Option 3 : Minor version every month with small breaking changes and keep major releases in sync with the core
Seems to be the approach of React Admin.
The text was updated successfully, but these errors were encountered: