diff options
| author | Bertrand Yuan <me@bertyuan.com> | 2026-04-27 20:52:54 +0800 |
|---|---|---|
| committer | Bertrand Yuan <me@bertyuan.com> | 2026-04-27 20:53:14 +0800 |
| commit | dbb5e791f0c228369605d126dd590962ebe1eddc (patch) | |
| tree | 8c83fc84bd9547630e6733929dec77e102e055a8 /Documentation/source/contributing | |
| parent | 658798b3a2378bb6df16cfbb16d707c6fb719e1e (diff) | |
docs: add comprehensive documentation for operations
This commit introduces a complete set of documentation files
covering various aspects of the project, including environment
setup, quality checks, command references, and architecture.
The documentation is structured to assist developers and
contributors in understanding the project's configuration,
workflow, and best practices.
Additionally, translations for Simplified and Traditional
Chinese have been added to ensure accessibility for a wider
audience. This enhances the overall usability and
maintainability of the project.
Signed-off-by: Bertrand Yuan <github@bertyuan.com>
Diffstat (limited to 'Documentation/source/contributing')
| -rw-r--r-- | Documentation/source/contributing/code-integrity.rst | 43 | ||||
| -rw-r--r-- | Documentation/source/contributing/commit-messages.rst | 85 | ||||
| -rw-r--r-- | Documentation/source/contributing/index.rst | 12 | ||||
| -rw-r--r-- | Documentation/source/contributing/workflow.rst | 42 |
4 files changed, 182 insertions, 0 deletions
diff --git a/Documentation/source/contributing/code-integrity.rst b/Documentation/source/contributing/code-integrity.rst new file mode 100644 index 0000000..7ead918 --- /dev/null +++ b/Documentation/source/contributing/code-integrity.rst @@ -0,0 +1,43 @@ +Code Integrity +============== + +This project should preserve a reviewable and trustworthy history. The raw +``docs/protecting-code-integrity.md`` note covers broader PGP background; this +page records repository-level expectations. + +Source Provenance +----------------- + +* Prefer signed commits and signed tags when publishing releases. +* Protect credentials and signing keys outside the repository. +* Do not commit generated secrets, local database state, or build output. +* Review dependency changes with the same care as source changes. + +Git Practices +------------- + +* Keep commits focused by subsystem or behavior. +* Avoid mixing generated files with hand-written changes unless the generated + files are required for the change. +* Use branches for non-trivial work. +* Rebase or merge deliberately; avoid history rewrites on shared branches + unless the team has agreed. + +Release Tags +------------ + +Release tags should be annotated and signed when possible: + +.. code-block:: bash + + git tag -s v1.2.0 -m "v1.2.0" + +Verification +------------ + +Before trusting a release or dependency bump, verify: + +* tag or commit signature when available; +* changelog and diff scope; +* dependency lockfile changes; +* CI result for the exact commit being released. diff --git a/Documentation/source/contributing/commit-messages.rst b/Documentation/source/contributing/commit-messages.rst new file mode 100644 index 0000000..22bda0d --- /dev/null +++ b/Documentation/source/contributing/commit-messages.rst @@ -0,0 +1,85 @@ +Commit Messages +=============== + +Commit messages should be structured enough to support readable history and +future changelog generation. + +Format +------ + +.. code-block:: text + + <type>(<scope>): <short summary> + + <body> + + <footer> + +The header is required. The body is recommended for all non-trivial changes and +should explain why the change exists. + +Types +----- + +.. list-table:: + :header-rows: 1 + :widths: 18 52 + + * - Type + - Use + * - ``build`` + - Build system or dependency changes. + * - ``ci`` + - CI configuration and automation. + * - ``docs`` + - Documentation-only changes. + * - ``feat`` + - New user-facing capability. + * - ``fix`` + - Bug fix. + * - ``perf`` + - Performance improvement. + * - ``refactor`` + - Code change that does not add behavior or fix a bug. + * - ``test`` + - Test additions or corrections. + +Scopes +------ + +Use a scope when it clarifies ownership. Recommended repository scopes: + +* ``app``; +* ``payload``; +* ``auth``; +* ``comments``; +* ``db``; +* ``ui``; +* ``email``; +* ``docs``; +* ``tooling``. + +Summary Rules +------------- + +* Use imperative present tense. +* Do not capitalize the first word unless it is a proper noun. +* Do not end the summary with a period. +* Keep the summary concise. + +Examples +-------- + +.. code-block:: text + + feat(comments): add moderation role checks + + fix(feed): keep rss canonical path consistent + + docs: add Sphinx architecture guide + +Reverts +------- + +Revert commits should start with ``revert:`` and include the SHA of the commit +being reverted in the body. diff --git a/Documentation/source/contributing/index.rst b/Documentation/source/contributing/index.rst new file mode 100644 index 0000000..0a2394d --- /dev/null +++ b/Documentation/source/contributing/index.rst @@ -0,0 +1,12 @@ +Contributing +============ + +This section describes contribution expectations for commits, review, and +source integrity. + +.. toctree:: + :maxdepth: 2 + + workflow + commit-messages + code-integrity diff --git a/Documentation/source/contributing/workflow.rst b/Documentation/source/contributing/workflow.rst new file mode 100644 index 0000000..8457cbd --- /dev/null +++ b/Documentation/source/contributing/workflow.rst @@ -0,0 +1,42 @@ +Workflow +======== + +Before Coding +------------- + +1. Identify which subsystem owns the change. +2. Read the nearest existing implementation and tests. +3. Decide whether the change affects runtime behavior, schema, UI, docs, or + operations. +4. Keep the patch scoped to the requested behavior. + +During Implementation +--------------------- + +* Follow local patterns before introducing new abstractions. +* Keep data fetching in server routes or ``src/lib`` helpers. +* Use existing UI primitives and tokens. +* Update tests when behavior changes. +* Update this documentation when a public contract, architecture, or workflow + changes. + +Before Submitting +----------------- + +Run the most relevant checks: + +.. code-block:: bash + + pnpm lint + pnpm test + make -C Documentation html + +For schema changes, include the appropriate migration and generated type +updates. + +Review Expectations +------------------- + +Reviews should prioritize correctness, behavior regressions, missing tests, +security-sensitive configuration, and unclear contracts. Style comments should +point to an existing repository convention or a maintainability issue. |