Skip to content

Commit b4a97db

Browse files
authored
feat: release and publish both packages independently, with docs and logos (#52)
1 parent c7913ab commit b4a97db

14 files changed

Lines changed: 397 additions & 97 deletions

‎.github/workflows/checks.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -59,12 +59,12 @@ jobs:
5959
- name: Run unit tests with coverage
6060
run: npm run test:coverage
6161

62-
- name: Comment coverage on PR
62+
- name: Comment ngx coverage on PR
6363
uses: ArtiomTr/jest-coverage-report-action@262a7bb0b20c4d1d6b6b026af0f008f78da72788 # v2.3.1
6464
if: github.event_name == 'pull_request'
6565
continue-on-error: true
6666
with:
67-
custom-title: Coverage report
67+
custom-title: Ngx coverage report
6868
coverage-file: ./coverage/report.json
6969
# Tests already ran above; the action only formats the report.
7070
skip-step: all

‎.github/workflows/release-please.yml‎

Lines changed: 32 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,10 @@ jobs:
1414
contents: write
1515
pull-requests: write
1616
outputs:
17-
release_created: ${{ steps.release.outputs['projects/ngx-ui-watchtower--release_created'] }}
17+
core_release_created: ${{ steps.release.outputs['projects/ui-watchtower--release_created'] }}
18+
ngx_release_created: ${{ steps.release.outputs['projects/ngx-ui-watchtower--release_created'] }}
1819
steps:
19-
- uses: googleapis/release-please-action@v5
20+
- uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0
2021
id: release
2122
with:
2223
config-file: release-please-config.json
@@ -26,7 +27,9 @@ jobs:
2627

2728
publish:
2829
needs: release-please
29-
if: ${{ needs.release-please.outputs.release_created == 'true' }}
30+
if: >-
31+
${{ needs.release-please.outputs.core_release_created == 'true' ||
32+
needs.release-please.outputs.ngx_release_created == 'true' }}
3033
runs-on: ubuntu-latest
3134
permissions:
3235
# Required for npm trusted publishing (OIDC). No npm token needed.
@@ -48,9 +51,32 @@ jobs:
4851
- name: Install dependencies
4952
run: npm ci
5053

51-
- name: Build library
54+
- name: Build both packages
5255
run: npm run build
5356

54-
- name: Publish to npm
57+
# The core first: the Angular package depends on it, and a failed step
58+
# stops the job. Each skips a version npm already has, so "Re-run failed
59+
# jobs" finishes a partial release.
60+
- name: Publish the core
61+
if: needs.release-please.outputs.core_release_created == 'true'
62+
working-directory: dist/ui-watchtower
63+
run: |
64+
name=$(node -p "require('./package.json').name")
65+
version=$(node -p "require('./package.json').version")
66+
if [ "$(npm view "$name@$version" version)" = "$version" ]; then
67+
echo "$name@$version is already on npm"
68+
else
69+
npm publish
70+
fi
71+
72+
- name: Publish the Angular package
73+
if: needs.release-please.outputs.ngx_release_created == 'true'
5574
working-directory: dist/ngx-ui-watchtower
56-
run: npm publish
75+
run: |
76+
name=$(node -p "require('./package.json').name")
77+
version=$(node -p "require('./package.json').version")
78+
if [ "$(npm view "$name@$version" version)" = "$version" ]; then
79+
echo "$name@$version is already on npm"
80+
else
81+
npm publish
82+
fi

‎README.md‎

Lines changed: 101 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,29 @@
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

7484
Four 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

126136
Releases 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

Comments
 (0)