From a1bc75372fa25af7510066c60c0ac24e39097651 Mon Sep 17 00:00:00 2001 From: "./root" Date: Sat, 20 Jun 2026 03:44:00 +0200 Subject: [PATCH 1/8] Added Semantic Versioning convention doc --- docs/versioning.md | 49 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 docs/versioning.md diff --git a/docs/versioning.md b/docs/versioning.md new file mode 100644 index 0000000..226991e --- /dev/null +++ b/docs/versioning.md @@ -0,0 +1,49 @@ +# Versioning + +Chai follows [Semantic Versioning](https://semver.org/). Releases are tagged on `main` +as `vMAJOR.MINOR.PATCH` (for example `v1.2.0`). + +## What `v1.2.0` means + +It's three numbers, `MAJOR.MINOR.PATCH`, and the `v` is just a conventional prefix for the git tag: + +``` +v 1 . 2 . 0 + │ │ └── PATCH — backward-compatible bug fixes only + │ └────── MINOR — new functionality, backward-compatible (nothing breaks) + └────────── MAJOR — breaking/incompatible API changes +``` + +The rule is "bump the leftmost number that applies, and reset the ones to its right to 0": + +| Change | From → To | +| --- | --- | +| Fix a bug, no API change | `1.2.0` → `1.2.1` | +| Add a new component, old code still works | `1.2.1` → `1.3.0` | +| Rename/remove a public API (breaking) | `1.3.0` → `2.0.0` | + +## What this maps to for Chai + +For a design-system library, the bump maps cleanly to consumer impact: + +- **PATCH** — fix `CPrimaryButton`'s disabled color. +- **MINOR** — ship the new `CCards` / `CTabs` components (additive). +- **MAJOR** — the `ChaiSteal` → `ChaiSteel` rename, or dropping a public color token + (breaks anyone depending on it). + +## Two conventions + +- **`0.x.y`** means "pre-1.0, anything can change" — useful while the API is still settling. + Cut `v1.0.0` once the public API is committed to being stable. +- A **pre-release suffix** like `v1.3.0-alpha01` or `-rc1` marks a not-yet-final build + (the same scheme AGP uses). + +## Release flow + +`develop` is the integration branch; `main` is the release line. + +1. Day-to-day work merges into `develop` via PRs. +2. To cut a release, open a PR from `develop` into `main`. +3. Once it merges, tag the merge commit on `main` with `vMAJOR.MINOR.PATCH`. + +The tag on `main` is the release. Only release-ready code reaches `main`. From f69bd4cb5f3acdc7826a5f24bed53c32262bf65b Mon Sep 17 00:00:00 2001 From: "./root" Date: Sat, 20 Jun 2026 03:44:01 +0200 Subject: [PATCH 2/8] Linked versioning doc in README index --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index c30465b..911eb79 100755 --- a/README.md +++ b/README.md @@ -35,6 +35,7 @@ The Chai Design System Project Architecture is captured in detail: 5. [chaiLinter](https://github.com/droidconKE/chai/blob/master/docs/chaiLinter.md) - Explains the design system linter 6. [Atoms](https://github.com/droidconKE/chai/blob/master/docs/atoms.md) - Explains the atoms in the design system 7. [Components](https://github.com/droidconKE/chai/blob/master/docs/components.md) - Design system components +8. [Versioning](https://github.com/droidconKE/chai/blob/master/docs/versioning.md) - Semantic Versioning scheme and the release flow ## Implementing Chai From bdea55eccaf8ac4b8897e387c5e20f05a05906ca Mon Sep 17 00:00:00 2001 From: "./root" Date: Sat, 20 Jun 2026 04:19:37 +0200 Subject: [PATCH 3/8] Fixed README doc links to use relative paths --- README.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 911eb79..1a38472 100755 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ What is a design system: -To learn more about this look at this [Why Design Systems](https://github.com/droidconKE/chai/blob/master/docs/whyDesignSystems.md) - Explains the need for a design system in the context of compose. +To learn more about this look at this [Why Design Systems](./docs/whyDesignSystems.md) - Explains the need for a design system in the context of compose. ## About Chai @@ -28,14 +28,14 @@ This Project shows how you can use this design system in a multi module app mono ### Structure Of Chai's Design System Project, The Chai Design System Project Architecture is captured in detail: -1. [Why Design Systems](https://github.com/droidconKE/chai/blob/master/docs/whyDesignSystems.md) - Explains the need for a design system in the context of compose. -2. [Architecture](https://github.com/droidconKE/chai/blob/master/docs/architecture.md) - The architecture of the project -3. [Chai Design System Architecture](https://github.com/droidconKE/chai/blob/master/docs/chaiArchitecture.md) - The architecture of the design system -4. [buildlogic](https://github.com/droidconKE/chai/blob/master/docs/buildlogic.md) - Handles how we build the app with gradle, ditches the build src in favour of convention plugins. -5. [chaiLinter](https://github.com/droidconKE/chai/blob/master/docs/chaiLinter.md) - Explains the design system linter -6. [Atoms](https://github.com/droidconKE/chai/blob/master/docs/atoms.md) - Explains the atoms in the design system -7. [Components](https://github.com/droidconKE/chai/blob/master/docs/components.md) - Design system components -8. [Versioning](https://github.com/droidconKE/chai/blob/master/docs/versioning.md) - Semantic Versioning scheme and the release flow +1. [Why Design Systems](./docs/whyDesignSystems.md) - Explains the need for a design system in the context of compose. +2. [Architecture](./docs/architecture.md) - The architecture of the project +3. [Chai Design System Architecture](./docs/chaiArchitecture.md) - The architecture of the design system +4. [buildlogic](./docs/buildlogic.md) - Handles how we build the app with gradle, ditches the build src in favour of convention plugins. +5. [chaiLinter](./docs/chaiLinter.md) - Explains the design system linter +6. [Atoms](./docs/atoms.md) - Explains the atoms in the design system +7. [Components](./docs/components.md) - Design system components +8. [Versioning](./docs/versioning.md) - Semantic Versioning scheme and the release flow ## Implementing Chai From b0844995d914d28b999db5708c44f32edb3a8192 Mon Sep 17 00:00:00 2001 From: "./root" Date: Sat, 20 Jun 2026 04:22:39 +0200 Subject: [PATCH 4/8] Indexed automated workflow doc in README --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 1a38472..4d94af0 100755 --- a/README.md +++ b/README.md @@ -36,6 +36,7 @@ The Chai Design System Project Architecture is captured in detail: 6. [Atoms](./docs/atoms.md) - Explains the atoms in the design system 7. [Components](./docs/components.md) - Design system components 8. [Versioning](./docs/versioning.md) - Semantic Versioning scheme and the release flow +9. [Automated Workflow](./docs/automatedWorkflow.md) - How RenovateBot groups and raises dependency-update PRs ## Implementing Chai From 156dc9bdc16d4f56d1f9cca55e3ced760507a86a Mon Sep 17 00:00:00 2001 From: "./root" Date: Sat, 20 Jun 2026 07:40:55 +0200 Subject: [PATCH 5/8] Added CI guards job for agent tooling and design system --- .github/workflows/main.yml | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 1783cad..20c2ffc 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -23,6 +23,20 @@ jobs: with: access_token: ${{ github.token }} + guards: + name: Guards (agent tooling & design system) + permissions: + contents: read + runs-on: ubuntu-latest + needs: cancel-previous + steps: + - name: Checkout + uses: actions/checkout@v5 + - name: Agent-tooling lint + run: ./scripts/check-agent-tooling.sh + - name: Design-system usage guard + run: ./scripts/check-design-system-usage.sh + lint: name: Lint permissions: From f76fb09a3d2232b3bb21f735ba198b43ab4ddceb Mon Sep 17 00:00:00 2001 From: "./root" Date: Sat, 20 Jun 2026 07:41:11 +0200 Subject: [PATCH 6/8] Added per-tool agent instruction pointers --- .cursor/rules/chai.mdc | 19 +++++++++++++++++++ .github/copilot-instructions.md | 17 +++++++++++++++++ CLAUDE.md | 7 +++++++ GEMINI.md | 6 ++++++ 4 files changed, 49 insertions(+) create mode 100644 .cursor/rules/chai.mdc create mode 100644 .github/copilot-instructions.md create mode 100644 CLAUDE.md create mode 100644 GEMINI.md diff --git a/.cursor/rules/chai.mdc b/.cursor/rules/chai.mdc new file mode 100644 index 0000000..4cec881 --- /dev/null +++ b/.cursor/rules/chai.mdc @@ -0,0 +1,19 @@ +--- +description: Chai repo agent guidance — points to AGENTS.md +alwaysApply: true +--- + +The full, tool-neutral guidance for this repo lives in +[`AGENTS.md`](../../AGENTS.md) — read it for conventions, guard rails, and where +skills/agents/memory live. + +Non-negotiables (authoritative version in `AGENTS.md`): + +- **Design system only.** In `chai`/`chaidemo` source use Chai components and + tokens (`ChaiTheme`, `ChaiColors`, the `C*` components, `Space*`/`Spacer*`). + Never raw Material 3 components or hardcoded `Color(0x…)` / `.dp` literals. +- **Compose previews** use `@ChaiPreview`, not `@Preview`. +- **Branches** target `develop`, not `main`. Prefixes: `feature/`, `fix/`, `docs/`. +- **Commits**: past tense, concise subject, no period, no body, no + conventional-commits prefix. +- **Never** `git push --no-verify` or `--force`. Fix hook failures instead. diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..6fbabb8 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,17 @@ +# Copilot instructions + +GitHub Copilot reads this file automatically. The full, tool-neutral guidance +for this repo lives in [`AGENTS.md`](../AGENTS.md) — read it for conventions, +guard rails, and where skills/agents/memory live. + +The non-negotiables, repeated here because Copilot does not follow links +(see `AGENTS.md` for the authoritative version): + +- **Design system only.** In `chai`/`chaidemo` source use Chai components and + tokens (`ChaiTheme`, `ChaiColors`, the `C*` components, `Space*`/`Spacer*`). + Never raw Material 3 components or hardcoded `Color(0x…)` / `.dp` literals. +- **Compose previews** use `@ChaiPreview`, not `@Preview`. +- **Branches** target `develop`, not `main`. Prefixes: `feature/`, `fix/`, `docs/`. +- **Commits**: past tense, concise subject, no period, no body, no + conventional-commits prefix. ("Added X", not "feat: add x.") +- **Never** `git push --no-verify` or `--force`. Fix hook failures instead. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..18730f4 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,7 @@ +# CLAUDE.md + +Claude Code reads this file automatically. All agent guidance for the Chai repo +is kept in one tool-neutral place so every assistant shares the same rules. +Read it before any task: + +@AGENTS.md diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 0000000..97ed8c0 --- /dev/null +++ b/GEMINI.md @@ -0,0 +1,6 @@ +# GEMINI.md + +Gemini reads this file automatically. All agent guidance for the Chai repo is +kept in one tool-neutral place: [`AGENTS.md`](./AGENTS.md). Read it before any +task — it is the single source of truth for conventions, guard rails, and where +skills/agents/memory live. From 9d4684d2a98384c966726760e2ad15de8bedd0f2 Mon Sep 17 00:00:00 2001 From: "./root" Date: Sat, 20 Jun 2026 07:41:24 +0200 Subject: [PATCH 7/8] Added write-tests skill for unit tests --- .ai/skills/write-tests/SKILL.md | 67 +++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 .ai/skills/write-tests/SKILL.md diff --git a/.ai/skills/write-tests/SKILL.md b/.ai/skills/write-tests/SKILL.md new file mode 100644 index 0000000..ddfe729 --- /dev/null +++ b/.ai/skills/write-tests/SKILL.md @@ -0,0 +1,67 @@ +--- +name: write-tests +description: | + Write or extend tests for the Chai repo. Triggered by "write a test", + "add tests", "test this", or as the follow-up when a component/util lands + without coverage. Local unit tests use JUnit 6 (Jupiter); Compose/UI behaviour + is tested as instrumented tests. Picks the right source set and idioms; does + not invent mocking/assertion libraries the catalog does not declare. +--- + +# write-tests + +The repo's tests are still mostly generated scaffolds (see +`docs/tech/findings.md` → "Only scaffold tests exist"). This skill writes real +ones in the conventions already wired into the build. + +## What runs where + +| Kind | Source set | Framework | Run with | +|------|-----------|-----------|----------| +| Pure logic, no Android/Compose runtime | `src/test/java` | JUnit 6 (Jupiter), `useJUnitPlatform()` | `./gradlew ::testDebugUnitTest` | +| Composable rendering / interaction | `src/androidTest/java` | `androidx.compose.ui:ui-test-junit4` + `androidx.test.ext:junit` | `./gradlew ::connectedDebugAndroidTest` (needs a device/emulator) | + +Catalog references (`gradle/libs.versions.toml`): `junit-bom`, +`junit-jupiter`, `junit-platform-launcher` for unit tests; +`androidx-ui-test-junit4`, `androidx-ui-test-manifest`, `androidx-junit`, +`androidx-espresso-core` for instrumented. + +## Rules + +- **Use Jupiter, not JUnit 4, for unit tests.** Import `org.junit.jupiter.api.Test` + and `org.junit.jupiter.api.Assertions.*` (or `assertEquals`/`assertTrue` from + Jupiter). Do not import `org.junit.Test` or `org.junit.Assert` in `src/test`. +- **No new test libraries.** The catalog declares no MockK, Truth, Turbine, or + coroutines-test. Do not add them as part of writing a test — if a test truly + needs one, raise it as a separate dependency change (see the `dependency-bump` + skill) rather than slipping it in here. +- **Compose tests** go in `src/androidTest`, use `createComposeRule()` / + `createAndroidComposeRule<…>()`, and wrap content in `ChaiTheme { }` so tokens + resolve the same way they do in the app. +- **Design system still applies in test content.** When a test renders sample + UI, use Chai components/tokens, not raw Material — the same guard rail + (`scripts/check-design-system-usage.sh`) covers test sources. +- Replace generated `ExampleUnitTest` / `ExampleInstrumentedTest` stubs when you + add the first real test for a module; do not leave the `2 + 2 == 4` scaffold + next to real coverage. + +## Procedure + +1. Find what is untested. Pick the smallest meaningful unit (a util, a mapper, a + component's documented behaviour). +2. Choose the source set from the table above. Pure Kotlin → `src/test`. + Anything that composes → `src/androidTest`. +3. Name the file `Test.kt` in the matching package under that source + set. One behaviour per `@Test`; name tests for the behaviour, not the method. +4. Run the matching gradle task (use the `check-build` / `checks` skills if the + module fails to compile first). +5. Report: file added, what it covers, and the run result. + +## Report + +``` +write-tests ✓ : added test(s) in (testDebugUnitTest passed) +``` + +If instrumented tests were written but no device was available to run them, say +so explicitly — do not claim they passed. From b6aea623c58d1e8352f9998d15206f7b484c1564 Mon Sep 17 00:00:00 2001 From: "./root" Date: Sun, 21 Jun 2026 18:22:31 +0200 Subject: [PATCH 8/8] Added VS Code Java null-analysis setting --- .vscode/settings.json | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 .vscode/settings.json diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..7b016a8 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,3 @@ +{ + "java.compile.nullAnalysis.mode": "automatic" +} \ No newline at end of file