feat: version playground examples and docs

[sean-perkins]

This PR versions the docs so that the v6 docs are within a versioned folder and the v7 docs are the latest. This also updates the playground component and file structure to support versioning.

• Adds the v7 option to the version dropdown
• v6 docs are now migrated to versioned_docs/version-v6
• v7 docs now live at docs/api
• Stackblitz base assets are now versioned in subdirectories:
  • v6 assets live at static/code/stackblitz/v6
  • v7 assets live at static/code/stackblitz/v7
• Stackblitz asset loader is updated for HTML and Angular example to load a package.json (this allows us to load different versions of Ionic for playground examples)
• Playground now supports a version property to determine which directory to load Stackblitz assets from, defaults to loading v6 assets for now, so we do not need to update existing examples.
  • <Playground version={7} />
  • Loads assets from /v7 directory.

I believe we have been incorrectly updating docs in the release-7.0 branch. We will likely need to backfill reverting changes to the versioned_docs/version-v6 directory. For example, ion-slides and ion-virtual-scroll documentation should display when developers are viewing the v6 documentation.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated
ionic-docs	✅ Ready (Inspect)	Visit Preview	Dec 6, 2022 at 11:53PM (UTC)

[liamdebeasi]

Full disclosure, I did not pour through the PR since there are over 5,000+ changes files 😄, but in general your approach sounds good.

I believe we have been incorrectly updating docs in the release-7.0 branch. We will likely need to backfill reverting changes to the versioned_docs/version-v6 directory. For example, ion-slides and ion-virtual-scroll documentation should display when developers are viewing the v6 documentation.

Does this mean we will want to revert the following changes specifically in versioned_docs/version-v6? main...release-7.0

[averyjohnston]

Since there isn't a v7 release yet that I can actually confirm with, I'll just ask to be sure: are the v7 docs set to install the latest version when opening the playgrounds in Stackblitz? Even if the assets are from v6, I imagine we'd want to install whatever version was selected in the dropdown -- if that causes an issue somewhere, that just means the demo needs updating with version-specific code.

[sean-perkins]

@liamdebeasi correct, we will want to revert those changes so that the v6 documentation is accurate after release-7.0 is merged into main.

@amandaejohnston each playground example is now pulling the dependencies from the package.json for each respective framework, in the static/code/stackblitz/v7/** folder. For v7 I am targeting a dev-build in those package.json files (we may need to update the lock file as well when we have a playground for v7). Currently we have a little bit of manual work, to have our demo template (demo.html) reference a dev build for the iframe example and maintaining these package.json files when we have an updated dev-build. When the v7 docs become public, we will need to do a find & replace to update these files. There is likely a way we can automate this better moving forward (hooking into the version dropdown or a script that updates the examples, etc.).

[averyjohnston]

If I open a Stackblitz example with the docs set to v7, it's still using a regular release of Ionic v6 rather than a dev build: https://user-images.githubusercontent.com/90629384/206030196-94be6d6b-6034-4067-a79f-2eb68a8c4a8d.mp4 Is that how it's supposed to look?

[sean-perkins]

@amandaejohnston ahh yes, so if a playground component does not specify a version, it will fallback to the v6 dependencies/stackblitz assets.

I need to mass update all the playground component usages to add <Playground version={7} to them. Good catch 👍

Also good to call out that we will need to use that syntax for our new examples that we expect to use v7 dependencies.

[averyjohnston]

It seems strange to need to add version={7} to everything; wouldn't we want v7 to be the default once it ships? Also wouldn't adding that cause all the playgrounds to load from the v7 assets directory, which you were trying to avoid so we don't need to mass-update everything right away?

Edit: I'm not opposed to needing to move everything to a new directory, of course, but I want to make sure things are going as intended.

[sean-perkins]

We should likely not default anything in the future, so that when releasing v8, we do not need to make any updates to the existing v7 playground examples. For example, each playground should explicitly state which version it is targeting.

I'd be happy to do this to the existing v6 playgrounds (in the release-7.0 branch) in a follow-up PR. This work effort is currently a blocker in our sprint for creating v7 playground examples.

[averyjohnston]

Ah, that's a good point. 🤔

Digging into the code locally, I noticed that currently all usage examples are duplicated between the v6 and v7 directories. Is there a way to have the playground try to grab the specified version, and if it doesn't exist, fall back to the latest available one? I imagine most of our examples won't change between v6 and v7, so this seems like a lot of duplicate code.

I can see the argument for that idea being too much "magic," though -- one might change a v6 playground and unexpectedly break it in v7 -- so I would be okay leaving things as-is if y'all feel strongly about that. (cc @liamdebeasi)

[sean-perkins]

Yeah I would opt that examples are duplicated across versions. This aligns with how Docusaurus handles versioning of markdown docs. Otherwise it will be difficult to know which playground examples can be removed in the future, without manually searching through each one to see if they are used vs. knowing we are dropping "version X" and can delete the entire directory.

[averyjohnston]

Works for me 👍