README: add development and maintainer runbook sections #7

New Issue

2026-05-05T22:32:50Z

mahseiah_ai commented

2026-05-05 22:32:50 +00:00

Problem

The README explains the library concepts and usage examples well, but it does not yet document the basic operational process for maintaining the project. For a small library like this, contributors and maintainers should be able to answer practical questions from README.md alone:

How do I set up and validate the project locally?
What commands should I run before opening a PR?
What does CI do, and when does it run?
What is the expected release flow?

For now, this content should live in the main README.md rather than a separate runbook or contributor guide. The project is small enough that keeping the operational guidance close to the main documentation is the simplest option.

Goals / scope

Add a short Development section to README.md covering local setup and validation commands actually used by this repo
Document the expected local verification flow, including Bun-based test execution
Add a brief CI section describing what Gitea Actions checks and when CI runs
Add a brief Release / maintenance section describing the intended maintainer workflow at a high level
Explicitly document the expected release tag format (x.y.z)
Keep the guidance lightweight, practical, and task-oriented

Out of scope / non-goals

Creating a separate RUNBOOK.md, CONTRIBUTING.md, or full maintainer handbook
Rewriting the entire README or changing the user-facing usage documentation substantially
Adding or automating new tooling as part of this issue
Defining project governance, support policy, or a large contributor process

Acceptance criteria

README.md contains clear sections for local development, verification, CI expectations, and release/maintenance steps
The documented commands match the repo's actual scripts/tooling and reflect the Bun-based test workflow
The README explains the intended release tag format (x.y.z) and where it matters operationally
A new contributor can follow the README to run tests and understand the basic maintainer workflow without extra project-specific context
The added content remains concise and fits naturally in the README

Open questions / notes

Should the README mention npm publish directly now, or keep publish details high-level until the release workflow exists?
If there is a preferred version bump or changelog convention, we should capture it briefly; otherwise keep the release section generic.
If the README becomes too long after this addition, we can later split the operational content into a dedicated contributor/runbook doc — but not yet.

## Problem The README explains the library concepts and usage examples well, but it does not yet document the basic operational process for maintaining the project. For a small library like this, contributors and maintainers should be able to answer practical questions from `README.md` alone: - How do I set up and validate the project locally? - What commands should I run before opening a PR? - What does CI do, and when does it run? - What is the expected release flow? For now, this content should live in the main `README.md` rather than a separate runbook or contributor guide. The project is small enough that keeping the operational guidance close to the main documentation is the simplest option. ## Goals / scope - [ ] Add a short **Development** section to `README.md` covering local setup and validation commands actually used by this repo - [ ] Document the expected local verification flow, including Bun-based test execution - [ ] Add a brief **CI** section describing what Gitea Actions checks and when CI runs - [ ] Add a brief **Release / maintenance** section describing the intended maintainer workflow at a high level - [ ] Explicitly document the expected release tag format (`x.y.z`) - [ ] Keep the guidance lightweight, practical, and task-oriented ## Out of scope / non-goals - [ ] Creating a separate `RUNBOOK.md`, `CONTRIBUTING.md`, or full maintainer handbook - [ ] Rewriting the entire README or changing the user-facing usage documentation substantially - [ ] Adding or automating new tooling as part of this issue - [ ] Defining project governance, support policy, or a large contributor process ## Acceptance criteria - [ ] `README.md` contains clear sections for local development, verification, CI expectations, and release/maintenance steps - [ ] The documented commands match the repo's actual scripts/tooling and reflect the Bun-based test workflow - [ ] The README explains the intended release tag format (`x.y.z`) and where it matters operationally - [ ] A new contributor can follow the README to run tests and understand the basic maintainer workflow without extra project-specific context - [ ] The added content remains concise and fits naturally in the README ## Open questions / notes - Should the README mention `npm publish` directly now, or keep publish details high-level until the release workflow exists? - If there is a preferred version bump or changelog convention, we should capture it briefly; otherwise keep the release section generic. - If the README becomes too long after this addition, we can later split the operational content into a dedicated contributor/runbook doc — but not yet.

jdb commented

2026-05-05 22:42:40 +00:00

Regarding the open questions:

We should mention npm publish, but as part of the current manual release process. This process is (in brief):
- Ensure the library builds and passes test suites (bun run build, bun test).
- Update the version (typically via update_version interactive using update_version).
- Commit the version bump and tag it with the version number.
- Log in to npmjs.com via npm login
- Publish the package via npm publish.
We use semver (major.minor.patch). Major versions should be reserved for breaking changes. Minor versions are for new functionality or features, patch version are for incremental improvements and bugfixes.

Regarding the open questions: - We should mention `npm publish`, but as part of the current manual release process. This process is (in brief): - Ensure the library builds and passes test suites (`bun run build`, `bun test`). - Update the version (typically via `update_version interactive` using [update_version](https://git.probatem.com/probatem/update-version)). - Commit the version bump and tag it with the version number. - Log in to npmjs.com via `npm login` - Publish the package via `npm publish`. - We use semver (`major.minor.patch`). Major versions should be reserved for breaking changes. Minor versions are for new functionality or features, patch version are for incremental improvements and bugfixes.

mahseiah_ai was assigned by jdb

2026-05-05 23:00:59 +00:00

mahseiah_ai referenced this issue from a commit

2026-05-06 02:14:35 +00:00

docs: Add Development, CI, and Maintenance sections to README (fixes #7)

mahseiah_ai closed this issue

2026-05-06 02:17:56 +00:00

jdb referenced this issue from a commit

2026-05-07 12:38:07 +00:00

docs: Add Development, CI, and Maintenance sections to README (fixes #7)

Sign in to join this conversation.