Sync examples to glitch

[diarmidmackenzie]

Description:

Historically, we hosted various A-Frame examples on glitch, and linked to them from the docs.

Over time, they became outdated, as there was no per-release process to update them (and if there had been it would have been tedious and manual).

We have now moved the master code for these examples into GitHub at examples\docs*, where they can be tested on a per-release basis & easily maintained.

What's now missing is the ability for a user to easily try out modifications to the code, as they could with glitch.

Discussion

Discussion of various options took place here

Conclusions:
1 - we'd like to stay on glitch as users are familar with it
2 - we'd like code in examples\docs to use a local A-Frame library (rather than a CDN one) because it makes testing a lot easier.
3 - we'd like a solution with zero additional maintenance, where just updating stuff in GitHub results in updates to the glitches.

This points to a soluton comprising:

• Zero maintenance sync from github to glitch as described here: https://github.com/javierarce/glitchub
• The jobs that run this will also need to switch the A-Frame library used in the examples from local to a CDN URL containing the latest version.

Rejected solutions:

• Code Sandbox has a really simple interface using https://githubbox.com which can fork a sub-tree of a Git repo into codesandbox.io. However that doesn't deliver on 1 or 2 above.
• Glitch has a similar service at https://glitch.new that creates a new glitch based on a github repo. Unfortunately at this time it can only clone a whole repo, not a sub-tree. However even if Glitch enhance this so that it can clone a sub-tree it still wouldn't solve 2, as the cloning process wouldn't transform the local A-Frame URL into a CDN URL.

Implementation

Will require access to the A-Frame glitch account. @dmarcos, do you have this? Are you happy to share it, or do you want to do the glitch-side setup yourself?

[dmarcos]

Can glitchclub pull from a git directory?

[diarmidmackenzie]

Sorry, I overlooked that point. I don't immediately see how to adapt the glitchub implementation to handle sub-directories.

I'm wondering about another solution where we:

• have a separate git repo for each example
• continue to master the example content in the main a-frame repo, and automatically keep those git repos in sync.

Techniques for doing this documented here:

• https://docs.github.com/en/get-started/using-git/splitting-a-subfolder-out-into-a-new-repository
  (this describes how to do this as a one-time operation, but I believe this could be automated to be done every time there is a change - hopefully we can limit it to only happening if there is a change to the example code, rather than on every change to the repo).

Once we have a separate zero-overhead git repo for each example, we can either use glitchhub, or (even simpler) just provide a glitch.new URL using the per-example repos.

I'm going to try prototyping the techniques for mirroing a sub-directory into a separate repo, to see if I can make that work.

[diarmidmackenzie]

I've got a working proof-of-concept of this.

A couple of "examples" are mastered in this repo:
https://github.com/diarmidmackenzie/split-sub-directory

E.g. https://github.com/diarmidmackenzie/split-sub-directory/tree/main/examples/example1

GitHub Actions mirror all changes here:
https://github.com/diarmidmackenzie/sample-example1

And you can use this URL to spin up a glitch of the example:
https://glitch.new/github.com/diarmidmackenzie/sample-example1

@dmarcos - can you take a look & let me know if you'd be happy for me to replicate the setup for A-Frame?

Will need some access to set up new repos (one for each example we want to mirror), deploy keys & secrets. Have a read through here & see if you are happy with the detail.

If you want to test this out, happy to add you as a collaborator on https://github.com/diarmidmackenzie/split-sub-directory (so you can make comits & observe them replicating to the mirror repos).

[dmarcos]

wow. thanks for the investigation. I would prefer not going down the route where each example is its own repo. It sounds complicated to maintain and confusing.

[dmarcos]

An alternative idea. Have a script in the A-Frame repo that updates all glitches associated to the examples with a single command. e.g npm run updateglitchexamples. We could replace local A-Frame with latest released one and copy over whatever other local dependencies to a vendor directory. Seems the cleanest and we're not contorting the A-Frame repo structure to a specific service and its current limitations. It will make easier in the future to migrate / use a different service than glitch if we have the need to do so.

[diarmidmackenzie]

Have a script in the A-Frame repo that updates all glitches associated to the examples with a single command.

I've had a look into whether this is possible. All the existing examples we have for GH->Glitch sync synchronize a whole repo.

However I've looked more closely at glitchub (and other similar techniques documented here, here and here), and it should in fact be possible to just pull a sub-directory.

They all operate in more-or-less the same way:

• A push to the master git repo triggers a WebHook listener on the glitch side.
• The WebHook listener runs a script
• The script clones the repo into glitch.

All that's needed is to modify this script to just pull a sub-directory, rather than the whole git repo. That can be done by cloning the whole thing + pruning (as I did above), or perhaps using this tool, which probably does the job more efficiently (using the svn client to pull just a single folder from a git repo).

The relevant sripts can be found:

• glitchub: in the git.sh file (glitchub and this tutorial)
• glitcheroo: here
• in the post-receive script in this tutorial

I'm not convinced this is a cleaner / more easily maintained solution. It's much more tightly coupled to Glitch than the solution I'd suggested above (which leverages glitch.new such that there wouldn't even need to be an A-Frame account on Glitch).

But I think it can be done, and happy to look at another round of prototyping to do it this way.

[diarmidmackenzie]

So in a glitch terminal, the following will copy over a sub-tree of a GitHub repo

svn export https://github.com/diarmidmackenzie/split-sub-directory/trunk/examples/example1/ . --force
refresh

Or for an A-Frame example:

svn export https://github.com/aframevr/aframe/trunk/examples/docs/aincraft/ . --force
refresh

Should be possible to trigger that script via a GitHub webhook.

The other thing we need to do is to update the A-Frame script location from:

<script src="../../../dist/aframe-master.js"></script>

to

<script src="https://aframe.io/releases/1.4.0/aframe.min.js"></script>

but without hard-coding the version string into the scripts on glitch (or we'd have to update them every release!)

Here's a script that can do just that, extracting the version string from package.json.

mkdir temp
cd temp
svn export https://github.com/aframevr/aframe/trunk/package.json
grep version package.json | sed 's#^.*[^0-9]\([0-9]*\.[0-9]*\.[0-9]*\).*$#s@../../../dist/aframe-master.js@https://aframe.io/releases/\1/aframe.min.js@#' > sed.script
cd ..
sed -f ./temp/sed.script -i *.html
rm -r temp

[diarmidmackenzie]

I have a working version of this now, built on the glitchub WebHooks solution.

This Glitch:
https://glitch.com/edit/#!/mirror-aframe-example

I have a webhook set up on this test repo:
https://github.com/diarmidmackenzie/mirror-aframe-examples

Whenever I commit to this repo, the glitch example refreshes itself from the latest aincraft example. We could easily build out more glitches like this & set up webhooks to update them from the main A-Frame repo.

Setup is just 1 webhook per-glitch, which is pretty simple to configure.

One thing I don't much like about this solution is that it requires a bunch of code inside the Glitch itself that is unrelated to the example - see root folder and mirror folder. This is the code to run an express server to listen for webhooks, and update when triggered to do so.

Whereas the alternative solution using a repo per-example & glitch.new just presents the user with the code for the example & nothing else.

Having tried out both solutions, my recommendation would still be to go for the mirrored repos (first suggestion)

In terms of reservations expressed about that first approach:

• We could create a new GitHub orgnization to hold the example repos, so they don't clutter up aframevr
• I don't see a lot of maintenance exposure - only features it depends on are GitHub deploy keys & GitHub actions, which are widely used and therefore unlikely to change much in non-back-compatible ways.
• I don't see it as coupling us to Glitch at all - indeed it doesn't even require an A-Frame Glitch account. The 2nd solution is IMO more tightly coupled to Glitch.

[mrxz]

Not too familiar with Glitch, but it seems it's possible to push to a Glitch (https://glitch.happyfox.com/kb/article/85-pushing-local-code-to-a-project/). So wouldn't it be an option to store the corresponding git remote urls as secrets and use a GitHub Action to (force) push the updated version?