Add planning baseline: BC, SA, PP and two gateways

Create the Business Case, Stakeholder Analysis (S01 course participant, S02 Udemy coursists, S03 GitHub viewers), Project Plan and the milestone documents MIL-001 (project setup, 6 tasks) and MIL-002 (game implementation, 8 tasks) for the console Blackjack game. Register PP and MIL in the artifact registry, set the PO language to en, and link the synced Gitea milestones in the Gateway Schedule. Refs #1 Refs #2 Refs #3 Refs #4 Refs #5 Refs #6 Refs #7 Refs #8 Refs #9 Refs #10 Refs #11 Refs #12 Refs #13 Refs #14
2026-10-04 21:38:09 +08:00
parent 52febca25e
commit 1d35410b8d
123 changed files with 5978 additions and 0 deletions
@@ -0,0 +1,71 @@
+# C conventions
+
+C has no single official style guide. This sub-skill fixes one consistent
+style built on common practice; MISRA C and SEI CERT C are the references for
+safety-critical or security-sensitive code.
+
+## Standard base
+
+ISO C11 or C17 as set by the project's compiler flag (`-std=c11`). Compile
+with warnings on (`-Wall -Wextra -Wpedantic`); treat warnings as errors in
+release builds.
+
+## Naming
+
+| Element | Convention | Example |
+| --- | --- | --- |
+| Function, variable, parameter | `snake_case` | `parse_header`, `byte_count` |
+| Public symbol | module prefix plus `snake_case` (C has no namespaces) | `stay_reader_open()` |
+| File-local function / variable | `static`, no prefix needed | `static int next_token(...)` |
+| Type (`struct`, `enum`, `typedef`) | `snake_case_t`, module prefix for public types | `stay_reader_t` |
+| Enum constant, macro, constant | `UPPER_SNAKE` with the module prefix | `STAY_READER_OK` |
+| Header / source file | `snake_case.h` / `snake_case.c`, same base name | `stay_reader.h` |
+| Header guard | `MODULE_FILE_H` (or `#pragma once` if the project allows) | `STAY_READER_H` |
+
+- Do not use reserved identifiers: a leading underscore followed by an
+  uppercase letter, any double underscore, or a leading underscore at file
+  scope.
+- POSIX reserves the `_t` suffix; keep the module prefix on public types so
+  they cannot collide.
+- Macros are a last resort; prefer `static inline` functions and `enum` or
+  `const` values.
+
+## Formatting
+
+- One formatter configuration for the project (`clang-format`); 4 spaces (or
+  the project's setting), no tabs mixed in.
+- Braces on every `if`, `else`, `for`, `while`, even for one statement.
+- One declaration per line; declare variables at first use, initialised.
+- Headers: include what you use, only what you use; public headers are
+  self-contained; add `extern "C"` guards when C++ code consumes them.
+
+## Language rules
+
+- Check every return value that can fail; check every allocation.
+- Every `malloc`/`open`/`lock` has one clear owner and one matching release;
+  release on every exit path (single exit or `goto cleanup`).
+- Use `size_t` for sizes and indices, fixed-width types (`<stdint.h>`) for
+  data layout, `const` wherever data is not modified, `restrict` only with
+  care.
+- Bounds are explicit: pass a length with every buffer; use `snprintf`,
+  never `sprintf`, `strcpy` or `gets`.
+- No undefined behaviour: no signed overflow, no out-of-range shifts, no use
+  after free, no uninitialised reads.
+- Avoid global mutable state; if unavoidable, `static` and documented.
+
+## Errors
+
+Return a status code (an `enum`) or `-1`/`NULL` plus an error out-parameter;
+document which in the header. Never ignore a failing call. Read `errno`
+immediately after the failing call.
+
+## Tests
+
+A unit-test framework (for example Unity or CMocka); run under sanitizers
+(`-fsanitize=address,undefined`) in at least one build.
+
+## Tooling
+
+`clang-format`, `clang-tidy` or `cppcheck`, compiler warnings, sanitizers.
+
+Review with `QC-CL-001`.