diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 6543e28..1ffdde9 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -31,22 +31,24 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@v4 + uses: actions/checkout@v7 with: fetch-depth: 0 # Not needed if lastUpdated is not enabled + - name: Set up pnpm + uses: pnpm/action-setup@v6 - name: Setup Node - uses: actions/setup-node@v4 + uses: actions/setup-node@v6 with: - node-version: 20 - cache: npm + node-version: 24 + cache: pnpm - name: Setup Pages - uses: actions/configure-pages@v4 + uses: actions/configure-pages@v6 - name: Install dependencies - run: npm ci + run: pnpm install --frozen-lockfile - name: Build with VitePress - run: npm run docs:build + run: pnpm run docs:build - name: Upload artifact - uses: actions/upload-pages-artifact@v3 + uses: actions/upload-pages-artifact@v5 with: path: doc/.vitepress/dist @@ -61,7 +63,7 @@ jobs: steps: - name: Deploy to GitHub Pages id: deployment - uses: actions/deploy-pages@v4 + uses: actions/deploy-pages@v5 publish-release-note: name: Publish release note @@ -74,7 +76,7 @@ jobs: steps: - name: Generate CalVer version id: calver - uses: actions/github-script@v6 + uses: actions/github-script@v9 with: script: | const now = new Date(); @@ -104,7 +106,7 @@ jobs: core.setOutput('version', version); core.setOutput('release_note_name', releaseNoteName); - - uses: release-drafter/release-drafter@v5 + - uses: release-drafter/release-drafter@v7 with: config-name: ./release-drafter-config.yml tag: ${{ steps.calver.outputs.version }} diff --git a/.github/workflows/run-tests.yml b/.github/workflows/run-tests.yml index 620f754..772538b 100644 --- a/.github/workflows/run-tests.yml +++ b/.github/workflows/run-tests.yml @@ -20,11 +20,11 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v7 with: ref: ${{ github.event.pull_request.head.sha }} token: ${{ secrets.GITHUB_TOKEN }} - - uses: actions/github-script@v6 + - uses: actions/github-script@v9 name: Set 'ci-testing' label if: github.event.action == 'review_requested' with: @@ -35,12 +35,14 @@ jobs: repo: context.repo.repo, labels: ["ci-testing"] }) + - name: Set up pnpm + uses: pnpm/action-setup@v6 - name: Set up Node.js - uses: actions/setup-node@v4 + uses: actions/setup-node@v6 with: - node-version: 20 - cache: npm + node-version: 24 + cache: pnpm - name: Install dependencies - run: npm ci + run: pnpm install --frozen-lockfile - name: Build (no tests) - run: npm run docs:build + run: pnpm run docs:build diff --git a/.workaholic/tickets/archive/coding-convention/rewrite-style-guide-wording-and-examples.md b/.workaholic/tickets/archive/coding-convention/rewrite-style-guide-wording-and-examples.md new file mode 100644 index 0000000..f43961d --- /dev/null +++ b/.workaholic/tickets/archive/coding-convention/rewrite-style-guide-wording-and-examples.md @@ -0,0 +1,126 @@ +--- +title: Rewrite the Style Guide pages โ€” wording, grammar, consistency, worked examples +layer: Documentation +mission: null +depends_on: [] +status: archived +created: 2026-07-09 +branch: coding-convention +pr: 73 +--- + +# Rewrite the Style Guide pages โ€” wording, grammar, consistency, worked examples + +## Summary + +Editorial rewrite of the four Style Guide pages so they read cleanly and +consistently, and so the per-language pages teach with worked examples in the +manner of the Google / Airbnb / GitLab guides. This is a copy-edit and +presentation pass โ€” **not** a policy change: every rule's substance, RFC-2119 +level, and ๐ŸŒŽ/๐Ÿ  tag is preserved. + +"Reference GitLab / Google / Airbnb" here means emulate their **grammar and +document style** (writing quality, formatting conventions, and Google-style +bad/good code examples). It does **not** mean adding new citations to those +guides or importing their content. + +## Scope + +In scope: +- Fix wording, grammar, and clarity; normalize to **American English** spelling + (behavior, modeled, organize โ€” currently mixed with British forms). +- Enforce one-concept-one-word terminology across all four pages (e.g. settle on + a single term chain for domain-layer code โ€” "project code" / "own types" / + "the core" / "the pure core" are used near-synonymously; likewise + "boundary" / "edge" / "adapter", and "Result (Either)" / "Result" / "error + channel"). +- Reconcile the ยง1 core framing contradiction ("Eliminating runtime errors is + the goal every rule below serves" vs "literal zero runtime errors is + impossible"). +- Structural consistency across the four pages: every section heading carries + exactly one ๐ŸŒŽ/๐Ÿ  tag (fix Go ยง4 "Interfaces" โ€” currently untagged and with no + Rationale); every ๐Ÿ  section ends with a *Rationale:* line that names the + mainstream baseline it diverges from; normalize section names (Python + "Formatting & Linting" vs siblings' "Formatting"). +- Add Google-style **bad/good** (โŒ / โœ…) worked examples to the per-language + pages for the highest-value rules (at least TypeScript Total Types, Result + error handling, no-classes; Go errors-as-values / panic; Python EAFP vs + return-values). +- Add a short "How to read this guide" convention note (GitLab-handbook style) + in the core page explaining the RFC-2119 levels, the ๐ŸŒŽ/๐Ÿ  tags, and the + bad/good example format โ€” once, single-sourced. + +Out of scope: +- No new citations or reference entries (do not add GitLab or others to + References; existing References stay for ๐ŸŒŽ/๐Ÿ  provenance). +- No change to any rule's substance, RFC-2119 level, or ๐ŸŒŽ/๐Ÿ  classification. +- No file/slug/H1 renames; no sidebar restructure. + +## Key Files + +- `doc/style-guide.md` โ€” language-agnostic hub; sets the RFC-2119 legend, ๐ŸŒŽ/๐Ÿ  + definitions, Rationale-line convention. Primary template the others mirror. +- `doc/style-guide-typescript.md` โ€” already names Google/Airbnb as divergence + baselines; natural anchor for bad/good examples. +- `doc/style-guide-golang.md` โ€” has the untagged "Interfaces" section to fix. +- `doc/style-guide-python.md` โ€” section naming diverges from siblings. +- `doc/.vitepress/config.mts` โ€” do **not** touch unless a title/slug changes + (not planned). The four `/style-guide*` routes + H1s are wired here. +- `doc/technical-glossary.md` โ€” only if a new **bold-link** term is introduced + (add a matching heading, or the build flags a dead anchor). + +## Related History + +- PR #73 (branch `coding-convention`) contains the guides; the rewrite lands on + this branch/PR. Commits: `8803297` (Add Coding Style Guide), `9e8c3ee` + (rename to Style Guide + nest), `25bae56` (original). +- No prior ticket or overlapping work (moderation: clear). + +## Implementation Steps + +1. Read all four pages together; build a terminology map and pick the canonical + term for each concept cluster. Apply consistently across all four in the same + change (terminology policy: update all affected areas together). +2. Copy-edit each page for grammar/clarity; normalize to US English spelling. +3. Fix the ยง1 framing contradiction in the core page. +4. Tag every section (fix Go "Interfaces"); ensure every ๐Ÿ  section has a + *Rationale:* naming its baseline; align section names across pages. +5. Add the "How to read this guide" note to the core page. +6. Add โŒ/โœ… bad-then-good examples to the per-language pages for the listed + high-value rules; keep them minimal and correct. +7. Preserve every glossary **bold-link** (14 anchors), the four slugs/H1s, and + the [[TOC]] + single-sourced RFC-2119 legend. +8. `pnpm docs:build` and confirm no dead-link / build errors. + +## Considerations + +- **Objective documentation** (ๅฎŸ่ฃ… pillar): keep language factual and + verifiable; do not introduce evaluative adjectives (elegant, powerful, simple) + or empty hedges (basically, essentially) while "improving wording." +- **One concept, one word** (ไผ็”ป pillar): do not add synonyms or notational + variants for terms already fixed in the Technical Glossary; reword sentences, + not the defined vocabulary. +- **Honest provenance**: the rewrite must not flip a rule's ๐ŸŒŽ/๐Ÿ  tag or + misstate what it diverges from; editorial polish only. +- **Load-bearing invariants**: 14 `/technical-glossary#` links (exact + spelling), the four `/style-guide*` slugs + H1s wired in `config.mts`, and the + core page's single RFC-2119 legend must all survive. + +## Quality Gate + +Both must hold before approval: + +1. **Build passes** โ€” `pnpm docs:build` completes with no dead-link or build + errors (this is the only automated check; VitePress fails the build on a + broken `/technical-glossary#anchor` or `/style-guide*` link). Confirms all 14 + glossary anchors and the four slugs/H1s still resolve. +2. **Named human review** โ€” a reviewer reads all four pages and confirms: + - grammar/wording is clean and consistent; spelling is uniformly US English; + - terminology is consistent (one word per concept, matching the glossary); + - every section is ๐ŸŒŽ/๐Ÿ -tagged and every ๐Ÿ  section has a Rationale line; + - bad/good examples are present for the listed high-value rules and are + correct; + - **no rule's substance, RFC-2119 level, or ๐ŸŒŽ/๐Ÿ  tag changed** (diff read + against the pre-rewrite version to confirm editorial-only). + +Reviewer: to be assigned on the PR (mention on PR #73). diff --git a/doc/.vitepress/config.mts b/doc/.vitepress/config.mts index 3b3b155..7e1d1d1 100644 --- a/doc/.vitepress/config.mts +++ b/doc/.vitepress/config.mts @@ -59,7 +59,24 @@ export default defineConfig({ text: "Guideline", items: [ { text: "On-boarding Guide", link: "/on-boarding" }, - { text: "Development Guide", link: "/development-guide" }, + { + text: "Development Guide", + link: "/development-guide", + collapsed: false, + items: [ + { + text: "Style Guide", + link: "/style-guide", + collapsed: true, + items: [ + { text: "TypeScript", link: "/style-guide-typescript" }, + { text: "Golang", link: "/style-guide-golang" }, + { text: "Python", link: "/style-guide-python" }, + { text: "HTML & CSS", link: "/style-guide-html-css" }, + ], + }, + ], + }, { text: "Non-functional Requirements", link: "/predefining-non-functional-requirements", diff --git a/doc/.vitepress/theme/font.css b/doc/.vitepress/theme/font.css index d9bae5b..90448fe 100644 --- a/doc/.vitepress/theme/font.css +++ b/doc/.vitepress/theme/font.css @@ -1,5 +1,5 @@ @import url('https://fonts.googleapis.com/css2?family=Montserrat:ital,wght@0,100..900;1,100..900&display=swap'); -:root{ - --vp-font-family-base: 'Montserrat' -}; +:root { + --vp-font-family-base: 'Montserrat'; +} diff --git a/doc/development-guide.md b/doc/development-guide.md index b88452b..a5becbf 100644 --- a/doc/development-guide.md +++ b/doc/development-guide.md @@ -8,7 +8,7 @@ In this page, you will find the standard development policy and workflow in OSBR ### 1-1. Setup Your Machine -Following checklist is all mandatory by our security policy: +The following checklist is all mandatory by our security policy: * Use company-provided laptop or company-approved personal device. * Sleep mode activation within 5 minutes, mandatory reauthentication after sleep mode. @@ -148,8 +148,8 @@ The following GitHub Actions are pre-configured in each repository. | --- | ---- | ----------- | | 1 | `start-pull-request` | Create a pull request by assigning a developer to the issue. | | 2 | `prepare-release` | Prepare a release pull request merging main to release. | -| 3 | `run-tests` | Skelton action which is supposed to run tests. | -| 4 | `release` | Skelton action which is supposed to deploy and publish release note. | +| 3 | `run-tests` | Skeleton action which is supposed to run tests. | +| 4 | `release` | Skeleton action which is supposed to deploy and publish release note. | #### Status diff --git a/doc/on-boarding.md b/doc/on-boarding.md index cbc8e29..0ed0dd0 100644 --- a/doc/on-boarding.md +++ b/doc/on-boarding.md @@ -85,7 +85,7 @@ To subscribe to a holiday calendar on macOS: 4. And follow the prompts to name the calendar, choose an account, and set update frequency. ::: info NOTE -You can use your preffered calendar app such as Google Calendar. +You can use your preferred calendar app such as Google Calendar. ::: ## 2. First Week diff --git a/doc/predefining-non-functional-requirements.md b/doc/predefining-non-functional-requirements.md index f5d5e9c..1518f24 100644 --- a/doc/predefining-non-functional-requirements.md +++ b/doc/predefining-non-functional-requirements.md @@ -1,6 +1,6 @@ # Non-functional Requirements -In the development process, it is necessary to define non-functional and functional requirements. Functional requirements are deep rooted in the specific things that a system needs to be able to do. What about non-functional requirements? (NFRs) +In the development process, it is necessary to define non-functional and functional requirements. Functional requirements are deep-rooted in the specific things that a system needs to be able to do. What about non-functional requirements? (NFRs) [[TOC]] @@ -81,7 +81,7 @@ Focuses on how well the system can handle growth. ### 2-7. Compliance -The system should adheres to laws, regulations, and industry standards. +The system should adhere to laws, regulations, and industry standards. #### Examples: diff --git a/doc/style-guide-golang.md b/doc/style-guide-golang.md new file mode 100644 index 0000000..d5bc2c6 --- /dev/null +++ b/doc/style-guide-golang.md @@ -0,0 +1,82 @@ +# Golang Style Guide + +Per-language style guide for Go. Shared rules: the +[Coding Style Guide](/style-guide). Requirement levels follow +RFC 2119; tags ๐ŸŒŽ / ๐Ÿ  are defined there. + +[[TOC]] + +## 1. Formatting ๐ŸŒŽ + +* Code MUST be formatted with `gofmt`. A `gofmt` diff MUST block review. +* Code MUST follow [Effective Go](https://go.dev/doc/effective_go) and + [Go Code Review Comments](https://go.dev/wiki/CodeReviewComments). + +## 2. Error Handling ๐ŸŒŽ + +* Functions MUST return `error`; callers MUST handle it at the call site: + + ```go + v, err := doThing() + if err != nil { + return fmt.Errorf("doThing: %w", err) + } + ``` + +* Errors MUST be wrapped with `%w` to add context. Errors MUST NOT be discarded + with `_`. +* `panic` MUST NOT be used for normal error handling. +* `panic` MAY be used for unrecoverable bugs or program init, but MUST NOT cross + a package boundary โ€” convert it to an `error` first. + +โŒ `panic` used for an expected failure crashes the caller: + +```go +func mustLoad(id string) User { + u, err := db.Load(id) + if err != nil { + panic(err) + } + return u +} +``` + +โœ… The failure is returned as an `error` the caller must handle: + +```go +func load(id string) (User, error) { + u, err := db.Load(id) + if err != nil { + return User{}, fmt.Errorf("load %s: %w", id, err) + } + return u, nil +} +``` + +*Rationale: errors-as-values is mandated by Go (Go Code Review Comments, Uber, +Effective Go). Go's `error` return is the idiomatic +[**Result (Either)**](/technical-glossary#result-either).* + +## 3. Mutation ๐ŸŒŽ *(scoped)* + +* Mutable global state MUST be avoided; use dependency injection. +* Slices and maps MUST be copied at API boundaries to avoid aliasing. + +*Note: Go idiom permits local mutation; the constraint is on globals and +boundary aliasing.* + +## 4. Interfaces ๐ŸŒŽ + +* Interfaces SHOULD be small and defined by the consumer. An interface with a + single implementation MUST NOT be exported. + +*Note: Go idiom is "accept interfaces, return structs" with consumer-defined +interfaces (Go Code Review Comments, Effective Go).* + +## References + +* Go Code Review Comments โ€” +* Effective Go โ€” +* Go: Defer, Panic, and Recover โ€” +* Go Wiki: PanicAndRecover โ€” +* Uber Go Style Guide โ€” diff --git a/doc/style-guide-html-css.md b/doc/style-guide-html-css.md new file mode 100644 index 0000000..e52019b --- /dev/null +++ b/doc/style-guide-html-css.md @@ -0,0 +1,349 @@ +# HTML & CSS Style Guide + +Per-language style guide for HTML and CSS. Shared rules: the +[Coding Style Guide](/style-guide). Requirement levels follow +RFC 2119; tags ๐ŸŒŽ / ๐Ÿ  are defined there. + +[[TOC]] + +## 1. Formatting ๐ŸŒŽ + +* HTML and CSS MUST be formatted with Prettier. Editors MUST format on save. +* Prettier's shared [`.prettierrc.json`](https://github.com/osbrjp/handbook/tree/main/templates) + applies unchanged: Prettier formats `.html`, `.css`, `.scss`, and `.less` out + of the box, so no extra config is needed. + +*Note: Prettier is the single formatter across TypeScript, Markdown, HTML, and +CSS. Stylelint MAY be added for lint rules Prettier does not cover (e.g. +declaration order, disallowed units), but MUST NOT re-implement formatting.* + +*Note: Prettier is mandated because its HTML formatter is the only stable one. +[Biome](https://biomejs.dev/) (CSS stable, HTML still experimental) and +[oxfmt](https://oxc.rs/docs/guide/usage/formatter.html) (beta, ~30ร— faster) are +Prettier-compatible alternatives to revisit once their HTML support stabilizes. +A toolchain-wide switch MUST be an [**ADR**](/technical-glossary#adr-architecture-decision-record), +not a per-page choice.* + +## 2. Semantic HTML ๐ŸŒŽ + +* Elements MUST be chosen for meaning, not appearance. Landmarks + (`
`, `