Versioned guides

[samselikoff]

No description provided.

[samselikoff]

@dfreeman wrote

Can you elaborate on how you imagine the versioned guides working? Would each version be a separate dummy app, or do you imagine them coexisting within a single application? Separate apps seem like they may be thorny to maintain and deploy, but if the guides include live (and possibly editable) examples, having multiple versions coexist in a single application could be difficult.

I haven't thought much about this yet.

Mirage has versioned docs, and I do this by literally copy-pasting the guides directory for each version. It's a Jekyll app, but you could imagine doing something similar in the Ember dummy app.

Now on the flip side, we will be needing to solve the versioned API docs problem as well. And the source for the API docs will certainly live in different versions of the project - since they'll be pulled from the actual tagged releases of the source code.

Seems we can either make everything static, or put things on a server somewhere.

I started to write more but I need more time to think about this. Back later. If anyone has thoughts here drop a line.

[dfreeman]

Sounds good. I'll let this rattle around in the back of my head while I work on other stuff and post back if anything occurs to me.

[samselikoff]

For example I will use this to rewrite Mirage's docs site. Want to port over the old versions and probably put them in a static place, public? Have to think about this.

[dfreeman]

So I just took some time to page the long conversation we had back in April back into my brain. It spans a bunch of topics, but I think has some relevance here. My biggest takeaway was that in order to support interactive guides across different versions of the addon in question, our only real option was going to be multiple deployed Ember apps.

If we were to go with that approach and treat gh-pages as a essentially a place for static build output, coexistence with older versions of documentation becomes pretty straightforward — going to my-addon/docs/v0.1.x could load a precompiled Jekyll page (or maybe even not prebuilt?), and my-addon/docs/v0.2.x could load a deployed Ember app.

Just spitballing on a directory structure, I could imagine something like:

• index.html (meta redirect to latest version?)
• docs/
  • v0.1.x/
    • index.md
    • ...
  • v0.2.x/
    • index.html
    • assets/
      • ...
    • ...
• data/
  • api-docs/
    • projects/
      • my-addon.json
    • project-versions/
      • my-addon-v0.2.0.json
      • my-addon-v0.2.1.json
      • ...
    • ...

To your point way back, you probably want API data published per-release, but guides are likely getting overhauled less frequently. Exactly how you'd want to configure that behavior and the affinity between API versions and guide versions would be a fun bikeshedding exercise for the future 😉

[samselikoff]

Let's think through using Mirage as a real-world case.

Current URLs:

ember-cli-mirage.com                 # homepage
ember-cli-mirage.com/docs/v0.3.x     # 0.3 docs
ember-cli-mirage.com/docs/v0.2.x     # 0.2 docs
ember-cli-mirage.com/blog            # blog
ember-cli-mirage.com/about           # about

When I migrate the site I want to be able to deploy the old site somewhere, more or less.

• Old homepage, blog and about will be migrated to new site
• No API docs, so mainly just guides.

I basically just want the old guides ported over somewhere.

New structure could be

ember-cli-mirage.com                   # new homepage
ember-cli-mirage.com/#/blog            # new blog
ember-cli-mirage.com/#/about           # new about
ember-cli-mirage.com/#/docs/v0.3.x     # new 0.3 docs (migrated)
ember-cli-mirage.com/docs/v0.2.x       # old 0.2 docs

Since we use the hash Router config for Ember apps served on github pages, this actually seems like it would work well. The /docs/v0.2.x path could just be a subset of my old docs, tossed in that directory.

One issue is that if gh-pages branch becomes a dumping ground, the entire docs site can no longer be built from current master. I think this is fine but we'll need to work on our deploy script - basically it can't just push to gh-pages, it needs to do something like a merge. Thoughts?

[dfreeman]

ember-cli-mirage.com                   # new homepage
ember-cli-mirage.com/#/blog            # new blog
ember-cli-mirage.com/#/about           # new about
ember-cli-mirage.com/#/docs/v0.3.x     # new 0.3 docs (migrated)
ember-cli-mirage.com/docs/v0.2.x       # old 0.2 docs

Where do you imagine future 0.4.x docs living with that setup? Are they served by the same app as the v0.3.x ones?

Mirage is maybe a tricky example to illustrate this particular piece with, but if you think of an addon like ember-bootstrap, where different major versions would bring in conflicting global stylesheets and component implementations, having multiple versions of the docs hosted in the same app doesn't seem feasible.

From a "how do we keep deployed versions isolated" perspective, I could see a layout like this working, but it raises some questions:

ember-cli-mirage.com                   # latest deployed homepage
ember-cli-mirage.com/#/blog            # latest deployed blog
ember-cli-mirage.com/#/about           # latest deployed about
ember-cli-mirage.com/#/docs            # latest deployed docs
ember-cli-mirage.com/v0.2.x/docs       # 0.2 docs subset
ember-cli-mirage.com/v0.3.x            # ??? (0.3 app is rooted here, but unclear what shows when you navigate to this URL)
ember-cli-mirage.com/v0.3.x/#/about    # ???
ember-cli-mirage.com/v0.3.x/#/blog     # ???
ember-cli-mirage.com/v0.3.x/#/docs     # 0.3 docs app

While it's not ideal, it seems like it wouldn't be the end of the world for things like home and about to be captured with each version. The blog feels like the killer, though — I can't really see any use for a moment-in-time snapshot of that. I don't know of a ton of other authors out there that maintain blogs for their addons, but it's entirely possible that's just because no one has made it easy for them. I know I'm personally guilty of using Github releases as poor man's blog posts at times.

One option would be for the app hosted under v0.3.x/ to link out to the top-level unversioned site for blog and friends, though that has the down side of losing the context of which version the user was browsing, and it introduces a hard refresh instead of a lightweight in-app transition.

One issue is that if gh-pages branch becomes a dumping ground, the entire docs site can no longer be built from current master. I think this is fine but we'll need to work on our deploy script - basically it can't just push to gh-pages, it needs to do something like a merge. Thoughts?

My take is that some amount of complexity around managing the versions is unavoidable, and if we try to make the full gh-pages branch creatable from master at any point in time, we just push that complexity from the deploy process into the build process instead.

I'm happy to take on the work of managing the deployment of different versions, once we tackle the layout questions above and know what we're aiming for 🙂

[dfreeman]

(Yikes. Sorry for the wall of text.)

[samselikoff]

You're absolutely right, conflicting global Ember versions/CSS sheets and more was one of the original reasons we wanted to go with isolated apps.

I'm thinking, what if we just start with an easy way to deploy the current version of the site, in a way that doesn't clobber the entire gh-pages branch? That way, for a project like Mirage, I could just decide where I wanted to put the old site and move it there.

There should also be an option to where you'd want to put your current Ember dummy app in the gh-pages directory. So ember deploy (or whatever the command is) would build and deploy the app to gh-pages root, but you could also pass an option if you wanted to deploy a different version somewhere else. And perhaps we could also provide a command to move the current root site to a different folder.

[samselikoff]

Thinking we should start with something like this, then try it out in some projects and iterate from there

[dfreeman]

So ember deploy (or whatever the command is) would build and deploy the app to gh-pages root, but you could also pass an option if you wanted to deploy a different version somewhere else.

Seems like a straightforward path to MVP, and we can deal with automating the version management process down the line.

And perhaps we could also provide a command to move the current root site to a different folder.

We'll have to be careful about how we reference assets and the docs JSON data to have a given deploy of the app work at different root URLs without rebuilding, but I think that should be doable.

[dfreeman]

Step 1: ef4/ember-cli-deploy-git#14

[samselikoff]

@dfreeman check with @sivakumar-kailasam because I had this installed and he removed it to change the deploy story

[dfreeman]

Ah, I missed that this was using Travis's built-in support for gh-pages deploys. It may be hard to get the control we'd want with that; it's kind of a blunt instrument.

@sivakumar-kailasam is the motivator for having Travis do the push that it's simpler to set up?

[sivakumar-kailasam]

Yep couldn't get the deploy git plugin to work on Travis.

[dfreeman]

I just got a dummy repo publishing to gh-pages with a Github deploy key via ember-cli-deploy-git: https://github.com/dfreeman/deploy-games/tree/gh-pages

The setup wasn't especially pretty, but I think we can probably abstract most of it away. I'll keep playing around and see what I can come up with.

[samselikoff]

sweet. I started with ember-cli-deploy-git and really liked it, Siva switched because we couldn't get it working with Travis but if you can I'd say let's switch back.

[dfreeman]

I packaged up my learnings into a companion ember-cli-deploy plugin that works alongside ember-cli-deploy-git to handle CI scenarios: https://github.com/dfreeman/ember-cli-deploy-git-ci

The ember-cli-deploy pipeline now fully controls the deploy process in this repo, and we get history on the gh-pages branch, which is a nice bonus: https://github.com/ember-learn/ember-cli-addon-docs/commits/gh-pages.

None of this directly moves us toward versioned guides, but it puts us back in control of how the build is happening and where it goes, which is a step in the right direction.

[sivakumar-kailasam]

Awesome @dfreeman ✨

[samselikoff]

Nice work man

[samselikoff]

@dfreeman what does an MVP for this feature look like? I feel like it's the biggest open issue for v1

[dfreeman]

I think there are two threads that have been discussed here (my fault for conflating the two) that complicate one another:

• continuous deployment of the docs app any time there's a build
• deploying multiple versions of the docs app alongside one another

To be able to deploy to the root of the gh-pages branch without blowing away a versions directory (or whatever it would be called), something like ef4/ember-cli-deploy-git#15 needs to land. I'm putting together a PR for that tomorrow.

With that in place, one super-minimal version of an MVP would basically be continuous deployment for master, with documentation for doing manual deploys to subdirectories to capture version snapshots.

I think there's a small step up from that, though, that may bring enough extra value to justify trying to roll it out up front. To be able to do automated versioned releases, we basically need to be able to answer two questions at the end of a build:

1. should we deploy at all?
2. where on the pages branch should we deploy to?

I could imagine defining a couple of hooks (maybe in config/deploy.js) that we call, providing information like the current branch and tag (if any) in order to answer those questions. That puts the onus on the maintainer to decide how to manage versioned releases, but it at least gets the ball rolling on automating the process and lets us start gathering data on what kinds of things folks will want to be able to do.

[dfreeman]

I imagine eventually we would provide opinionated default implementations for those hooks, as well as being able to ask more sophisticated questions around potential things like one-to-many guides version to API docs version rollout ("is this a new guides version or a refresh of the existing one?"), rather than the more blunt "deploy yes/no?" and "deploy where?".

[samselikoff]

Here's what I'd consider a common workflow:

1. I'm cutting my first release tagged 1.0, and I want to publish Guides and the API Reference.

2. There's been commits to master since (1), and I want to edit a typo in the existing Guides and have them updated.

3. I'm cutting a second release 1.1. I want to make some updates to Guides but don't need to publish a new version. I do want to publish a new version of the API Reference (it should be tagged 1.1).

4. Later I publish 2.0 guides and API reference.

5. I need to make an edit to the 1.0 Guides or API Reference.

I think these are the scenarios to solve.

---

(1) and (2) seem straightforward and are taken care of with our current workflow. (3) would be taken care of with "documentation for doing manual deploys to subdirs" as you stated.

(4) is similar to 3 but (5) is where things get tricky, and what the steps are for (5) will affect the actual strategy we take for the ultimate API for this thing.

Let's talk through it. Given master is at 2.0 and I need to make a change to 1.0 Guides or API Reference, what does this look like?

• git checkout tags/1.0
• make my modifications
• commit? To 1-0-stable branch? then push?
• run the command to deploy to the 1.0 subdir?
• check back out master

Thoughts?

[dfreeman]

My ideal for (5) would be for it to be as simple as checking out a branch, making a commit, and pushing. If the 1.x line is still active enough to warrant documentation edits, nudging authors toward having something like a 1-0-stable branch seems like a positive thing.

While it should always be possible to do a manual deploy, I hope that we can land in a place where things mostly "just work" based on e.g. a tag/branch naming scheme (which itself is the manifestation of a default implementation of documented hooks that can be customized). Do you think that's a pipe dream?

(3) to me is maybe the most interesting scenario, because it's the most complex with respect to the actual mechanics of the deploy. We want to update the current version of the Guides in place and add a new tagged data set for the API Reference, while keeping the previous API data in available as well.

This comes back to some of the discussion earlier in this thread—depending on the exact layout we're talking about for the app(s) vs the API data, (3) doesn't seem like it will be a straightforward "deploy to a subdir" situation. I suspect if we can get crisp on how this should behave and how authors ought to work with the functionality, most of the rest of the scenarios fall out from there.

[samselikoff]

You're correct, I hadn't thought through this. In (3) we'd want to preserve 1.0 API Reference while publishing 1.1. So we'd need two sites.

That means when (3) comes around, author would need to

• "archive" the existing version of the site to /v1.0
• publish master to latest

In that case the Guides thing isn't a huge issue, since the author would just mostly reuse the existing guides (most of her Dummy app would stay the same). But the API reference would be updated based on new comments from source.

[dfreeman]

Because the API Reference is driven off JSON data that's potentially independent of the deployed app, we could land in a place where there's a single most-recent version of the 1.x Guides at any time, and that deployed application could fetch API Reference data for multiple different 1.x versions.

The question, to my mind, is whether that's MVP or something we should punt on for now. It may be useful to think the scenario through to see how it impacts other decisions we're making regardless of whether we fully implement it up front or not. Thoughts?