jsdelivr as CDN

[tsturm]

After dealing with the challenges of our current server provided by Fraunhofer IGD, I took the initiative to explore potential alternatives for delivering our x3dom library. Among the various options, I found https://www.jsdelivr.com/ to be the most promising choice. Notably, it's free to use and seamlessly integrates with GitHub. However, I encountered an issue since it doesn't align perfectly with our main repository structure, mainly because we don't commit our build artifacts.

To address this, I propose creating a separate repository exclusively for storing the final build artifacts for each release. This approach would enable us to leverage all the advantages of jsdelivr effectively.

As a starting point, I've set up a test repository on my private GitHub account: https://github.com/tsturm/x3dom-release. Using a repository like that, we can request specific versions via the jsdelivr CDN, as demonstrated in the following examples:

A specific version:
https://cdn.jsdelivr.net/gh/tsturm/x3dom-release@1.8.2/x3dom.js
A specific version + automatic patch updates:
https://cdn.jsdelivr.net/gh/tsturm/x3dom-release@1.8/x3dom.js
The latest stable release:
https://cdn.jsdelivr.net/gh/tsturm/x3dom-release@latest/x3dom.js

Before finalizing this approach, there are some important points we need to clarify:

• Repository name: We should decide on a suitable name for the repository, such as x3dom-release, x3dom-cdn, x3dom-stable, x3dom-version, etc.
• Version management: Should we use specific branches for different versions, as demonstrated in my example repository, or would a main branch with tags be sufficient?
• File accessibility: Determine which files should be accessible for each version to optimize the delivery process.
• Other considerations: Are there any other open points or concerns we should address before proceeding?

I'm eager to hear your thoughts and opinions on this matter. Let's work together to find the best solution for our x3dom library delivery.

[MacrayBlackhand]

I'm all for jsdelivr, I use it heavily already and have found it to be very stable.

[andreasplesch]

Thanks for putting in the effort to address the server challenges. jsdelivr as CDN would be super, and a dedicated repo for releases could work well.

A few thoughts. To minimize friction and complete automation, it might be better to utilize the main x3dom/x3dom for recent and future releases, eg. commit build artefacts or tagged releases for those with the github action workflow, if this is feasible. Older releases may not build anymore with the main repo and could be archived on a static, separate repo.

Repo name: It would be best to keep x3dom/x3dom fo recent and new releases, and a x3dom/x3dom-archive for older releases.

If this is not possible, I would vote for x3dom/x3dom-download to follow the x3dom.org directory structure most closely.

Versions: I think main branch with tags is most common but whatever is easiest to manage is fine. Branches for each version would probably be closest to current x3dom.org. latest stable, and nightly, and/or dev should be there. ( Is it possible to have github actions work across repos ? Probably. )

Files: The same files as are currently on x3dom.org/download . The dev version is now missing from http://x3dom.org/download/dev/ but should also be made available. Documentation ?

Other considerations:

• http:// access would be great but jsdelivr presumably does not have that. Other solutions ?
• Documentation: It would be good to also have access to the automated documentation. x3dom.github.io/x3dom, dedicated repo x3dom.github.io/x3dom-doc/ ?

[jamesleesaunders]

Rather than a separate repo, could we not setup a GitHub pipeline which runs, builds and pushes to jsdeliver, this could be triggered when a new release tag is added.
A separate repo sounds a little more admin work.
The same pipeline process could also be used to publish the npm builds also.

[jamesleesaunders]

As for the version discussion, I personally think x3dom should use the semver versioning system:

major.minor.patch

Where:

• major = Breaking changes, API changed, new usage, not backwards compatible.
• minor = New feature release, new functionality, non-breaking change.
• patch = bugfixes, dev, performance improvements, non-breaking changes.

So there is more of a turnaround as and when patches/bug fixes are added.

Then there is no need for the -dev postfix (this is catered for by the patch version).

At the moment I think x3dom has the 3 levels a little out of step and using the 'patch' level for a minor release , for example we are preparing for a 'launch' of Release 1.8.3 where as really it should be version 1.9.0 being released then faster increments...
patch/bugfix 1.9.1
patch/bugfix 1.9.2
patch/bugfix 1.9.3

Then 'launch' 1.10.0

This would also mean x3dom looks like it is more active and being contributed to regularly.

I am not nesesarily saying every commit / PR = one patch increment though - this may take some git branch magic to achieve.

[andreasplesch]

There is no need to push to jsdelivr. Based on the path (end point) it reaches out and caches github repos automatically.

It might work to just add the builds to the current tagged releases on x3dom/x3dom ? in addition to the source archives. There is a file size limit of 20MB by jsdelivr.

Actually, jsdelivr does not work with github release assets: jsdelivr/jsdelivr#18203

The recommended alternative is to have a 'release' branch which is not really the idea for which branches are designed.

So I think now probably a separate release or download repo is cleanest if it is possible to push to it from a github action on the main repo ( which should be possible ).

I am uncertain about more frequent, minor releases since it involves more hands on deck (even with automation) and implies more qc than is actually available. A major release every year with an announcement sounds about right to me. Dev or nightly versions should be available (although they are also easy to build) but could remain unversioned for simplicity.

[jamesleesaunders]

"The recommended alternative is to have a 'release' branch which is not really the idea for which branches are designed."
I am not sure why you say this is not the idea of what branches are designed for? This is one of the very reasons for branches (less frequent release branches, more frequent feature branches, even more frequent bugfix branches).
The use of a 'release' branch is core to the popular gitflow workflow (see https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow).
This would marry up with modern development and CI/CD stratages.
All this said I appreciate this needs to be easy to administer, so I am just mentioning this as food for thought.

"A major release every year with an announcement sounds about right to me." With regards to 'major' - again it does not have to be followed but a major would suggest API/breaking changes (see https://semver.org/) So these would only be required if x3dom drastically changes and is no longer backwards compatible. Perhaps a minor release every year?

[andreasplesch]

'release' branch was used in a different sense in the jsdelivr issue. The suggestion was to have a branch which collects all release artifacts over time, and does not have source code, to parallel the release assets.

Ok, a minor release with potentially many changes.

[jamesleesaunders]

Ah I see yes that sort of 'release' branch would be dirty (and indeed not what branches are intended for). So perhaps the 2nd repo is the simplest.

One other thing to consider during this exercise is npm publishing (currently done via the GitHub x3dom/dist repo I believe) could/should this also be brought in line with this workflow?
Especially so as more and more browsers support JS modules therefore more people may reach for npm version of x3dom.

@fibo FYI

[brutzman]

If it is possible for X3DOM .js and .css references in an html page to try retrieving a second url if first url fails, that would be interesting. I will continue using best-practice patterns when autogenerating X3DOM pages for the X3D Example Archives.

• X3D Resources, Examples: Scene Archives for X3D
• https://www.web3d.org/x3d/content/examples/X3dResources.html#Examples

[andreasplesch]

The safest option is to just host x3dom.js and .css with the html on the same server. Then the .js will be available when .html is available, and when the .html is not available the .js does not need to be available.
https://stackoverflow.com/questions/67543431/how-to-create-fallback-for-cdn-libraries-without-using-document-write has some options for fallback loading.
But the point of using a CDN is that it is designed for availability and robustness. It would be hard to beat by any other solution except for self-hosting.

[tsturm]

Thanks for all your inputs. Im currently playing around with the Github Workflows to automate the single steps for the jsDelivr integration.

Currently, I'm using three different repositories for this integration:

• x3dom (main repo)
• x3dom-stable (repo for the delivery of the stable builds)
• x3dom-dev(repo for the delivery of the latest dev build)

In the main repo (x3dom), I utilize the repository_dispatch feature to trigger workflows in the other two repos:

• The x3dom-stable workflow is triggered if we publish a new release
• The x3dom-dev workflow is triggered if we push something to the main branch

As structure for the x3dom-stable & x3dom-dev repository I use the following:

• x3dom-stable/dev
  • dist/ (output of the x3dom build script excluding the zip archive)
  • LICENSE.md (License informations)
  • README.md (Informations about the Repository and how to use jsdelivr to access the files)

As of now, I'm testing everything with private repositories on my personal GitHub account. If any of you are interested in contributing or following the progress, I'd be happy to grant access to the repositories or make them public.

[brutzman]

Timo, first impression, this sounds great.

Might you be able to give me a slide for SIGGRAPH update on this? Simple prose OK.

[andreasplesch]

Super. This already sounds great. Please let us know if you want us to do some tests. Feel free to provide repo access. I think public should be fine.

Should we also consider a x3dom/x3dom-test repo ? It would just serve the test/functional and test/regression-suite tests from x3dom-test.github.io/ .

If jsdelivr setup is stable, the https://www.x3dom.org/nodes/ page could be updated to refer to the CDN, in addition to x3dom.org/download .

[tsturm]

Hi Don,

It seems unlikely that we'll have everything completely ready and available before the Siggraph but maybe you can already teaser it 😊

https://docs.google.com/presentation/d/1NrE-L7kf9hr8QU1jQL8uUr79DK-J75EKQ6Agtlb1cLE/edit?usp=sharing

[tsturm]

@andreasplesch I gave you access to my three test repositories.

I think the most interesting parts are the three workflow files:

https://github.com/tsturm/x3dom-do-release/blob/main/.github/workflows/dispatchRelease.yml
https://github.com/tsturm/x3dom-stable/blob/main/.github/workflows/publishStableRelease.yml
https://github.com/tsturm/x3dom-dev/blob/main/.github/workflows/publishDevRelease.yml

The up- and download artifact step can take a while because of the size of the docs-folder

[andreasplesch]

Please let us know if we can do anything to assist with enabling jsdelivr as CDN.