sqlitecpp-workflow

# SQLiteCpp Workflow ## Required workflow For an implementation request, complete the local Git workflow before handing the work back: 1. Load `sqlitecpp-git-branching`, inspect `git status`, and create the task branch before editing. 2. Implement the change and its tests, public API documentation, and any required build-file updates. 3. Build and run the relevant tests. 4. Commit the completed work according to the atomic and independent commit rules below. 5. Report the branch name, commit hashes, and validation results. If work was accidentally started on `master`, create the correctly named branch immediately while preserving the working tree, then continue the workflow there. Do not leave completed implementation changes uncommitted unless the user explicitly asks for an uncommitted patch. ## Change checklist - [ ] Public API has Doxygen (`@brief`, `@param`, `@return`, `@throw`). - [ ] Tests added under `tests/`. - [ ] Build files updated (`CMakeLists.txt`, `meson.build`). - [ ] `CHANGELOG.md` updated for user-facing changes (in a **separate commit** after opening the PR). ## CHANGELOG conventions If the user explicitly requests no CHANGELOG change or entry, leave `CHANGELOG.md` unchanged. Update `CHANGELOG.md` in the same PR that makes the change, but **in a separate commit** created after the PR is opened so the PR number is known. Normally add one line per PR under the current unreleased version heading (`Version X.Y.Z - <year> ???`). Create that heading if it does not exist yet. - Append a new bullet at the end of the current unreleased section by default. Do not reorder existing entries or insert the new entry by category unless there is a clear reason to group related changes. - Related PRs may be kept together or combined when that makes the history clearer. For example, keep consecutive updates to the bundled SQLite library together instead of separating them by append order. - Normally use one bullet per PR: `- <description> (#NNN)`. Keep all PR numbers at the end when related PRs share an entry: `- <description> (#NNN) (#MMM)`. - Write in the imperative mood, present tense: "Add", "Fix", "Update", "Remove". Not "Added", "Fixes", or "Adding". - Keep each entry to a single line that names the user-facing effect, not the internal mechanics. - A change merged straight to master without a PR still gets a bullet; omit the `(#NNN)` and note it was committed directly to master. - ASCII only, no em dashes. Run the entry through the `humanizer` skill before committing so the prose stays plain and free of AI tells. Finalizing the version heading and tagging belong to the release process: see [[sqlitecpp-release]]. **Workflow for CHANGELOG updates:** 1. Commit source code changes (tests, implementation, etc.) in one or more atomic commits 2. Push the branch and open the PR to obtain the PR number 3. Create a separate final commit adding only the CHANGELOG entry with the PR number 4. Push the CHANGELOG commit to the same branch This keeps commits atomic (CHANGELOG is separate from code) and allows the PR number to be included in the CHANGELOG entry. Keep the CHANGELOG commit last in the PR history. If review follow-ups add source, test, or documentation commits after it, reorder the branch before pushing again. ## Pull requests - Open PRs with `gh pr create` against `master`. - The maintainer wants a **short and tight** PR description: one or two sentences on what the PR does and why, plus a brief bullet list only when it genuinely helps review. No filler, no restating the diff, no marketing. ASCII only, no em dashes; run it through `humanizer` if unsure. ## Git commits and pushing - Use a clean, short imperative headline, aiming for about 50 characters. - Nearly always add one short paragraph after a blank line: usually one or two sentences explaining why the change is needed, including the failure condition when useful. Wrap at about 72 characters. - Keep messages self-explanatory without repeating the diff, listing routine validation, or recounting the investigation. Add detail only when essential to understand the change; omit the body for a truly self-explanatory change. Put fuller explanations and validation results in the PR description or task response. - Make commits **atomic and independent**. Each commit must have exactly one purpose and be reviewable on its own. Include only the implementation, tests, and documentation required for that purpose. - Do not mix distinct bug fixes, API additions, refactoring, formatting, workflow changes, or other unrelated work in one commit. A task containing separable outcomes, such as fixing existing behavior and adding a new API, requires separate commits. - **CHANGELOG.md updates must be in a separate final commit** from source code changes, created after the PR is opened so the PR number can be included. - Each commit must leave the repository in a valid state: it must compile and pass its relevant tests when checked out at that point in the branch history. - Push when the user has explicitly authorized pushing in the current session, including in the initial request. Do not ask again when that authorization already covers the branch and action. Otherwise, ask for permission stating the branch name and action (e.g., "Push branch `update-sqlite-3.52.2` to origin?"). ## Add a method Follow the required workflow above. Include: - A declaration with Doxygen in `include/SQLiteCpp/<Class>.h`. - The implementation in `src/<Class>.cpp`. - Tests in `tests/<Class>_test.cpp`. ## Add a class Follow the required workflow above. Include: - `include/SQLiteCpp/NewClass.h`, `src/NewClass.cpp`, and `tests/NewClass_test.cpp`. - The new files in `CMakeLists.txt` and `meson.build`. - The public header in `SQLiteCpp.h` when the class is public API.