From dbb5e791f0c228369605d126dd590962ebe1eddc Mon Sep 17 00:00:00 2001 From: Bertrand Yuan Date: Mon, 27 Apr 2026 20:52:54 +0800 Subject: 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 --- .../source/contributing/code-integrity.rst | 43 +++++++++++ .../source/contributing/commit-messages.rst | 85 ++++++++++++++++++++++ Documentation/source/contributing/index.rst | 12 +++ Documentation/source/contributing/workflow.rst | 42 +++++++++++ 4 files changed, 182 insertions(+) create mode 100644 Documentation/source/contributing/code-integrity.rst create mode 100644 Documentation/source/contributing/commit-messages.rst create mode 100644 Documentation/source/contributing/index.rst create mode 100644 Documentation/source/contributing/workflow.rst (limited to 'Documentation/source/contributing') 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 + + (): + + + +