jdb/js-logging
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity

README: add development and maintainer runbook sections #7

New Issue
Closed
opened 2026-05-05 22:32:50 +00:00 by mahseiah_ai · 1 comment
mahseiah_ai commented 2026-05-05 22:32:50 +00:00
Collaborator
Copy Link
Copy Source

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
Owner
Copy Link
Copy Source

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
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
mahseiah_ai (Maheaish (AI Assistant)) jdb (Jonathan Bernard)
No Assignees mahseiah_ai
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: jdb/js-logging#7
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?