[docs] Add notes about next branch

[eps1lon]

Clarify what PRs should target what branch.

/cc @mui-org/core-contributors

[oliviertassinari]

Regarding the dev workflow. Ideally, I would only work on a single branch at the time. Meaning, I think that we should do our best to avoid having master and next moving forward at the same path. Instead, I think that we can:

1. Commit all the changes that are backward compatible in the master branch for v4.
2. Freeze the master branch, keep it for important bug fixes only, rename the branch v3.x.
3. Start working the breaking changes for v4 in the master branch.
4. Merge the breaking pull-request on the master branch.
5. Start chipping v4.alpha releases as we are changing the API.
6. Start shipping beta releases as we are fixing the bugs.
7. Release a pre-release when we are happy with the current state.
8. Release v4.

Alternatively, we can switch the branch names v3.x -> master, master -> next. It doesn't really matter. I think that it's really important to have a single branch of focus. This way, we don't have to do any rebase. For benchmarking: http://markdotto.com/2015/09/28/bootstrap-features/.

What do you think about this strategy?

[mbrookes]

For benchmarking: http://markdotto.com/2015/09/28/bootstrap-features.

Not sure that's such a good benchmark for what you're proposing - they seem to run a two branch strategy, with v4-dev being the default branch, but with master receiving regular commits (462 ahead of v4-dev).

[oliviertassinari]

Not sure that's such a good benchmark for what you're proposing

I'm trying to explore the alternatives we have.

[eps1lon]

Looking at all the changes I think freezing 3.x might be a bad idea if it takes 2 or 3 month which means no activity.

@oliviertassinari What are the reasons to avoid 2 branches that we're working on? Rebasing alone is not actually a reason. We could also do merge commits but those tend to clutter the history up especially if they are done irregular.

[oliviertassinari]

if it takes 2 or 3 months which means no activity.

@eps1lon I wouldn't worry about this point, at least not too much. We had frozen the v0.x branch for 12 months when working on the v1. People kept installing the project, the download rate where growing +5% month after month. https://npm-stat.com/charts.html?package=material-ui&from=2017-01-11&to=2019-01-11. People love LTS versions.

By freezing, I mean no active work on the branch. If somebody submit an important bug fix, we review it and merge it on the frozen branch. But that's not all, we also have to backport the fix to the "next" branch. We might have conflicts to solve.

What are the reasons to avoid 2 branches that we're working on?

I would like to minimize the operational overhead. Backporting the fixes from master to the next branch is going to be a pain in the a**. I can live with it for the bugs. I'm not sure that we can handle all the conflicts that feature changes will create.

---

@mui-org/core-contributors What do you think of this strategy?

• v3.x (or master) for bug fixes, almost like a LTS (low activity). We will have to backport the fixes to the active branch.
• master (or next) for all our ongoing effort, it's our active branch (high activity)

[mbrookes]

I'm fine with this. I would prefer master & next for the branch names, but we can make next the primary branch.

We have 45 open PRs, mostly on master. We should make a concerted effort to merge or close them before we start active development on next.

[eps1lon]

Ok I'm more comfortable with a single branch so this is fine.

This means we make next the default and add a note that any changes should target next and bugfixes should target master?

[oliviertassinari]

@eps1lon It sounds like a plan 👍

[oliviertassinari]

We have 45 open PRs, mostly on master. We should make a concerted effort to merge or close them before we start active development on next.

@mbrookes It brings back a bit of a déjà vu time 😆. The different from the v0.x -> v1 migration is that I'm already spending all the time I can squeeze in reviewing the pull-requests and the issues. While I was able to double the time I was spending on Material-UI two years ago to reduce the number of open pull requests during the migration (by abandoning https://splitme.net/). I can't do that again without spending less time on onepixel.com. If we want to see the number of open PRs go down, we should either:

• Close aggressively what we don't want.
• Have help from all the maintainers to go through the open pull requests.

[oliviertassinari]

Do we need to update the CONTRIBUTING.md file?

[eps1lon]

Backporting the fixes from master to the next branch is going to be a pain in the a**. I can live with it for the bugs. I'm not sure that we can handle all the conflicts that feature changes will create.

Agreed. Minor nitpick: It's (forward) porting.

Do we need to update the CONTRIBUTING.md file?

I changed everything as we discussed. master for 3.x, important fixes only. next everything else. Someone with repo access needs to make next default and protect it.

[mbrookes]

we should either:

• Close aggressively what we don't want.
• Have help from all the maintainers to go through the open pull requests.

Or both - and yes, I meant "we" to mean @mui-org/core-contributors, not just you.