Lit-html: Move deployed docs to branch so they don't run ahead of releases.

[justinfagnani]

RIght now GitHub pages is set to deploy from /docs on master. Having the source of truth on master is great for keeping docs in sync with changes, but it's bad for control over docs releases. They're currently running ahead of the latest release, which has happened several time.

We should configure GitHub pages to deploy from a gh_pages branch, but still keep the source in /docs on master. We'll need a release script to deploy the docs when we do a release.

[daKmoR]

may I suggest a different workflow?

1) If work happens in a dev branch it can never get out of sync and I would even recommend merging to master only when it's also released. Seems to be way easier to understand by users.
2) Also having github pages as a host is apparently not the most convenient option anymore. Using something like netlifly allows to keep git free of generated content and it will stay always up to date (e.g. they run the build script and grab the generated html for you) and it even works for merge requests - where you get a preview url.

if this sounds useful and there are questions I'm happy to share more details

[justinfagnani]

@daKmoR I greatly prefer having master be the development branch. Release branches are easier to cut and maintain (or ignore) than trying to keep master aligned with the current release. I certainly don't want to change the development branch just to satisfy docs, and GitHubs particularities at that.

I'm very open to using a different hosting solution, or using GitHub pages, but not it's built-in Jekyll support, but we're standardizing the docs infrastructure across lit-html, lit-element and pwa-starter-kit, so we all have to agree on this.

[logicalphase]

I agree with Justin on this one. Ideally docs could be synced to their
respective library versions using tags so devs could reference the most
current docs for their version. Not sure if that's doable, but something to
think about.

[mariusGundersen]

If the docs are in master and are merged to gh_pages in a release script, does that mean minor changes and improvements also have to go through master? Or can they be done directly on the gh_pages branch without getting conflicts when creating a new new release?

[justinfagnani]

I think minor changes to release documents can happen to release branches, if master has gotten ahead of the current release. And release branches will allow us to make multiple versions of docs at the same time. The harder part is assembling one docs deployment from several release branches.

[mariusGundersen]

There must be some prior art out there to copy? How are other projects hosted here on github dealing with this problem?

[daKmoR]

I agree with Justin on this one. Ideally docs could be synced to their
respective library versions using tags so devs could reference the most
current docs for their version. Not sure if that's doable, but something to
think about.

with netlifly you can have multiple branches deployed.

• master deployed to domain.com
• v0.x brach deployed to v0x.domain.com
• v1.x brach deployed to v1x.domain.com

for the problem aligning master with the released - I believe this should be actually handled by a ci completely so in the ideal world it would be

• dev branch (actual work)
• whenver a released is needed just merge dev to master (no need to create any changelog or so)
• master updade will be detected by ci
• ci runs something like standard-version & npm publish
• netlifly will update primary domain
• (automatic nightlys might also be nice)

but yes I agree it's a completely different workflow :see_no_evil: feel free to disregard the sugguestion :hugs:

[Westbrook]

With only one "official" documentation site at a time as well, my team uses https://www.npmjs.com/package/gh-pages to package a deploy in what amounts to the postpublish script in our package.json, it's been pretty successful to date.

Would something like that make sense here? I can see benefit of versioned docs, but I'm not sure you'll be able to support that with github alone.