@aliaksandarpratashchyk/kickcat 0.5.8 → 0.6.0

package/README.md

@@ -6,6 +6,8 @@
 
 KickCat keeps GitHub metadata (milestones, labels, issues) as YAML and syncs it with a GitHub repository or a file-based store. It preserves schema-driven ordering and hash comments so you can review changes as code.
 
+- Documentation: [KickCat Codex](./codex/index.md)
+
 ## What it does
 
 - Manage milestones, labels, and issues as YAML with `$schema` + `hash` comments.

package/codex/index.md

@@ -0,0 +1,11 @@
+# KickCat Codex
+
+This document is the *preferred* KickCat user manual.
+
+It states a set of rules and recommendations, which aren't necessarily required for KickCat's stability, but ***CAN*** be adopted to ensure uniformity of all GitHub entities.
+
+It is composed of several manuals, each for its corresponding GitHub entity:
+
+- ["Label Design Manual"](./label.md)
+- ["Milestone Design Manual"](./milestone.md)
+- ["Issue Design Manual"](./issue.md)

package/codex/issue.md

@@ -0,0 +1,76 @@
+## Issue Design Manual
+
+This document is a formal GitHub **issue** design manual.
+
+It states a set of rules and recommendations, which are expected to be followed by all project participants when adding a new **issue** to ensure uniformity of all **issues**.
+
+**1.** All **issues** ***SHOULD*** be stored in the `.github/issues.yml` YAML file.
+
+**2.** `.github/issues.yml` is a multi-document YAML file described by [issue.schema.yml](../schemas/issue.schema.yml).
+
+**3.** Each document inside the multi-document YAML file `.github/issues.yml` ***MUST*** start with a reference to its schema using special YAML comment syntax:
+
+```yml
+# yaml-language-server: $schema=RELATIVE_PATH_TO_SCHEMA
+```
+
+`RELATIVE_PATH_TO_SCHEMA` is the relative path to the corresponding schema inside the `node_modules` folder.
+
+For instance: if `node_modules` is on the same level as `.github`, then `../node_modules/@aliaksandarpratashchyk/kickcat/schemas/issue.schema.yml` is the relative path to the issue schema.
+
+**4.** All YAML documents in `.github/issues.yml` are divided into two categories: already synchronized with GitHub and new ones.
+
+Already synchronized documents have a special YAML `hash` comment immediately after the `yaml-language-server` schema comment. This `hash` comment ***CANNOT*** be edited manually; KickCat manages it automatically.
+
+**5.** [issue.schema.yml](../schemas/issue.schema.yml) uses an extended JSON Schema format that can define the **order** of properties inside YAML documents. All YAML documents ***MUST*** follow the property order specified by their schema.
+
+**6.** The **issue** `number` is assigned automatically by GitHub during synchronization stage and ***MUST NOT*** be edited manually.
+
+**7.** The **issue** `title` ***SHOULD*** follow a semantic commit style, with an optional scope for monorepos.
+
+If an **issue** is epic and effectively equivalent to a **milestone**, the **issue** `title` ***SHOULD*** use the same icon prefix as the **milestone**.
+
+For instance: `🚀 feat: setup project and scaffold raw implementation` for **milestone** `🚀 v1.0.0 - Project Setup & Raw Implementation`.
+
+**8.** The **issue** `milestone` property ***MUST*** reference the associated milestone, if an **issue** has one.
+
+It can be either:
+
+- **Milestone** `number`, if the **milestone** is already synchronized with GitHub and has a `number`.
+- **Milestone** `title`, if the **milestone** is new and does not yet have a `number`. The KickCat utility will replace it with `number` during synchronization.
+
+**9.** The **issue** `labels` property is a list of **labels** associated with the **issue**. Label `name` is used as the **label** identifier.
+
+**10.** The **issue** `state` property is either `open` or `closed`. For a new **issue**, it ***CAN*** be omitted.
+
+**11.** The **issue** `dependencies` property is a list of **issues** that this **issue** depends on. These **issues** ***MUST*** be closed before this **issue** can be closed. As issue identifiers in this list, either:
+
+- **Issue** `number` ***MUST*** be used if the **issue** is already synchronized with GitHub.
+- **Issue** `title` ***MUST*** be used if the **issue** is new and does not yet have a `number`.
+
+**12.** The issue `description` property is multi-line Markdown text with this structure:
+
+- Start with a short introduction of the **issue**.
+- Follow with a `Goal` section where the purpose of the **issue** is clearly stated. Visually, this section ***SHOULD*** be marked with the `## 🎯 Goal` header.
+- Follow with an optional `Subtasks` section, used when the **issue** is large and can be split into subtasks. Visually, this section ***SHOULD*** be marked with the `## 🧩 Subtasks` header.
+- End with an `Outcomes` section that states expected results after the **issue** is closed. Visually, this section ***SHOULD*** be marked with the `## ✅ Outcomes` header.
+
+Below is an example description for **issue** `🚀 feat: setup project and scaffold raw implementation`:
+
+```markdown
+Set up the project tooling and scaffold the raw implementation of the project.
+
+## 🎯 Goal
+Ship a small but complete v1 foundation.
+
+## 🧩 Subtasks
+- Set up NPM project
+- Configure GitHub workflows
+- Implement initial course structure:
+  - Episode scripts
+  - Code snippets
+
+## ✅ Outcomes
+- Workflows are present
+- Structured raw implementation is added
+```

package/codex/label.md

@@ -0,0 +1,47 @@
+## Label Design Manual
+
+This document is a formal GitHub **label** design manual.
+
+It states a set of rules and recommendations, which are expected to be followed by all project participants when adding a new **label** to ensure uniformity of all **labels**.
+
+**1.** All **labels** ***SHOULD*** be stored in the `.github/labels.yml` YAML file.
+
+**2.** `.github/labels.yml` is a multi-document YAML file described by [label.schema.yml](../schemas/label.schema.yml).
+
+**3.** Each document inside the multi-document YAML file `.github/labels.yml` ***MUST*** start with a reference to its schema using special YAML comment syntax:
+
+```yml
+# yaml-language-server: $schema=RELATIVE_PATH_TO_SCHEMA
+```
+
+`RELATIVE_PATH_TO_SCHEMA` is the relative path to the corresponding schema inside the `node_modules` folder.
+
+For instance: if `node_modules` is on the same level as `.github`, then `../node_modules/@aliaksandarpratashchyk/kickcat/schemas/label.schema.yml` is the relative path to the label schema.
+
+**4.** All documents in `.github/labels.yml` are divided into two categories: already synchronized with GitHub and new ones.
+
+Already synchronized documents have a special YAML `hash` comment immediately after the `yaml-language-server` schema comment. This `hash` comment ***CANNOT*** be edited manually; KickCat manages it automatically.
+
+**5.** [label.schema.yml](../schemas/label.schema.yml) uses an extended JSON Schema format that defines the **order** of properties inside YAML documents. All YAML documents ***MUST*** follow the specified property order.
+
+**6.** The set of **labels** ***SHOULD*** be designed based on current repository or project needs, in an amount sufficient to describe current issues and the project specifics.
+
+For a typical coding project, examples include `priority:low`, `priority:medium`, `priority:high`, `type:feature`, and `type:bug`.
+
+For a monorepo, `scope` category **labels** can be added.
+
+For non-coding projects, such as writing-focused projects, `priority` **labels** can still be useful, but `type` **labels** ***SHOULD*** be designed according to project needs.
+
+**7.** The label `name` ***MUST*** start with a category prefix, separated with a colon `:` from the rest of the name. Typical category prefixes:
+
+- `priority` - used by **labels** that specify feature criticality or urgency, for example `priority:low` or `priority:high`.
+- `type` - used by **labels** that specify issue type, for example `type:feature` or `type:fix`.
+- `scope` - used in monorepos to specify a project or package.
+
+For instance, `scope:client` and `scope:server` can be used for a simple client-server application. In a single-project repository, `scope` **labels** ***SHOULD NOT*** be used.
+
+**8.** The **label** `color` ***SHOULD*** match the meaning of the label.
+
+For instance, `priority` labels can follow a traffic-light metaphor: red for `priority:high`, yellow for `priority:medium`, and green for `priority:low`.
+
+**9.** The **label** `description` ***SHOULD*** be short but clear enough to explain the label.

package/codex/milestone.md

@@ -0,0 +1,56 @@
+## Milestone Design Manual
+
+This document is a formal GitHub **milestone** design manual.
+
+It states a set of rules and recommendations, which are expected to be followed by all project participants when adding a new **milestone** to ensure uniformity of all **milestones**.
+
+**1.** All **milestones** ***SHOULD*** be stored in the `.github/milestones.yml` YAML file.
+
+**2.** `.github/milestones.yml` is a multi-document YAML file described by [milestone.schema.yml](../schemas/milestone.schema.yml).
+
+**3.** Each document inside the multi-document YAML file `.github/milestones.yml` ***MUST*** start with a reference to its schema using special YAML comment syntax:
+
+```yml
+# yaml-language-server: $schema=RELATIVE_PATH_TO_SCHEMA
+```
+
+`RELATIVE_PATH_TO_SCHEMA` is the relative path to the corresponding schema inside the `node_modules` folder.
+
+For instance: if `node_modules` is on the same level as `.github`, then `../node_modules/@aliaksandarpratashchyk/kickcat/schemas/milestone.schema.yml` is the relative path to the milestone schema.
+
+**4.** All documents in `.github/milestones.yml` are divided into two categories: already synchronized with GitHub and new ones.
+
+Already synchronized documents have a special YAML `hash` comment immediately after the `yaml-language-server` schema comment. This `hash` comment ***CANNOT*** be edited manually; KickCat manages it automatically.
+
+**5.** [milestone.schema.yml](../schemas/milestone.schema.yml) uses an extended JSON Schema format that can define the **order** of properties inside YAML documents. All YAML documents ***MUST*** follow the property order specified by their schema.
+
+**6.** The **milestone** `number` is assigned automatically by GitHub during synchronization stage and ***MUST NOT*** be edited manually.
+
+**7.** The **milestone** `title` ***SHOULD*** follow these conventions:
+
+- Start with a Unicode icon prefix that matches the title meaning.
+- Follow with a version number, such as `v1.0.0`, to reference the target version for implementation.
+- Follow with a title in Title Case.
+
+For example: `🚀 v1.0.0 - Project Setup & Raw Implementation`
+
+**8.** The **milestone** `description` is multi-line Markdown with this structure:
+
+- Start with a short introduction.
+- Follow with a `Goal` section that clearly and briefly states why the milestone exists. Visually, this section should start with the `### 🎯 Goal` header.
+- End with an `Outcomes` section that lists expected implementation outcomes. Visually, this section should start with the `### ✅ Outcomes` header.
+
+Below is an example description for **milestone** `🚀 v1.0.0 - Project Setup & Raw Implementation`:
+
+```markdown
+Initialize the repository structure and developer tooling for the project.
+
+Scaffold the first usable implementation.
+
+### 🎯 Goal
+Establish a foundation for further improvements.
+
+### ✅ Outcomes
+- Project scaffolded (README, workflows)
+- Raw implementation added
+```