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 --- Documentation/source/operations/database.rst | 59 ++++++++++++++++++++++ Documentation/source/operations/documentation.rst | 51 +++++++++++++++++++ Documentation/source/operations/environment.rst | 60 +++++++++++++++++++++++ Documentation/source/operations/index.rst | 13 +++++ Documentation/source/operations/quality.rst | 56 +++++++++++++++++++++ 5 files changed, 239 insertions(+) create mode 100644 Documentation/source/operations/database.rst create mode 100644 Documentation/source/operations/documentation.rst create mode 100644 Documentation/source/operations/environment.rst create mode 100644 Documentation/source/operations/index.rst create mode 100644 Documentation/source/operations/quality.rst (limited to 'Documentation/source/operations') diff --git a/Documentation/source/operations/database.rst b/Documentation/source/operations/database.rst new file mode 100644 index 0000000..37c0cba --- /dev/null +++ b/Documentation/source/operations/database.rst @@ -0,0 +1,59 @@ +Database +======== + +Local Bootstrap +--------------- + +Use the included helper when developing locally: + +.. code-block:: bash + + ./start-database.sh + +The script is designed for local development and should not be used as a +production database management tool. + +Schema Areas +------------ + +.. list-table:: + :header-rows: 1 + :widths: 24 50 + + * - Area + - Ownership + * - Payload schema + - CMS collections, admin content, media metadata, and Payload-managed + structures. + * - Drizzle ``blog_*`` tables + - better-auth users, sessions, accounts, verifications, comments, rates, + and roles. + +Migration Workflow +------------------ + +For Payload collection changes: + +.. code-block:: bash + + pnpm payload:migrate:create + pnpm payload:migrate + pnpm payload:generate + +For application schema changes: + +.. code-block:: bash + + pnpm db:generate + pnpm db:migrate + +During local iteration, ``pnpm db:push`` can be useful, but committed schema +changes should still have a deliberate migration story. + +Operational Cautions +-------------------- + +* Keep Payload and application-owned tables conceptually separate. +* Regenerate Payload types after collection changes. +* Keep ``drizzle.config.ts`` filters aligned with application-owned tables. +* Do not commit local database data directories or generated build artifacts. diff --git a/Documentation/source/operations/documentation.rst b/Documentation/source/operations/documentation.rst new file mode 100644 index 0000000..b7fcb71 --- /dev/null +++ b/Documentation/source/operations/documentation.rst @@ -0,0 +1,51 @@ +Documentation +============= + +Source Layout +------------- + +Sphinx source files live in ``Documentation/source``. Use reStructuredText for +all Sphinx pages. + +.. list-table:: + :header-rows: 1 + :widths: 26 50 + + * - Directory + - Purpose + * - ``architecture`` + - System design, data model, auth, comments, feeds, and risk register. + * - ``frontend`` + - Routes, UI conventions, components, and accessibility. + * - ``operations`` + - Setup, environment, database, quality, and documentation workflow. + * - ``contributing`` + - Commit, review, and code integrity practices. + * - ``reference`` + - Stable route, command, glossary, and API references. + +Build Commands +-------------- + +Build HTML: + +.. code-block:: bash + + make -C Documentation html + +Clean generated output: + +.. code-block:: bash + + make -C Documentation clean + +Authoring Rules +--------------- + +* Write durable documentation in ``.rst`` files under ``Documentation/source``. +* Keep raw notes in ``docs/`` only when they are not yet ready for the formal + documentation tree. +* Prefer small pages with focused toctrees over long mixed-topic pages. +* Use literal paths and commands with double backticks. +* Add new pages to the nearest ``index.rst`` toctree. +* Do not commit ``Documentation/build`` output. diff --git a/Documentation/source/operations/environment.rst b/Documentation/source/operations/environment.rst new file mode 100644 index 0000000..64e5c8e --- /dev/null +++ b/Documentation/source/operations/environment.rst @@ -0,0 +1,60 @@ +Environment +=========== + +Validation Source +----------------- + +Environment validation is defined in ``src/env.js`` with +``@t3-oss/env-nextjs`` and ``zod``. Empty strings are treated as undefined. + +Server Variables +---------------- + +.. list-table:: + :header-rows: 1 + :widths: 34 44 + + * - Variable + - Purpose + * - ``DATABASE_URL`` + - PostgreSQL connection string. + * - ``RESEND_API_KEY`` + - Resend API key. Must start with ``re_``. + * - ``RESEND_AUDIENCE_ID`` + - Resend audience identifier. + * - ``EMAIL_FROM`` + - Sender email address. + * - ``BETTER_AUTH_SECRET`` + - better-auth secret. Required in production. + * - ``BETTER_AUTH_URL`` + - Optional explicit auth base URL. + * - ``GOOGLE_CLIENT_ID`` / ``GOOGLE_CLIENT_SECRET`` + - Google OAuth credentials. + * - ``GITHUB_CLIENT_ID`` / ``GITHUB_CLIENT_SECRET`` + - GitHub OAuth credentials. + +Client Variables +---------------- + +.. list-table:: + :header-rows: 1 + :widths: 34 44 + + * - Variable + - Purpose + * - ``NEXT_PUBLIC_UMAMI_URL`` + - Optional Umami analytics script URL. + * - ``NEXT_PUBLIC_UMAMI_WEBSITE_ID`` + - Optional Umami site identifier. + +Skipping Validation +------------------- + +``SKIP_ENV_VALIDATION=1`` can be used for limited local or container workflows. +Do not rely on it for production builds. + +Production Notes +---------------- + +Production should use explicit, non-default secrets for Payload and better-auth +and an explicit public site URL for canonical links and generated metadata. diff --git a/Documentation/source/operations/index.rst b/Documentation/source/operations/index.rst new file mode 100644 index 0000000..41b6431 --- /dev/null +++ b/Documentation/source/operations/index.rst @@ -0,0 +1,13 @@ +Operations +========== + +This section covers runtime configuration, database workflows, testing, +documentation builds, and release-oriented tasks. + +.. toctree:: + :maxdepth: 2 + + environment + database + quality + documentation diff --git a/Documentation/source/operations/quality.rst b/Documentation/source/operations/quality.rst new file mode 100644 index 0000000..4be1cfd --- /dev/null +++ b/Documentation/source/operations/quality.rst @@ -0,0 +1,56 @@ +Quality +======= + +Tooling +------- + +.. list-table:: + :header-rows: 1 + :widths: 20 54 + + * - Tool + - Role + * - Vitest + - Unit and component tests. + * - Testing Library + - DOM-oriented component assertions. + * - Biome + - Linting and formatting checks. + * - ``scripts/lint.mts`` + - Project-specific content and link validation. + * - TypeScript + - Static type checking through project build and editor tooling. + +Common Checks +------------- + +.. code-block:: bash + + pnpm lint + pnpm check + pnpm test + pnpm build + +Testing Guidance +---------------- + +Add tests when a change affects: + +* shared UI components; +* route-visible behavior; +* metadata generation; +* validation logic; +* content transformation; +* pagination; +* authentication or comment policy boundaries. + +Keep tests focused on observable behavior. Avoid locking tests to incidental +implementation details unless the implementation itself is the contract. + +CI Direction +------------ + +A complete CI gate should run lint, tests, type-sensitive build checks, and +documentation build checks. If a command requires external secrets, provide a +mocked or validation-skipped CI mode rather than weakening production +validation. -- cgit v1.2.3