See https://a11y-analytics.deno.dev/ for more information
I don't yet feel confident I understand what the API surface of this should be in all cases, so it seems misleading to publish a 1.0 and semantically version it.
Given that, this won't be semantically versioned until I reach that level of confidence.
However, I will attempt to make sure breaking changes are called out in CHANGELOG.md from this point forward.
These are the analytics providers the snippet can work with at the moment
- Google Analytics
- Plausible
The snippet should always be inserted as follows
- After all of the scripts of the analytics provider
- As an inline script tag with
typeset tomoduleso its execution is deferred until the analytics provider scripts finish executing
The initial synchronous work done by the snippet takes approximately 15 plus or minus 10 milliseconds, roughly.
The snippet itself currently weighs in at approximately 3.2 kilobytes (approximately 1.3 kilobytes when compressed with gzip)
To minify the source file and create a snippet to include on the website, go through the following steps
- Start a Github Codespace from a new branch
- Run the following command at the root of the repo
deno task build- When it asks you for run access, double check that the binary it's pointing to looks correct. The path to it should be "/home/vscode/.cache/esbuild/bin/@esbuild-linux-x64@X.Y.Z" where "X.Y.Z" is the version of esbuild in use.
- Accept through run access
You should see the minified snippet out in the console, as well as showing up as
a file under the dist/ folder.
This applies to the creation of the Github Releases that contain the published Javascript snippets.
To publish updated snippets the process goes as follows
- Update CHANGELOG.md with what the new changes include
- Update the version in version.json according to semantic versioning
- Create a PR with those changes and merge it into main
- Run the Release Github Workflow via workflow dispatch against the main branch
A new Git tag and Github Release should be created containing the updated snippets.
This applies to the "marketing" website where the ideas behind this project are discussed.
This repository is hooked up to a (manually created) Deno Deploy project. So
every merge to main will cause a redeploy of main.tsx and the
https://a11y-analytics.deno.dev/ site.
The version of all dependencies are pinned down to a patch version.
The version of Deno used locally for building and processing source code into the final snippets is pinned down to a patch version.
The version of Debian used as the base image for the dev container used in Github Codespaces is not pinned, to allow easy uptake of security patches. It's also in the stable release channel (buster) for Debian.
The version of the Deno VS Code extension is not pinned. This is a source of risk for slipping in subtle changes into code I wouldn't otherwise notice.
All 3rd party Github Actions are pinned to a commit.
Common libraries provided by the Github Actions runtime (e.g. jq) are not pinned.
Deno Deploy's version is not pinned as it's a Software-as-a-Service platform.
All application level dependencies in the code deployed to it have their versions pinned down to a patch version.
Github Codespaces automatically signs commits for you when you use it, if you've
configured that in your account settings. This along with the branch protection
rule on main to require signed commits should prevent anyone masquerading as
me and trying to slip in changes unnoticed.
Currently Github doesn't seem to sign their dev container images, so it's not possible to detect if it's been tampered with (before or after starting a session). I asked about this lack of container signing on Twitter.
Debian images generally include many more Linux kernel packages than other slimmer alternatives (e.g. alpine or Chainguard ones), meaning they have a much larger surface area for vulnerabilities. Github Codespaces only seemed to offer it as an option, and it's unclear to me how to make a custom alternative that still functions with Codespaces.
Deno dependencies are not yet tracked by Dependabot meaning it's unlikely I'll get a notification if there's a security issue with them that requires an update. The workaround is on my Github account I have a watch setup for security alerts for each the Github repositories of the dev dependencies
3rd party Github Actions are another vulnerability source. Dependabot should be notifying me of any reported security vulnerabilities with the ones in use, as well as helping keep them on the latest major version (to make it easier to take security patches).
Creation of the snippet and its inclusion into the website are currently manual processes, vulnerable to modification by other malicious things running on the same system.
The primary mitigation for this is to perform the processes on a clean machine, in this case a Github Codespace. It also helps that I'm the only contributor currently, as the mitigation is useless otherwise.
The publishing of the Github Releases is done via Github Actions and their clean, ephemeral runners.
I currently am the only owner of this repository, and I have MFA enabled on my account.