Skip to content

Commit 02cf504

Browse files
committed
docs: a changelog, and the release checklist says to write in it
Every release so far has had its notes on the GitHub releases page and nowhere in the tree, so somebody standing in a checkout could not find out what they were about to take without leaving it. This adds CHANGELOG.md, Keep a Changelog format, starting at 0.6.0; earlier versions keep pointing at the releases page rather than being reconstructed from commits. The entry opens with what an upgrading operator has to do by hand — for 0.6.0 that is nothing — because that is the line people look for, and a changelog that buries it is a list of commits with better formatting. RELEASING.md gains the step, and says the GitHub release notes are this entry pasted: two places disagreeing about one release is exactly the drift that file exists to prevent.
1 parent 8386357 commit 02cf504

2 files changed

Lines changed: 86 additions & 2 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Changelog
2+
3+
The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
4+
and the numbers mean what [RELEASING.md](RELEASING.md) says they mean: while
5+
the major is `0`, a minor is anything you might have to read this file before
6+
taking.
7+
8+
Releases before 0.6.0 have their notes on the
9+
[GitHub releases page](https://github.com/OpenLabs-so/openanalytics/releases).
10+
11+
## [0.6.0] - 2026-09-05
12+
13+
**Upgrade notes: none.** `./upgrade.sh` and nothing else. The two ClickHouse
14+
migrations in this release only add columns, and the migrate container applies
15+
them while the upgrade runs.
16+
17+
### Added
18+
19+
- **Filters.** Clicking a row in Sources, Locations or the device cards keeps
20+
only the sessions that match it, and the overview re-reads with that filter
21+
applied. Four dimensions — source, country, city, device — combined with
22+
`and` across dimensions and `or` within one. What you picked shows as marks
23+
on the tab bar, each clearing on its own. A filtered view is rebuilt from raw
24+
events rather than read off a rollup, so it covers at most 92 days; past that
25+
the cards offer to shorten the range or drop the filters. The same grammar
26+
serves the dashboard, `/v1/read` and MCP, so they cannot drift.
27+
- **Entries and exits.** Top Pages carries entrances, exits and a bounce rate
28+
per path, and can be ranked by any of them. The ranking is a question put to
29+
the server rather than a re-sort of the rows on screen.
30+
- **Click ids as sources.** `gclid`, `fbclid`, `msclkid` and their companions
31+
name the ad network a visit came from when the referrer does not.
32+
- **`?ref=` names a source.** A link you control can carry `?ref=twitter` or
33+
`?ref=newsletter`, and visits that would have read as Direct get that name
34+
instead. Known names fold onto the site they mean; anything else is kept as
35+
written. A referrer the browser did send always wins.
36+
- **Polar as a revenue provider.** A second provider a site can connect
37+
alongside Stripe, with Standard Webhooks signature verification.
38+
- **Umami import.** An adapter for Umami exports, and one archive entry may now
39+
fill several reports.
40+
- **Overview poster.** A share button turns the numbers on screen into an
41+
image — the site's mark, the period, the headline figures and the traffic
42+
curve — as a PNG or on the clipboard. It draws from what the board already
43+
has, so it cannot disagree with the screen it was made from.
44+
- **Realtime names who is here.** The overview's realtime card lists the
45+
visitors present rather than the paths that are busy, and a live badge sits
46+
beside the Overview and Realtime titles.
47+
- **MCP hints.** Every tool spells out its hints, native-app redirect URIs are
48+
accepted, and a root `.mcp.json` points at the hosted server.
49+
- **Dokploy.** The blueprint ships with an import config and a copyable raw
50+
link beside it.
51+
- Documentation for the dashboard: what each headline metric counts, what each
52+
breakdown is a cut of, how filters behave, and how to tag your own links.
53+
54+
### Changed
55+
56+
- **The tracker stands down for a site that is gone.** A `404` from the config
57+
read is a gone-marker, and `collection_paused` carries a body and an ETag;
58+
the tracker obeys both and stops asking.
59+
- Squircle cards fall back to rounder corners on engines without
60+
`corner-shape`, and to a plain radius where even that is unsupported.
61+
62+
### Fixed
63+
64+
- **Email.** A rate limit is retryable and a bad address is not, so a `429` no
65+
longer burns an address; a stranger's typo no longer becomes a page. A
66+
terminal failure is recorded as `failed`.
67+
- **Ingest.** The finalizer window is bounded, the outbox is leased and
68+
reclaimed rather than raced, the backlog carries an `available_at`, and the
69+
queue publishes its own metrics.
70+
- **Realtime.** A refusal is believed only once a fresh token has been refused
71+
too, so an expired token no longer reads as a revoked one.
72+
- **Shared reports.** Percentages are shares of the total rather than of the
73+
biggest row.
74+
75+
### Coming in 0.7.0
76+
77+
Fifteen-minute rollups, which serve every timezone including the half- and
78+
quarter-hour ones (+05:30, +05:45), with a one-time backfill the upgrader runs
79+
for you.

‎RELEASING.md‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -113,8 +113,13 @@ keepable. Not before.
113113
5. Watch it. **A release whose workflow failed is a tag pointing at images that
114114
do not exist**, and the failure mode for whoever tries it is a `docker
115115
compose pull` that cannot find a manifest.
116-
6. Write the release notes on the GitHub release. What changed, and — first,
117-
before anything else — whatever an upgrading operator has to do by hand.
116+
6. Add the entry to `CHANGELOG.md` in the same commit as the version bump. It
117+
opens with what an upgrading operator has to do by hand, or with
118+
**Upgrade notes: none** — that line is the first thing somebody looks for
119+
and the reason the file exists rather than a list of commits.
120+
7. Write the release notes on the GitHub release. They are the CHANGELOG entry
121+
for this version, pasted: two places that say different things about one
122+
release is the drift this file exists to prevent.
118123

119124
**Pre-releases** are `vX.Y.Z-rc.N`. They publish the same ten images under the
120125
pre-release tag and deliberately do not move `latest`, so the way to test the

0 commit comments

Comments
 (0)