ScriptV2: Tracker release process, documentation (#5477)
* Release process start * Move CHANGELOG.md to tracker directory, symlink * Update LICENSE * Restructure symlinks to make sure files are included in `npm pack` * Start with new flows * New workflow for tracker script releasing * Changelog * typo * Fix bump steps naming * Scope commit to tracker/ folder * Step naming
This commit is contained in:
Karl-Aksel Puulmann
GitHub
parent
d4bec6d9e3
commit
17f116d827
|
|
@ -0,0 +1,79 @@
|
|||
name: "Tracker: publish NPM release"
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
branches: [master]
|
||||
types: [closed]
|
||||
|
||||
jobs:
|
||||
tracker-release-npm:
|
||||
runs-on: ubuntu-latest
|
||||
permissions:
|
||||
pull-requests: read
|
||||
contents: read
|
||||
if: >-
|
||||
${{ github.event.pull_request.merged == true && (
|
||||
contains(github.event.pull_request.labels.*.name, 'tracker-release: patch') ||
|
||||
contains(github.event.pull_request.labels.*.name, 'tracker-release: minor') ||
|
||||
contains(github.event.pull_request.labels.*.name, 'tracker-release: major') ) }}
|
||||
|
||||
steps:
|
||||
- name: Checkout the repository
|
||||
uses: actions/checkout@v3
|
||||
with:
|
||||
token: ${{ secrets.PLAUSIBLE_BOT_GITHUB_TOKEN }}
|
||||
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 23.2.0
|
||||
registry-url: 'https://registry.npmjs.org'
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm install --prefix tracker
|
||||
|
||||
- name: Bump the patch version and update changelog
|
||||
if: "${{ contains(github.event.pull_request.labels.*.name, 'tracker-release: patch') }}"
|
||||
run: npm run npm:prepare_release:patch --prefix tracker
|
||||
|
||||
- name: Bump the minor version and update changelog
|
||||
if: "${{ contains(github.event.pull_request.labels.*.name, 'tracker-release: minor') }}"
|
||||
run: npm run npm:prepare_release:minor --prefix tracker
|
||||
|
||||
- name: Bump the major version and update changelog
|
||||
if: "${{ contains(github.event.pull_request.labels.*.name, 'tracker-release: major') }}"
|
||||
run: npm run npm:prepare_release:major --prefix tracker
|
||||
|
||||
- name: Get the package version from package.json
|
||||
id: package
|
||||
run: |
|
||||
echo "version=$(jq -r .version tracker/npm_package/package.json)" >> $GITHUB_OUTPUT
|
||||
|
||||
- name: Publish tracker script to NPM
|
||||
run: npm publish
|
||||
working-directory: tracker/npm_package
|
||||
env:
|
||||
NODE_AUTH_TOKEN: ${{ secrets.TRACKER_RELEASE_NPM_TOKEN }}
|
||||
|
||||
- name: Commit and Push changes
|
||||
uses: EndBug/add-and-commit@a94899bca583c204427a224a7af87c02f9b325d5
|
||||
with:
|
||||
message: "Released tracker script version ${{ steps.package.outputs.version }}"
|
||||
add: "tracker/npm_package"
|
||||
|
||||
- name: Notify team on success
|
||||
if: ${{ success() }}
|
||||
uses: fjogeleit/http-request-action@v1
|
||||
with:
|
||||
url: ${{ secrets.BUILD_NOTIFICATION_URL }}
|
||||
method: 'POST'
|
||||
customHeaders: '{"Content-Type": "application/json"}'
|
||||
data: '{"content": "<h1>🚀 New tracker script version has been released to NPM!</h1>"}'
|
||||
|
||||
- name: Notify team on failure
|
||||
if: ${{ failure() }}
|
||||
uses: fjogeleit/http-request-action@v1
|
||||
with:
|
||||
url: ${{ secrets.BUILD_NOTIFICATION_URL }}
|
||||
method: 'POST'
|
||||
customHeaders: '{"Content-Type": "application/json"}'
|
||||
data: '{"content": "<a href=\"https://github.com/plausible/analytics/actions/workflows/tracker-script-npm-release.yml\">NPM release failed</a>"}'
|
||||
|
|
@ -107,3 +107,27 @@ jobs:
|
|||
message: |
|
||||
${{ steps.analyze.outputs.sizes }}
|
||||
comment-tag: size-report
|
||||
|
||||
- name: Check PR has tracker release label set
|
||||
if: >-
|
||||
${{ !(
|
||||
contains(github.event.pull_request.labels.*.name, 'tracker-release: patch') ||
|
||||
contains(github.event.pull_request.labels.*.name, 'tracker-release: minor') ||
|
||||
contains(github.event.pull_request.labels.*.name, 'tracker-release: major') ) }}
|
||||
|
||||
run: |
|
||||
echo "::error::PR changes tracker script but does not have a 'tracker release:' label. Please add one."
|
||||
exit 1
|
||||
|
||||
- name: Get changed files
|
||||
id: changelog_changed
|
||||
uses: tj-actions/changed-files@ed68ef82c095e0d48ec87eccea555d944a631a4c
|
||||
with:
|
||||
files: |
|
||||
tracker/npm_package/CHANGELOG.md
|
||||
|
||||
- name: Error if PR no tracker CHANGELOG.md updates
|
||||
if: ${{ steps.changelog_changed.outputs.any_changed == 'false' }}
|
||||
run: |
|
||||
echo "::error::PR changes tracker script but does not have a tracker NPM package CHANGELOG.md update."
|
||||
exit 1
|
||||
|
|
|
|||
|
|
@ -0,0 +1,86 @@
|
|||
# Architecture
|
||||
|
||||
This document describes the design goals informing the architecture of the Plausible tracker script codebase as well as a map
|
||||
to how the code is laid out.
|
||||
|
||||
## Design goals
|
||||
|
||||
We want to provide users a javascript suite to capture page views and activities done on the web page.
|
||||
|
||||
Over time, the following key design goals have emerged:
|
||||
|
||||
### 1. Minimal script size
|
||||
|
||||
Smaller scripts lead to better user experience and reduce the amount of data we miss due to script download and runtime.
|
||||
|
||||
We minify our scripts using the speedy `@swc/core` library and track script size changes on every pull request.
|
||||
|
||||
### 2. Many targets, single codebase
|
||||
|
||||
Plausible provides a web 'snippet' users can include on their site, tooling for wordpress and other plugins as well as an npm package.
|
||||
|
||||
As Plausible doesn't have the workforce to maintain multiple code bases, everything is built from the same underlying source code.
|
||||
|
||||
This is achieved by:
|
||||
- Having a canonical list of compiled variants in `tracker/compiler/variants.json`
|
||||
- Using `COMPILE` globals to toggle certain functionality on/off depending on the variant.
|
||||
- Having the script minifier drop dead branches of the code from each variant.
|
||||
- Having `compile.js` compile all needed variants
|
||||
|
||||
### 3. Flexible user configuration
|
||||
|
||||
Rather than capturing everything, we want to provide configurability allowing Plausible users to toggle tracking features on/off.
|
||||
|
||||
To make life simpler for these users, we want to allow changing configuration on web without users needing to change their integration code or deploying.
|
||||
|
||||
Plausible tracker endpoints dynamically interpolate site-specific configuration into the minified plausible.js. For integrations such as the wordpress plugin, we provide tooling like the plugins API.
|
||||
|
||||
### 4. Legacy support
|
||||
|
||||
We want to avoid intentionally breaking existing installations of the script.
|
||||
|
||||
In a previous version of the script, Plausible allowed toggling features by changing their script extension. We still generate and serve each of these legacy variants.
|
||||
|
||||
### 5. Great development experience
|
||||
|
||||
To make sure development of the tracker works like a well-oiled machine, we:
|
||||
|
||||
- Ensure compilation is snappy and done in parallel. Currently compiling over a 1000 variants around 3 seconds on a development machine.
|
||||
- Use a bundler (rollup) to split code into multiple files.
|
||||
- Use automated browser-based testing to cover new functionality and changes.
|
||||
- Leverage CI-based workflows for testing and releasing each new version
|
||||
|
||||
## Code Map
|
||||
|
||||
This section provides a key overview of code that is relevant to understand the tracker codebase.
|
||||
|
||||
### `tracker/src/`
|
||||
|
||||
Contains tracker code itself which is to be compiled. `plausible.js` is the entrypoint during compilation.
|
||||
|
||||
### `tracker/compiler/variants.json`
|
||||
|
||||
Contains a list of variants and associated global `COMPILE` flags.
|
||||
|
||||
- `manualVariants` are the main variants we need to care for, containing both the web snippet and npm package.
|
||||
- `legacyVariants` is a list of all the legacy variants we support, generated by `tracker/compiler/generate-variants.js`
|
||||
|
||||
### `tracker/compile.js` and `tracker/compiler/index.js`
|
||||
|
||||
This script is responsible for bundling and minifying each variant in parallel.
|
||||
|
||||
Compilation adds code under `priv/tracker/js`
|
||||
|
||||
### `tracker/npm_package`
|
||||
|
||||
Contains types, package.json, README.md, CHANGELOG.md and other related files to the npm package.
|
||||
Does not contain the actual code which is placed there during compilation.
|
||||
|
||||
### `tracker/test/`
|
||||
|
||||
Playwright tests. These tests usually load a specific html fixture, configure the tracker script, emulate user behavior
|
||||
and check what events get sent.
|
||||
|
||||
### `lib/plausible_web/plugs/tracker_plug.ex` and `lib/plausible_web/tracker.ex`
|
||||
|
||||
Elixir code responsible for serving tracker script, interpolating and managing site tracker script configuration.
|
||||
|
|
@ -0,0 +1 @@
|
|||
npm_package/CHANGELOG.md
|
||||
|
|
@ -1,7 +0,0 @@
|
|||
Copyright 2020 Plausible Insights OÜ
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
|
|
@ -0,0 +1 @@
|
|||
npm_package/LICENSE.md
|
||||
|
|
@ -0,0 +1,49 @@
|
|||
# Plausible tracker
|
||||
|
||||
This contains Plausible tracker script and NPM package which Plausible users integrate into
|
||||
their site and which captures pageviews and more.
|
||||
|
||||
## Development
|
||||
|
||||
See also [ARCHITECTURE.md](./ARCHITECTURE.md)
|
||||
|
||||
### Dependencies
|
||||
|
||||
To download dependencies, do:
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npx playwright install # installs browsers used by playwright
|
||||
```
|
||||
|
||||
### Compilation
|
||||
|
||||
Compile tracker code by `node compile.js`.
|
||||
|
||||
Use `node compile.js --watch` to watch for changes.
|
||||
|
||||
Use `node compile.js --web-snippet` if you need to update web snippet code.
|
||||
|
||||
### Tests
|
||||
Tests can be run in UI mode via `npm run playwright --ui`. This helps with debugging.
|
||||
|
||||
### NPM package
|
||||
|
||||
To test changes to the npm package by installing the local version against a test project, we recommend:
|
||||
|
||||
- installing [yalc](https://github.com/wclr/yalc) via `npm install yalc -g`
|
||||
- compiling the tracker
|
||||
- running `yalc publish` in `tracker/npm_package` directory
|
||||
|
||||
More instructions can be found in [yalc repo](https://github.com/wclr/yalc).
|
||||
|
||||
## Cloud deployment
|
||||
|
||||
Handled via PRs. When making tracker changes, it's required to:
|
||||
- Tag your PR with a `tracker release:` label
|
||||
- Update `tracker/CHANGELOG.md`
|
||||
|
||||
After merge github actions automatically:
|
||||
- includes the updated tracker scripts in the next cloud deploy
|
||||
- updates npm package package.json and CHANGELOG.md with the new version
|
||||
- releases the new package version on NPM.
|
||||
|
|
@ -0,0 +1,10 @@
|
|||
# Changelog
|
||||
|
||||
All notable changes to this npm library will be documented in this file.
|
||||
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
||||
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
## Unreleased
|
||||
|
||||
Initial release.
|
||||
|
|
@ -0,0 +1,9 @@
|
|||
MIT License
|
||||
|
||||
Copyright 2020 Plausible Insights OÜ
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
|
|
@ -0,0 +1,106 @@
|
|||
# Plausible Analytics tracker
|
||||
|
||||
[](https://www.npmjs.com/package/macobo-test-tracker)
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
|
||||
**Notice:** This library is currently under development and will be released as an official library later this year.
|
||||
|
||||
Add [Plausible Analytics](https://plausible.io/) to your website.
|
||||
|
||||
## Features
|
||||
- Small package size
|
||||
- Same features and codebase as the official script, but as an NPM module
|
||||
- Automatically track page views in your SPA apps
|
||||
- Track goals and custom events
|
||||
- Provide manual values that will be bound to the event
|
||||
- Full typescript support
|
||||
|
||||
## Package Installation
|
||||
|
||||
With npm:
|
||||
|
||||
```bash
|
||||
npm install macobo-test-tracker
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
To begin tracking events, you must initialize the tracker:
|
||||
|
||||
```javascript
|
||||
import { init } from 'macobo-test-tracker'
|
||||
|
||||
init({
|
||||
domain: 'my-app.com'
|
||||
})
|
||||
```
|
||||
|
||||
### Configuration options
|
||||
|
||||
See also [plausible.d.ts](https://github.com/plausible/analytics/blob/master/tracker/npm_package/plausible.d.ts) for typescript types.
|
||||
|
||||
| Option | Description | Default |
|
||||
| --- | --- | --- |
|
||||
| `domain` | **Required** Your site's domain, as declared by you in Plausible's settings. | |
|
||||
| `endpoint` | The URL of the Plausible API endpoint. See proxying guide at https://plausible.io/docs/proxy/introduction | `"https://plausible.io/api/event"` |
|
||||
| `autoCapturePageviews` | Whether to automatically capture pageviews. | `true` |
|
||||
| `hashBasedRouting` | Whether the page uses hash based routing. Read more at https://plausible.io/docs/hash-based-routing | `false` |
|
||||
| `outboundLinks` | Whether to track outbound link clicks. | `false` |
|
||||
| `fileDownloads` | Whether to track file downloads. | `false` |
|
||||
| `formSubmissions` | Whether to track form submissions. | `false` |
|
||||
| `captureOnLocalhost` | Whether to capture events on localhost. | `false` |
|
||||
| `customProperties` | Object or function that returns custom properties for a given event. | `{}` |
|
||||
|
||||
#### Using `customProperties`
|
||||
|
||||
To track a custom property with every page view, you can use the `customProperties` configuration option:
|
||||
|
||||
```javascript
|
||||
init({
|
||||
domain: 'my-app.com',
|
||||
customProperties: { "content_category": "news" }
|
||||
})
|
||||
```
|
||||
|
||||
`customProperties` can also be a dynamic function:
|
||||
|
||||
```javascript
|
||||
init({
|
||||
domain: 'my-app.com',
|
||||
customProperties: (eventName) => ({ "title": document.title })
|
||||
})
|
||||
```
|
||||
|
||||
### Tracking custom events
|
||||
|
||||
To track a custom event, call `track` and give it the name of the event. Custom properties can be passed as a second argument:
|
||||
|
||||
```javascript
|
||||
import { track } from 'macobo-test-tracker'
|
||||
|
||||
track('signup', { props: { tier: "startup" } })
|
||||
```
|
||||
|
||||
To mark an event as non-interactive so it would not be counted towards bounce rate calculations, set `interactive` option:
|
||||
|
||||
```javascript
|
||||
track('autoplay', { interactive: false })
|
||||
```
|
||||
|
||||
### Revenue tracking
|
||||
|
||||
To track an event with revenue information, do:
|
||||
|
||||
```javascript
|
||||
import { track } from 'macobo-test-tracker'
|
||||
|
||||
track('Purchase', { revenue: { amount: 15.99, currency: 'USD' } })
|
||||
```
|
||||
|
||||
More information can be found in [ecommerce revenue tracking docs](https://plausible.io/docs/ecommerce-revenue-tracking)
|
||||
|
||||
### Opt out and exclude yourself from the analytics
|
||||
|
||||
Since plausible-tracker is bundled with your application code, using an ad-blocker to exclude your visits isn't an option. Fortunately Plausible has an alternative for this scenario: plausible-tracker will not send events if `localStorage.plausible_ignore` is set to `"true"`.
|
||||
|
||||
More information about this method can be found in the [Plausible documentation](https://plausible.io/docs/excluding-localstorage).
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
{
|
||||
"name": "macobo-test-tracker",
|
||||
"version": "0.0.1",
|
||||
"version": "0.1.6",
|
||||
"description": "Plausible Analytics official frontend tracking library",
|
||||
"scripts": {
|
||||
"test": "echo \"Error: Testing done in the tracker folder\" && exit 1"
|
||||
|
|
@ -12,7 +12,7 @@
|
|||
"analytics"
|
||||
],
|
||||
"author": "Plausible Analytics",
|
||||
"license": "AGPLv3",
|
||||
"license": "MIT",
|
||||
"homepage": "https://plausible.io",
|
||||
"type": "module",
|
||||
"module": "./plausible.js",
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ export function init(config: PlausibleConfig): void
|
|||
export function track(eventName: string, options: PlausibleEventOptions): void
|
||||
|
||||
export interface PlausibleConfig {
|
||||
// Domain of the site to track. Should be registered with Plausible.
|
||||
// Your site's domain, as declared by you in Plausible's settings.
|
||||
domain: string,
|
||||
|
||||
// The URL of the Plausible API endpoint. Defaults to https://plausible.io/api/event
|
||||
|
|
|
|||
|
|
@ -1,11 +1,16 @@
|
|||
{
|
||||
"tracker_script_version": 15,
|
||||
"tracker_script_version": 16,
|
||||
"type": "module",
|
||||
"scripts": {
|
||||
"deploy": "node compile.js",
|
||||
"test": "npx playwright test",
|
||||
"test:local": "npx playwright test",
|
||||
"start": "node test/support/server.js"
|
||||
"start": "node test/support/server.js",
|
||||
"npm:prepare_release:patch": "npm run npm:bump_version patch && npm run npm:update_code_and_changelog",
|
||||
"npm:prepare_release:minor": "npm run npm:bump_version minor && npm run npm:update_code_and_changelog",
|
||||
"npm:prepare_release:major": "npm run npm:bump_version major && npm run npm:update_code_and_changelog",
|
||||
"npm:bump_version": "npm --prefix npm_package version --no-git-tag-version --",
|
||||
"npm:update_code_and_changelog": "node compile.js && ./release-update-changelog.sh"
|
||||
},
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
|
|
|
|||
|
|
@ -0,0 +1,24 @@
|
|||
#!/bin/bash
|
||||
|
||||
# Ensure we're in the correct directory for relative paths to work
|
||||
script_dir="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
|
||||
cd "$script_dir"
|
||||
|
||||
version=$(jq -r .version npm_package/package.json)
|
||||
release_date=$(date +%Y-%m-%d)
|
||||
|
||||
temp_file=$(mktemp)
|
||||
|
||||
# Copy header and add new unreleased section
|
||||
head -n 6 CHANGELOG.md > "$temp_file"
|
||||
cat >> "$temp_file" << EOF
|
||||
|
||||
## Unreleased
|
||||
|
||||
EOF
|
||||
|
||||
# Replace the old unreleased section with new version
|
||||
sed "s/## Unreleased/## [$version] - $release_date/" CHANGELOG.md | \
|
||||
tail -n +8 >> "$temp_file"
|
||||
|
||||
mv "$temp_file" npm_package/CHANGELOG.md
|
||||
Loading…
Reference in New Issue