How about using master branch for patches / current docs and canary for the future stuff?

How would we be able to fix bugs in the website then? Would we have to commit to both branches?

There must be various ways of doing so I believe. E.g. there can be a canary branch, into which all PRs get merged. This branch is merged into master when a new feature release is baked. Meanwhile, if there is any patch that applies to the current version of Prettier, a PR commit is cherry-picked by a maintainer from canary into master. This updates the docs immediately. Alternatively, 'patch' PRs can be created against master instead of canary (maintainers can change the target branch if it's wrong). In this case, master needs to be merged into canary from time to time to keep them synced.

With a canary branch that represents upcoming features, there is a possibility of having https://canary.prettier.io/ with its own playground and other perks.

We could use versioned docs to achieve this goal, see here for example. (We don't need to add past versions, stable and next should be enough.)

I would totally agree that a separate branch for each major version + dev/canary is a very good idea.

I would even go on step further and say every merge you do on master should be auto-released - e.g. you merge a bugfix => get's released.
you merge canary/or any ready feature branch => get's released.

canary would probably be too noisy for that => so merge without release and schedule a release every night.

I think something like this would be the ideal release system.

@daKmoR Installing from GitHub is already supported, which means you can simply npm install prettier/prettier to get the "nightly" release.

@ikatyang if master plays the role of canary, then there is a need for another branch (say, stable or current) for bugfixes and and minor doc improvements. This is because ongoing pull requests have two distinct destinations.

I'm more in favour of canary / master name pair instead, but that would require people to npm install prettier/prettier#canary if they want to try out bleeding edge versions from github. What is cool about canary as name though is that it can be also used on npm for automatic nightly releases (npm install prettier@1.16.0-canary.20181221 / npm install prettier@canary). The third usage for this name would be: https://canary.prettier.io/. master instead of canary would look slightly less self-explanatory in the above cases.

If canary does not feel like the right word to use, dev or next can work as a replacement synonym.

Here is an example of a different approach: https://github.com/containous/traefik. They use master for working on the 'future' version and for each of the x.x versions they use their own branch. If the current latest version of Prettier is 1.15.3, patches would go to branch v1.15and new features would go to master. Time and again commits from v1.15 would be cherry-picked to master (example) and one v1.16.0 is released, branch v1.16 is created from master. This is more complex than just two branches, but makes it possible to patch multiple versions if needed (not sure this is valuable for Prettier though). UPD: React team uses something similar.

One way or another, it would be great to see the development and bugfix work to be split between branches to avoid reverting upcoming docs or keeping feature pull requests open till the last minute. The new workflow will also make patch releases much easier. Imagine someone discovering an urgent bug tomorrow, which would require releasing 1.15.4 immediately. master already contains #5629, so it will be necessary to manually go through commits after 1.15.3, cherry-pick them into a temporary branch and release from it. This feels somewhat convoluted and ad hoc.

Meanwhile, I'll prepare a PR that reverts this PR that reverts docs in PR #5629 that confused @daKmoR (and many others) 😅

@kachkaev

if master plays the role of canary, then there is a need for another branch (say, stable or current) for bugfixes and and minor doc improvements. This is because ongoing pull requests have two distinct destinations.

While it sounds like a good idea, our website is currently deployed from master via Netlify and I'm not sure if deploying from branches is supported. And I think it'd be better to use versioned docs since we could modify both the current and the next docs in the same PR.

Regarding bugfixes, it's already the case, though we only did it if it's necessary, see release-1.14 branch for example.

it can be also used on npm for automatic nightly releases (npm install prettier@1.16.0-canary.20181221 / npm install prettier@canary)

While it's a nice thing to have, disabling OTP (which is required for nightly build) does not look like a good idea.

One way or another, it would be great to see the development and bugfix work to be split between...

Our current versioning is not that strict, we could try a stricter one in the next release, that is, patch releases are only used for significant bugfixes (which usually requires cherry-pick), everything else will go to the next minor version.

While it sounds like a good idea, our website is currently deployed from master via Netlify and I'm not sure if deploying from branches is supported.

it is supported... it's actually what happens with every merge request - when you get the preview URL.

And I think it'd be better to use versioned docs since we could modify both the current and the next docs in the same PR.

true, but what would be the usecase? updating the docs of 1.x and 2.x at the same time will mean also releasing at the same time and having only one release branch... makes it kinda tough.

Most bigger projects have branches for each major version so I guess you will need that at some point anyways and having a "next" branch (seems to be currently the most common name for it) would be just one other release branch. You could use it for nightly builds but as said before you can skip that and say install via npm install prettier/prettier#next.

I would even say that's easier to understand...

• npm i prettier => you get the latest released version from npm (might not have all files because of .npmignore)
• npm i prettier/prettier => get latest master version from git (same version as npm but all files)
• npm i prettier/prettier#next => get next version from git (possibly unstable)

Overall I would still say the benefits for multiple release branches are worth the extra effort.

PS: not every PR needs to go next -> master; you can go to master directly and then rebase
PPS: Not a problem for prettier but if you have a monorepo then you sort of need nightly builds as you can't just install from a git repository (as you can't install only subdirectories)

it is supported... it's actually what happens with every merge request - when you get the preview URL.

Thanks, I just found it on Netlify:

true, but what would be the usecase? updating the docs of 1.x and 2.x at the same time will mean also releasing at the same time and having only one release branch... makes it kinda tough.

I meant the next minor version, not the major one. Of course the next major version should be in a separate branch.