Bring project documentation up to ffr's standard #61

New issue

Closed

opened 2026-08-16 11:14:14 +02:00 by myrmidex · 2 comments

myrmidex commented

2026-08-16 11:14:14 +02:00

Owner

incr's project-level documentation is thin next to ffr's. Now that v0.4.0 has settled what the app actually is, the docs should match.

Licence — currently inconsistent in three places

Source	Says
`LICENSE`	GNU GPL v3
`README.md` (License section)	GNU GPL v3
`composer.json:10`	MIT

Decision: relicense to AGPL v3, matching ffr. AGPL is GPL plus Section 13, which closes the network-use loophole — a fork hosted as a service must offer its source. Straightforward here: sole author, no external contributors.

Replace LICENSE with the AGPL v3 text (ffr's is the unmodified FSF version — copy it)
composer.json → "license": "AGPL-3.0-or-later"
README License section → AGPL, matching ffr's wording
README badge (currently GPLv3)

CONTRIBUTING.md — missing

Mirror ffr's structure: Reporting issues · Development setup · Before opening a pull request · Commits · License.

Should reflect incr's own reality — nix-shell and the dev-* helpers, the three gates (Pint, PHPStan level 7, PHPUnit), and the single-line <issue-id> - <Description> commit format.

CHANGELOG.md — missing

Keep-a-Changelog format, as ffr uses. Start at [0.4.0] — this milestone is a big enough story to be worth writing down properly: a VWCE share tracker became a counter, React/Inertia became Livewire, nine tables became one.

Note ffr's 1.4.1 entry already documents the same CI work done here (prebuilt image, wrong Composer cache path, DNS) — worth reading as a model for tone and level of detail.

Screenshots — missing

ffr keeps them in docs/screenshots/ and embeds them in a ## Screenshots section after the intro, each with a sentence of context.

incr needs far fewer — realistically two:

the counter at rest
the set-value dialog open

Both on the black/red terminal aesthetic, which is the most distinctive thing about the app and currently invisible to anyone reading the repo.

README gaps beyond the above

No ## Screenshots section
No ## Contributing section pointing at CONTRIBUTING.md
ffr has a ## Note on AI assistance section; consider whether incr wants the same

Acceptance criteria

LICENSE, composer.json and README all state AGPL v3 — no contradictions
CONTRIBUTING.md exists and describes incr's actual setup, not ffr's
CHANGELOG.md exists with a [0.4.0] entry
At least two screenshots in docs/screenshots/, embedded in the README
README has Screenshots and Contributing sections

Note

Requested for v0.4.0 rather than deferred, so the release ships with documentation that matches the app.

incr's project-level documentation is thin next to ffr's. Now that v0.4.0 has settled what the app actually is, the docs should match. ## Licence — currently inconsistent in three places | Source | Says | |---|---| | `LICENSE` | GNU **GPL** v3 | | `README.md` (License section) | GNU **GPL** v3 | | `composer.json:10` | **MIT** | **Decision: relicense to AGPL v3**, matching ffr. AGPL is GPL plus Section 13, which closes the network-use loophole — a fork hosted as a service must offer its source. Straightforward here: sole author, no external contributors. - [ ] Replace `LICENSE` with the AGPL v3 text (ffr's is the unmodified FSF version — copy it) - [ ] `composer.json` → `"license": "AGPL-3.0-or-later"` - [ ] README License section → AGPL, matching ffr's wording - [ ] README badge (currently GPLv3) ## CONTRIBUTING.md — missing Mirror ffr's structure: Reporting issues · Development setup · Before opening a pull request · Commits · License. Should reflect incr's own reality — `nix-shell` and the `dev-*` helpers, the three gates (Pint, PHPStan level 7, PHPUnit), and the single-line `<issue-id> - <Description>` commit format. ## CHANGELOG.md — missing Keep-a-Changelog format, as ffr uses. Start at `[0.4.0]` — this milestone is a big enough story to be worth writing down properly: a VWCE share tracker became a counter, React/Inertia became Livewire, nine tables became one. Note ffr's `1.4.1` entry already documents the same CI work done here (prebuilt image, wrong Composer cache path, DNS) — worth reading as a model for tone and level of detail. ## Screenshots — missing ffr keeps them in `docs/screenshots/` and embeds them in a `## Screenshots` section after the intro, each with a sentence of context. incr needs far fewer — realistically two: - the counter at rest - the set-value dialog open Both on the black/red terminal aesthetic, which is the most distinctive thing about the app and currently invisible to anyone reading the repo. ## README gaps beyond the above - No `## Screenshots` section - No `## Contributing` section pointing at CONTRIBUTING.md - ffr has a `## Note on AI assistance` section; consider whether incr wants the same ## Acceptance criteria - [ ] `LICENSE`, `composer.json` and README all state AGPL v3 — no contradictions - [ ] `CONTRIBUTING.md` exists and describes incr's actual setup, not ffr's - [ ] `CHANGELOG.md` exists with a `[0.4.0]` entry - [ ] At least two screenshots in `docs/screenshots/`, embedded in the README - [ ] README has Screenshots and Contributing sections ## Note Requested for v0.4.0 rather than deferred, so the release ships with documentation that matches the app.

myrmidex added this to the v0.4.0 milestone 2026-08-16 11:14:14 +02:00

myrmidex added the

enhancement

label 2026-08-16 11:14:14 +02:00

myrmidex self-assigned this 2026-08-16 11:14:14 +02:00

myrmidex commented

2026-08-16 11:33:41 +02:00

Author

Owner

Scope correction: one screenshot, not two

The ticket asked for two — the counter and the set-value dialog. That was over-specified: incr is a single-view app, and the dialog opens on the same screen. Two near-identical images would pad the README rather than inform.

Reduced to one screenshot of the counter, with the caption mentioning [SET VALUE].

Acceptance criteria amended:

LICENSE, composer.json and README all state AGPL v3 — no contradictions
CONTRIBUTING.md exists and describes incr's actual setup, not ffr's
CHANGELOG.md exists with a [0.4.0] entry
~~At least two screenshots~~ One screenshot in docs/screenshots/counter.png, embedded in the README
README has Screenshot and Contributing sections

## Scope correction: one screenshot, not two The ticket asked for two — the counter and the set-value dialog. That was over-specified: incr is a single-view app, and the dialog opens on the same screen. Two near-identical images would pad the README rather than inform. Reduced to one screenshot of the counter, with the caption mentioning `[SET VALUE]`. Acceptance criteria amended: - [x] `LICENSE`, `composer.json` and README all state AGPL v3 — no contradictions - [x] `CONTRIBUTING.md` exists and describes incr's actual setup, not ffr's - [x] `CHANGELOG.md` exists with a `[0.4.0]` entry - [ ] ~~At least two screenshots~~ **One screenshot** in `docs/screenshots/counter.png`, embedded in the README - [x] README has Screenshot and Contributing sections

myrmidex commented

2026-08-16 12:04:44 +02:00

Author

Owner

Done — `2183dff` and follow-up

Shipped in v0.4.0.

Licence

Was contradictory in three places: LICENSE said GPL v3, the README said GPL v3, composer.json:10 said MIT. All three now say AGPL v3.

LICENSE — ffr's unmodified FSF AGPL text, verified identical and complete (Section 13 present)
composer.json — "license": "AGPL-3.0-only", matching ffr's identifier exactly
README badge and License section

CONTRIBUTING.md

Mirrors ffr's structure, but describes incr's own setup: its dev-* commands including dev-composer, its ports, MySQL rather than MariaDB, no Redis.

Two deliberate differences from ffr's text:

PHPStan has no baseline here and the project is clean at level 7, so the guidance is "keep it that way" rather than "don't add baseline entries"
A note that feature requests adding tracking, history or goals are likely to be declined — a previous version had all three and they were removed on purpose

CHANGELOG.md

Keep-a-Changelog format with a [0.4.0] entry built from the closed tickets rather than memory.

Screenshot

Scope reduced from two to one, per the comment above — incr is a single-view app and the dialog opens on the same screen, so two near-identical images would pad rather than inform.

docs/screenshots/counter.png, cropped from 3741×2022 to 3741×1150 because the counter sat in the top third with two-thirds empty black below. 321 kB → 139 kB, nothing clipped.

README

Added Screenshot and Contributing sections; badge updated to AGPL.

Acceptance criteria

LICENSE, composer.json and README all state AGPL v3 — no contradictions
CONTRIBUTING.md exists and describes incr's actual setup, not ffr's
CHANGELOG.md exists with a [0.4.0] entry
One screenshot in docs/screenshots/counter.png, embedded in the README
README has Screenshot and Contributing sections

## Done — `2183dff` and follow-up Shipped in v0.4.0. ### Licence Was contradictory in three places: `LICENSE` said GPL v3, the README said GPL v3, `composer.json:10` said **MIT**. All three now say AGPL v3. - `LICENSE` — ffr's unmodified FSF AGPL text, verified identical and complete (Section 13 present) - `composer.json` — `"license": "AGPL-3.0-only"`, matching ffr's identifier exactly - README badge and License section ### CONTRIBUTING.md Mirrors ffr's structure, but describes incr's own setup: its `dev-*` commands including `dev-composer`, its ports, MySQL rather than MariaDB, no Redis. Two deliberate differences from ffr's text: - PHPStan has **no baseline** here and the project is clean at level 7, so the guidance is "keep it that way" rather than "don't add baseline entries" - A note that feature requests adding tracking, history or goals are likely to be declined — a previous version had all three and they were removed on purpose ### CHANGELOG.md Keep-a-Changelog format with a `[0.4.0]` entry built from the closed tickets rather than memory. ### Screenshot Scope reduced from two to one, per the comment above — incr is a single-view app and the dialog opens on the same screen, so two near-identical images would pad rather than inform. `docs/screenshots/counter.png`, cropped from 3741×2022 to 3741×1150 because the counter sat in the top third with two-thirds empty black below. 321 kB → 139 kB, nothing clipped. ### README Added Screenshot and Contributing sections; badge updated to AGPL. ### Acceptance criteria - [x] `LICENSE`, `composer.json` and README all state AGPL v3 — no contradictions - [x] `CONTRIBUTING.md` exists and describes incr's actual setup, not ffr's - [x] `CHANGELOG.md` exists with a `[0.4.0]` entry - [x] One screenshot in `docs/screenshots/counter.png`, embedded in the README - [x] README has Screenshot and Contributing sections

myrmidex closed this issue

2026-08-16 12:04:46 +02:00