11<p align =" center " >
2- <picture >
3- <source media="(prefers-color-scheme: dark)" srcset="assets/logo/logo-stacked-dark.svg">
4- <source media="(prefers-color-scheme: light)" srcset="assets/logo/logo-stacked-light.svg">
5- <img src="assets/logo/logo-stacked-auto.svg" alt="Angular UI Watchtower" width="280">
6- </picture >
2+ <img src =" assets/logo/logo-stacked-light.svg#gh-light-mode-only " alt =" UI Watchtower " width =" 280 " >
3+ <img src =" assets/logo/logo-stacked-dark.svg#gh-dark-mode-only " alt =" UI Watchtower " width =" 280 " >
74</p >
85
9- # Angular UI Watchtower
6+ # UI Watchtower
107
11- Source of [ ` @absaoss-cps/ngx-ui-watchtower ` ] ( https://www.npmjs.com/package/@absaoss-cps/ngx-ui-watchtower ) ,
12- a telemetry library for Angular apps: scenarios (user end-to-end journeys or specific functional workflows through an app), BI events and
13- logs, with an optional AWS CloudWatch RUM sink. It builds on
14- [ ` @absaoss-cps/ui-watchtower ` ] ( projects/ui-watchtower/README.md ) , the
15- framework-independent engine, which lives here too.
8+ Telemetry for frontend applications, in three parts:
169
17- How to use the library: [ projects/ngx-ui-watchtower/README.md] ( projects/ngx-ui-watchtower/README.md )
18- (also the npm page).
19- How it is designed: [ projects/ngx-ui-watchtower/DESIGN.md] ( projects/ngx-ui-watchtower/DESIGN.md ) .
10+ - ** Scenarios** — did a user journey or a workflow succeed, and how long did
11+ it take?
12+ - ** BI events** — which features are used?
13+ - ** Logs** — what exactly happened?
14+
15+ Events go to AWS CloudWatch RUM or another destination you choose; logs go
16+ to a backend you provide.
17+
18+ It comes as two packages, each with its own version:
19+
20+ | Package | Use it in | Guide |
21+ | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------- |
22+ | [ ` @absaoss-cps/ui-watchtower ` ] ( https://www.npmjs.com/package/@absaoss-cps/ui-watchtower ) | Any frontend: plain JavaScript or TypeScript, or any framework. Framework adapters are built on it ([ how] ( docs/ADAPTERS.md ) ). | [ README] ( projects/ui-watchtower/README.md ) |
23+ | [ ` @absaoss-cps/ngx-ui-watchtower ` ] ( https://www.npmjs.com/package/@absaoss-cps/ngx-ui-watchtower ) | Angular applications. A thin adapter over ` @absaoss-cps/ui-watchtower ` : Angular providers, injectable services and Observables around the same engine. | [ README] ( projects/ngx-ui-watchtower/README.md ) |
24+
25+ Each guide is also the package's npm page. How it is designed:
26+ [ projects/ngx-ui-watchtower/DESIGN.md] ( projects/ngx-ui-watchtower/DESIGN.md ) .
2027
2128## Layout
2229
@@ -35,10 +42,13 @@ projects/ngx-ui-watchtower/
3542 README.md usage guide, published to npm
3643 DESIGN.md full design
3744 package.json the published package's manifest
38- scripts/ the public API snapshot, and the packaging smoke test
45+ docs/ ADAPTERS.md: how to write a framework adapter
46+ scripts/ the public API snapshot, the packaging smoke test, and publishing
3947```
4048
41- The Angular package depends on the core, never the other way round.
49+ The Angular package depends on the core, never the other way round. Each
50+ package has its own version; a core release also releases the Angular
51+ package, with its dependency moved (see [ Releases] ( #releases ) ).
4252
4353## Getting started
4454
@@ -56,20 +66,20 @@ application does. Tests and the typecheck read the core's source.
5666
5767## Scripts
5868
59- | Script | What it does |
60- | ----------------------- | -------------------------------------------------------------- |
61- | ` npm run build ` | Builds both packages (production), the core first |
62- | ` npm run watch ` | Builds the core, then rebuilds the Angular package on change |
63- | ` npm run test ` | Runs the unit tests of both packages (Jest) |
64- | ` npm run test:core ` | Runs the core's unit tests only: plain Jest, no Angular |
65- | ` npm run test:coverage ` | Runs the unit tests with coverage, as CI does |
66- | ` npm run typecheck ` | Builds the core, then type-checks every tsconfig and type test |
67- | ` npm run api:check ` | Builds both packages, then compares their public APIs |
68- | ` npm run api:update ` | Builds both packages, then rewrites their snapshots |
69- | ` npm run smoke ` | Installs the built packages, packed, into throwaway consumers |
70- | ` npm run lint ` | ESLint, no warnings allowed |
71- | ` npm run format ` | Formats with Prettier |
72- | ` npm run format:check ` | Checks formatting without writing |
69+ | Script | What it does |
70+ | ----------------------- | ---------------------------------------------------------------- |
71+ | ` npm run build ` | Builds both packages (production), the core first |
72+ | ` npm run watch ` | Builds the core, then rebuilds the Angular package on change |
73+ | ` npm run test ` | Runs the unit tests of both packages (Jest) |
74+ | ` npm run test:core ` | Runs the core's unit tests only: plain Jest, no Angular |
75+ | ` npm run test:coverage ` | Runs the unit tests with coverage, as CI does; fails below 90% |
76+ | ` npm run typecheck ` | Builds the core, then type-checks every tsconfig and type test |
77+ | ` npm run api:check ` | Builds both packages, then compares their public APIs |
78+ | ` npm run api:update ` | Builds both packages, then rewrites their snapshots |
79+ | ` npm run smoke ` | Installs the built packages, packed, into throwaway consumers |
80+ | ` npm run lint ` | ESLint, no warnings allowed |
81+ | ` npm run format ` | Formats with Prettier |
82+ | ` npm run format:check ` | Checks formatting without writing |
7383
7484Four checks guard what consumers depend on:
7585
@@ -124,15 +134,67 @@ Squash-merge pull requests: the title then becomes the commit message on
124134## Releases
125135
126136Releases are automated with [ release-please] ( https://github.com/googleapis/release-please )
127- — don't publish by hand.
128-
129- 1 . Every push to ` main ` updates a release PR. ` feat ` bumps the minor version,
130- ` fix ` , ` perf ` and ` revert ` the patch; until 1.0, a breaking change bumps
131- the minor. Other types don't trigger a release.
132- 2 . The release PR holds the version bump and the ` CHANGELOG.md ` entry.
133- 3 . Merging it tags the release, creates the GitHub release and publishes the
134- package to npm from GitHub Actions through trusted publishing — no npm
135- token.
137+ — don't publish by hand. Each package has its own version and changelog, and
138+ is released when it changes:
139+
140+ | A change to | Releases |
141+ | ------------------- | ------------------------------------------------------------------------------------------ |
142+ | The Angular package | The Angular package |
143+ | The core | The core, and a patch of the Angular package that moves its dependency to ` ^ ` the new core |
144+ | Both | Each, with its own bump |
145+
146+ 1 . Every push to ` main ` updates one release PR, for every package with
147+ changes. ` feat ` bumps the minor version, ` fix ` , ` perf ` and ` revert ` the
148+ patch; until 1.0, a breaking change bumps the minor. Other types don't
149+ trigger a release.
150+ 2 . The release PR holds each released package's version bump and
151+ ` CHANGELOG.md ` entry. When the core is released, Release Please's
152+ ` node-workspace ` plugin also moves the Angular package's dependency on the
153+ core and releases it as a patch, so it always depends on the core it was
154+ built against.
155+ 3 . Merging it tags each release, ` ui-watchtower-v<version> ` or
156+ ` ngx-ui-watchtower-v<version> ` (until 0.4.0, the Angular package's tags
157+ were ` v<version> ` ), and creates its GitHub release. GitHub Actions then
158+ publishes what was released, the core before the Angular package, through
159+ trusted publishing — no npm token.
160+
161+ ** A failed publish** stops before the Angular package, so it never depends
162+ on a core that isn't on npm. To finish a partial release, use ** Re-run failed
163+ jobs** on that workflow run: each package's step skips a version npm already
164+ has.
165+
166+ ** The core's first release is 0.1.0** , set by its ` initial-version ` in
167+ ` release-please-config.json ` , and published by the workflow like every
168+ release. npm adds a trusted publisher only to a package that exists, so
169+ before the first release PR that releases the core is merged, an
170+ ` @absaoss-cps ` owner publishes a placeholder, ` 0.0.0 ` , by hand:
171+
172+ ``` bash
173+ npm login
174+ mkdir ui-watchtower-placeholder && cd ui-watchtower-placeholder
175+ echo ' { "name": "@absaoss-cps/ui-watchtower", "version": "0.0.0", "description": "Placeholder: the first release is 0.1.0", "license": "Apache-2.0" }' > package.json
176+ npm publish --access public
177+ ```
178+
179+ Then, on npmjs.com, in the package's settings, add the trusted publisher the
180+ Angular package has: GitHub Actions, ` AbsaOSS/ui-watchtower ` , workflow
181+ ` release-please.yml ` . Once the workflow has published 0.1.0, deprecate the
182+ placeholder:
183+
184+ ``` bash
185+ npm deprecate @absaoss-cps/ui-watchtower@0.0.0 " Placeholder, use 0.1.0 or later"
186+ ```
187+
188+ If the release PR is merged first, publishing the core fails, and the
189+ Angular package isn't published: add the trusted publisher, then re-run the
190+ failed job.
191+
192+ ` bootstrap-sha ` in ` release-please-config.json ` is the commit tagged
193+ ` v0.4.0 ` : it keeps what that release shipped out of the first changelogs,
194+ and is read only until both packages have a release. If another ` v ` release
195+ reaches ` main ` first, set it to that release's commit. That commit is also
196+ tagged ` ngx-ui-watchtower-v0.4.0 ` , in the new format, so the Angular
197+ package's first changelog compares from a tag that exists.
136198
137199## License
138200
0 commit comments