@arbor-education/design-system.components 0.24.0 → 0.24.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.24.1
+
+### Patch Changes
+
+- [#201](https://github.com/arbor-education/design-system.components/pull/201) [`96bdfeb`](https://github.com/arbor-education/design-system.components/commit/96bdfebc8dfb69e88ba0bede7102d6688e6d3ef0) Thanks [@angusmglfraser](https://github.com/angusmglfraser)! - FRENDS-90 📝 Update contributing guidelines to reflect current versioning conventions and notes on proper use of changesets
+
 ## 0.24.0
 
 ### Minor Changes

package/CONTRIBUTING.md

@@ -60,18 +60,18 @@ Format: `{JIRA-TICKET} {gitmoji} {Short, imperative description}`
 - Keep it under 72 characters
 
 **Common gitmoji:**
-| Emoji | Use for |
-|-------|---------|
-| ✨ | New feature |
-| 🐛 | Bug fix |
-| ♻️ | Refactor (no behaviour change) |
-| 💄 | Styling / visual change |
-| 🧪 | Tests only |
-| 📝 | Documentation |
-| ⬆️ | Dependency upgrade |
-| 🔧 | Config / tooling change |
-| 💥 | Breaking change |
-| ♿️ | Accessibility improvement |
+| Emoji | Use for                        |
+| ----- | ------------------------------ |
+| ✨     | New feature                    |
+| 🐛     | Bug fix                        |
+| ♻️     | Refactor (no behaviour change) |
+| 💄     | Styling / visual change        |
+| 🧪     | Tests only                     |
+| 📝     | Documentation                  |
+| ⬆️     | Dependency upgrade             |
+| 🔧     | Config / tooling change        |
+| 💥     | Breaking change                |
+| ♿️     | Accessibility improvement      |
 
 ### Description
 
@@ -130,24 +130,16 @@ Run through this checklist yourself before requesting review:
 ### Hard rules for agents
 
 1. **One PR per Jira ticket.** Never combine work from multiple tickets into a single PR, even if the work seems related.
-
 2. **Stop and check scope before starting.** Before writing any code, identify the minimal set of files required to complete the task. If you find yourself touching more than ~5 files or ~200 lines, pause and ask the human whether the task should be split.
-
 3. **Never bundle refactoring with feature work.** If you notice an opportunity to refactor while implementing a feature, stop. Create a note for the human. Do not refactor in the same PR unless explicitly instructed.
-
 4. **Never touch files outside the task scope.** Do not "improve" adjacent code, fix unrelated formatting, or clean up files you didn't need to open to complete the task.
-
 5. **Never open a PR with failing tests.** All tests must pass. `yarn test:coverage` must complete with 100% of tests passing.
-
 6. **Never open a PR with type errors.** `yarn check-types` must pass cleanly.
-
 7. **Write a complete PR description.** Use the template. Answer all four questions. Do not leave sections blank.
-
 8. **Warn before generating large changes.** If completing a task would require changes to more than 400 lines of meaningful code or more than 10 files, stop and tell the human before proceeding. Ask whether the task should be broken into smaller pieces.
-
-9. **Commit atomically.** Each commit should be a coherent, working unit. Do not commit broken intermediate states.
-
+9. **Commit atomically.** Each commit should be a coherent, working unit. Do not commit broken intermediate states, and avoid large commits with a broad scope where possible.
 10. **Ask, don't assume.** When the scope or approach is unclear, ask the human rather than making assumptions that lead to larger-than-expected changes.
+11. **Do not write changeset files yourself.** AI agents have a propensity to directly write their own changeset files, which often hallucinate the structure of the files, or the name of the changeset project, which can result in stray changeset files not being added to the changelog on releases. **All** changeset files **must** be generated by running `yarn changeset`.
 
 ---
 
@@ -183,6 +175,16 @@ See [CLAUDE.md](./CLAUDE.md) for the definitive reference. In summary:
 
 ---
 
+## A Note on Versioning
+
+Generally we use semantic versioning (https://semver.org/), however, we are reserving version 1.0.0 for the first wide release of this project. Therefore, in the mean time, we follow the following convention with regards to change levels:
+
+- Major version bumps are reserved for the first wide release
+- Minor version bumps are for breaking changes
+- Patch version bumps are for all other changes (including added functionality)
+
+---
+
 ## Resources
 
 - [gitmoji reference](https://gitmoji.dev/)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arbor-education/design-system.components",
-  "version": "0.24.0",
+  "version": "0.24.1",
   "description": "The component library for the design system (the baby)",
   "main": "dist/index.js",
   "type": "module",

package/src/docs/Contributing.mdx

@@ -205,6 +205,13 @@ Never push directly to `main` — all work goes through a branch and PR.
 - **Under 400 lines** of meaningful code change — if it's bigger, split it.
 - **Fill in the PR template** — every section, no placeholders.
 
+### Changesets
+
+- **Every PR requires a changeset.** These should be generated by running `yarn changeset`, which takes you through a prompt to specify the change level and to give a brief description of your change
+- **Do not let an AI create a changeset file for you.** AI Agents have a propensity to directly write their own changeset files, which often hallucinate the structure of the files, or the name of the changeset project, which can result in stray changeset files not being added to the changelog on releases. Generate **all** changeset files via `yarn changeset`.
+- **Do not use backticks or quotes in your changeset description** - these break the release automation
+- Until we are on v1.0.0 as our first wide release, we are not using proper semver. For the time being, use minor version bumps for breaking changes and patch for all other changes, including new functionality.
+
 For the full details and the reasoning behind these rules, see [CONTRIBUTING.md](https://github.com/arbor-education/design-system.components/blob/main/CONTRIBUTING.md) on GitHub.
 
 ---