Release Candidate 2026-07-09 20:09:51 +0900

.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 }}

.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

.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#<anchor>` 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).

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",

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';
+}

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
 

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

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:
 

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 — <https://go.dev/wiki/CodeReviewComments>
+* Effective Go — <https://go.dev/doc/effective_go>
+* Go: Defer, Panic, and Recover — <https://go.dev/blog/defer-panic-and-recover>
+* Go Wiki: PanicAndRecover — <https://go.dev/wiki/PanicAndRecover>
+* Uber Go Style Guide — <https://github.com/uber-go/guide/blob/master/style.md>