From 91188e31385432e9bd8fb8c7626794ba42c389e9 Mon Sep 17 00:00:00 2001 From: Md Bayazid Bostame Date: Sun, 29 Mar 2026 01:48:34 +0100 Subject: [PATCH] docs: tighten handbook ui copy --- .../workflows/developer_handbook.html | 18 +++++++++--------- .../templates/workflows/handbook.html | 9 ++++----- 2 files changed, 13 insertions(+), 14 deletions(-) diff --git a/backend/workflows/templates/workflows/developer_handbook.html b/backend/workflows/templates/workflows/developer_handbook.html index 1668ffe..f4b64ef 100644 --- a/backend/workflows/templates/workflows/developer_handbook.html +++ b/backend/workflows/templates/workflows/developer_handbook.html @@ -18,7 +18,7 @@ Project Wiki -

Engineering runbook for development, deployment, maintenance, and extension of the current company portal deployment.

+

Engineering guide for development, deployment, maintenance, and extension of the current portal deployment.

Overview @@ -45,9 +45,9 @@

1) Overview

-

This handbook is for developers and maintainers. It documents the actual engineering workflow of the standalone product repository.

+

This handbook is for developers and maintainers. It documents the engineering workflow of the standalone product repository.

    -
  • Repository: workdock-platform (current local path; legacy compose project name may still be retained for runtime continuity)
    • +
  • Repository: workdock-platform
  • Main stack: Django + Celery + PostgreSQL + Redis + MailHog
  • Runtime mode: Docker Compose for local development and staging-style operation
  • Repository-level quick-start guide for future coders: CONTRIBUTING.md
    • @@ -308,7 +308,7 @@ docker compose exec -T web python manage.py run_staging_e2e_check
  • Use targeted shell checks for render validation when changing templates or routes.
  • New pages should extend base_shell.html and keep header/frame logic out of page-local templates.
  • Use real PDF generation tests when changing PDF templates or intro/offboarding document logic.
    • -
  • Use the dedicated Release Checklist page as the final go/no-go runbook before shipping changes.
    • +
  • Use the dedicated Release Checklist page as the final go/no-go guide before shipping changes.
  • The automated bilingual smoke tests now cover DE/EN request language capture and English email-template rendering.
  • Onboarding and offboarding request objects now expose explicit processing state and last-error fields. Async tasks are responsible for transitioning submitted → processing → completed/failed.
  • The Requests Dashboard includes a retry action for failed requests. Retries reset the error text, set the request back to submitted, and enqueue the appropriate Celery task again.
    • @@ -349,7 +349,7 @@ make backup-verify BACKUP_DIR=backups/backup_YYYYmmdd_HHMMSS
  • APP_BASE_URL is also appended to trusted CSRF origins automatically.
  • Use APP_DOMAIN and APP_BASE_URL as the primary deployment-facing values instead of repeatedly editing long host/origin strings.
  • If you also reach the app by IP address, keep the IP in DJANGO_ALLOWED_HOSTS and, if needed, in DJANGO_CSRF_TRUSTED_ORIGINS.
    • -
  • The dedicated runbook page is available at /admin-tools/deployment-hosts/.
    • +
  • The dedicated host/domain guide is available at /admin-tools/deployment-hosts/.
  • An Invalid HTTP_HOST header failure happens before normal page routing, so a broken hostname cannot render a custom error page on that same broken host. Use a working host or IP to access the runbook and fix the env file.
@@ -361,7 +361,7 @@ make backup-verify BACKUP_DIR=backups/backup_YYYYmmdd_HHMMSS
  • Working branch: develop.
  • Stable branch: main.
  • GitHub Actions is used for CI.
    • -
  • Current test deployment is done manually from a LAN-connected machine, not from GitHub-hosted runners.
    • +
  • Test deployment is done manually from a LAN-connected machine, not from GitHub-hosted runners.
    • @@ -408,7 +408,7 @@ make backup-verify BACKUP_DIR=backups/backup_YYYYmmdd_HHMMSS
    -

    Current test server values

    +

    Test server values

    - The current LAN test deployment intentionally uses DJANGO_DEBUG=1 in .env.test because the security checks correctly reject insecure cookie settings when DEBUG=0 and the deployment is still plain HTTP behind a local test topology. This is acceptable for the test box only. Production must run with HTTPS and DEBUG=0. + The LAN test deployment intentionally uses DJANGO_DEBUG=1 in .env.test because the security checks correctly reject insecure cookie settings when DEBUG=0 and the deployment is still plain HTTP behind a local test topology. This is acceptable for the test box only. Production must run with HTTPS and DEBUG=0.

    18) Deployment

    @@ -475,7 +475,7 @@ make backup-verify BACKUP_DIR=backups/backup_YYYYmmdd_HHMMSS
  • Wait until /healthz/ becomes healthy

    • Manual deploy

    -

    The preferred current test-deployment path is the local helper script from a Mac or another LAN-connected workstation:

    +

    The preferred test-deployment path is the local helper script from a Mac or another LAN-connected workstation:

    ./scripts/deploy_test_from_mac.sh

    This script fast-forwards develop, checks that the remote env file exists, syncs the repo to the server with rsync, runs the remote deployment, verifies the health endpoint, and prints the deployed commit hash.

    The script explicitly preserves server-local env files such as .env.test and .env.prod so deployment does not wipe machine-specific secrets.

    diff --git a/backend/workflows/templates/workflows/handbook.html b/backend/workflows/templates/workflows/handbook.html index 4e90260..a5a92c8 100644 --- a/backend/workflows/templates/workflows/handbook.html +++ b/backend/workflows/templates/workflows/handbook.html @@ -15,7 +15,7 @@

    {% trans "Handbook" %}

    -

    {% trans "Single documentation entry point for both operational knowledge and long-term engineering knowledge." %}

    +

    {% trans "Operational and engineering documentation in one place." %}

    @@ -26,7 +26,7 @@
  • {% trans "workflow overview" %}
  • {% trans "admin tools and system behavior" %}
  • {% trans "integrations and operations" %}
    • -
  • {% trans "runbook and troubleshooting" %}
    • +
  • {% trans "operations and troubleshooting" %}
    • {% trans "Open Project Wiki" %} @@ -36,7 +36,7 @@
    {% trans "Engineering" %}

    {% trans "Developer Handbook" %}

    -

    {% trans "Engineering runbook for architecture, branch workflow, deployment, CI/CD, code guidelines, and long-term maintenance." %}

    +

    {% trans "Engineering guide for architecture, branch workflow, deployment, CI/CD, code guidelines, and maintenance." %}

    • {% trans "repository and service structure" %}
    • {% trans "branch workflow and coding guidelines" %}
      • @@ -46,7 +46,6 @@
    {% trans "Open Developer Handbook" %} - {% trans "Open Contributor Guide" %}
    @@ -68,7 +67,7 @@
    {% trans "Release" %}

    {% trans "Release Checklist" %}

    -

    {% trans "Step-by-step release runbook for rebuilds, migrations, translations, static assets, smoke checks, and rollout verification." %}

    +

    {% trans "Step-by-step release guide for rebuilds, migrations, translations, static assets, smoke checks, and rollout verification." %}

    • {% trans "pre-release validation commands" %}
    • {% trans "translation, static, and migration steps" %}