From d6cf1006aab71d7f43ac2b435679cb0f97b9751d Mon Sep 17 00:00:00 2001 From: Ronan Date: Thu, 16 Jul 2026 11:42:35 +0800 Subject: [PATCH] docs(#1): establish secure development guide --- .github/PULL_REQUEST_TEMPLATE.md | 74 ++++ .github/workflows/documentation-quality.yml | 26 ++ .pre-commit-config.yaml | 29 ++ Compliance/ISO IEC 27001 Mapping.md | 97 ++++++ Engineering/Engineering Standards.md | 122 +++++++ Engineering/Testing and Quality Gates.md | 131 +++++++ Git/Branch Management.md | 103 ++++-- Git/Commit Messages.md | 94 +++-- Git/Development Flow.md | 148 ++++++-- README.md | 125 +++++++ SECURITY.md | 52 +++ Security/Secrets and Data Handling.md | 100 ++++++ Security/Secure Development Standard.md | 170 ++++++++++ Version Management/Release New Version.md | 160 +++++++-- python-guide-ist.md | 358 -------------------- scripts/check_markdown_links.py | 85 +++++ 16 files changed, 1415 insertions(+), 459 deletions(-) create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/workflows/documentation-quality.yml create mode 100644 .pre-commit-config.yaml create mode 100644 Compliance/ISO IEC 27001 Mapping.md create mode 100644 Engineering/Engineering Standards.md create mode 100644 Engineering/Testing and Quality Gates.md create mode 100644 README.md create mode 100644 SECURITY.md create mode 100644 Security/Secrets and Data Handling.md create mode 100644 Security/Secure Development Standard.md delete mode 100644 python-guide-ist.md create mode 100644 scripts/check_markdown_links.py diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..5133b52 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,74 @@ +## Summary + + + +## Linked record + +- Issue / change / incident: +- Target release (if any): + +## Risk classification + +- [ ] Standard +- [ ] High-risk — threat model and two independent approvals required +- [ ] Emergency — incident/change approval and retrospective controls required + +### Security and privacy + +- Affected assets, trust boundaries, identities, and data classes: +- Authentication / authorization / secrets / cryptography impact: +- Abuse cases and controls: +- Privacy, retention, transfer, or customer impact: +- Residual risk or approved exception: + + + +## Scope + +- Components and interfaces changed: +- Deliberately out of scope: +- Compatibility or breaking-change impact: +- Dependencies, packages, CI actions, images, or licenses changed: + +## Validation evidence + +| Check | Command / CI job | Result | +|---|---|---| +| Formatting / pre-commit | | | +| Lint / static / type checks | | | +| Targeted tests | | | +| Full tests | | | +| Security / secret / dependency scans | | | +| Build / package / migration | | | +| Manual / integration / gateway validation | | | + +Known failures, skipped checks, or environment limitations: + +## Release and operations + +- Configuration or migration steps: +- Deployment order and post-deployment checks: +- Monitoring and rollback trigger: +- Rollback or forward-fix procedure: +- Documentation and release notes updated: + +## Author checklist + +- [ ] The change is minimal, issue-scoped, and contains no unrelated refactor or formatting. +- [ ] I reviewed the final diff, including generated and binary files. +- [ ] No secrets, production/customer data, personal data, or sensitive security evidence are included. +- [ ] Server-side authorization, input validation, safe errors, and safe logging were considered. +- [ ] Changed behavior has positive, negative, boundary, and regression tests as applicable. +- [ ] Repository-defined checks completed on this commit; failures and skips are disclosed above. +- [ ] Dependency and supply-chain changes were verified and pinned through the repository mechanism. +- [ ] Migration, deployment, monitoring, compatibility, and rollback impacts are documented. +- [ ] Documentation reflects the implemented behavior and does not overstate a control. +- [ ] Exceptions and residual risks have a named approver, compensating control, and expiry/follow-up. + +## Reviewer checklist + +- [ ] The requirement, implementation, tests, and evidence agree. +- [ ] Security, privacy, data, dependency, and operational impacts were reviewed. +- [ ] The diff is focused and preserves existing contracts unless intentionally changed. +- [ ] Required checks are current and successful on the reviewed commit. +- [ ] Release and rollback steps are proportionate to the risk. diff --git a/.github/workflows/documentation-quality.yml b/.github/workflows/documentation-quality.yml new file mode 100644 index 0000000..efaf379 --- /dev/null +++ b/.github/workflows/documentation-quality.yml @@ -0,0 +1,26 @@ +name: Documentation quality + +on: + pull_request: + push: + branches: + - main + +permissions: + contents: read + +jobs: + pre-commit: + runs-on: ubuntu-latest + timeout-minutes: 10 + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.12" + + - name: Run pre-commit + uses: pre-commit/action@v3.0.1 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..8dc96c7 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,29 @@ +minimum_pre_commit_version: "3.0.0" + +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.6.0 + hooks: + - id: trailing-whitespace + - id: end-of-file-fixer + - id: check-yaml + - id: check-added-large-files + - id: check-case-conflict + - id: check-merge-conflict + - id: detect-private-key + - id: mixed-line-ending + args: [--fix=lf] + + - repo: https://github.com/Yelp/detect-secrets + rev: v1.4.0 + hooks: + - id: detect-secrets + + - repo: local + hooks: + - id: markdown-internal-links + name: validate repository-local Markdown links + entry: python scripts/check_markdown_links.py + language: system + files: \.md$ + pass_filenames: false diff --git a/Compliance/ISO IEC 27001 Mapping.md b/Compliance/ISO IEC 27001 Mapping.md new file mode 100644 index 0000000..90cf8e6 --- /dev/null +++ b/Compliance/ISO IEC 27001 Mapping.md @@ -0,0 +1,97 @@ +# ISO/IEC 27001:2022 Mapping + +## Purpose and limitation + +This mapping shows how the Developer Guide supports engineering-related requirements and controls in ISO/IEC 27001:2022. It is a navigation aid for the Cubewise Asia ISMS and audit evidence; it is not a Statement of Applicability, risk assessment, legal opinion, certification claim, or substitute for the licensed standards. + +Control applicability and implementation status MUST be determined through the organizational risk-treatment process. The ISMS owner MUST maintain the authoritative Statement of Applicability, including justification for inclusion or exclusion and the implementation status of each control. + +Authoritative references: + +- [ISO/IEC 27001:2022 — ISMS requirements](https://www.iso.org/standard/27001) +- [ISO/IEC 27001:2022/Amd 1:2024 — Climate action changes](https://www.iso.org/standard/88435.html) +- [ISO/IEC 27002:2022 — Information security controls](https://www.iso.org/standard/75652.html) +- [ISO/IEC 27000 family overview](https://www.iso.org/standard/iso-iec-27000-family) + +## Clauses 4–10 + +| Clause | Guide support | Example engineering evidence | ISMS dependency | +|---|---|---|---| +| 4 — Context | README scope, precedence, repository baseline, and this mapping | Repository scope, stakeholders, system context, customer/security requirements | Organization scope, interested parties, ISMS processes, and assessment of whether climate change is relevant under the 2024 amendment | +| 5 — Leadership | Mandatory controls, owners, roles, segregation, and exception approval | Approved guide, repository ownership, branch protection, review records | Security policy, leadership commitment, assigned authorities | +| 6 — Planning | Change risk classification, threat modeling, residual risk, and exceptions | Issue risk assessment, threat model, risk acceptance, remediation issue | ISMS risk method, risk register, treatment plan, objectives, Statement of Applicability | +| 7 — Support | Repository contract, competence expectations, controlled documentation, and evidence | Onboarding/training record, current documentation, CI logs, approved tools | Resources, competence program, awareness, communication, document control | +| 8 — Operation | Development flow, secure coding, testing, release, supplier/dependency controls | Pull requests, tests, scans, approvals, releases, deployments, rollback tests | Operational planning, outsourced-process control, formal risk-treatment operation | +| 9 — Performance evaluation | Quality gates, monitoring evidence, review records, and baseline-failure handling | Required-check trends, defects, vulnerabilities, review and release metrics | ISMS monitoring objectives, internal audit, management review | +| 10 — Improvement | Incident learning, regression tests, corrective actions, guide review | Root-cause record, corrective issue, updated tests/controls | Nonconformity process and continual-improvement program | + +The 2024 amendment adds climate-change consideration to organizational context and interested-party analysis. Engineering teams MUST implement resulting requirements when the ISMS determines they are relevant, for example resilience, hosting, supplier, capacity, continuity, or customer commitments. This guide does not make that organization-level determination. + +## Annex A engineering control mapping + +The control names below are abbreviated navigation labels. Consult the licensed standards and the Cubewise Asia Statement of Applicability for authoritative wording and applicability. + +| Control | Guide section | Expected evidence | Primary engineering role | +|---|---|---|---| +| A.5.1 Policies for information security | [README](../README.md), guide maintenance | Approved standard, review history | Engineering and ISMS owners | +| A.5.2 Information security roles and responsibilities | [README — Roles](../README.md#roles-and-segregation-of-duties) | Ownership and reviewer records | Maintainer | +| A.5.3 Segregation of duties | [Branch Management](../Git/Branch%20Management.md), [Development Flow](../Git/Development%20Flow.md) | Independent approvals, restricted bypass | Maintainer / Release owner | +| A.5.7 Threat intelligence | [Secure Development — Supply chain](../Security/Secure%20Development%20Standard.md#dependencies-and-software-supply-chain) | Advisory sources, vulnerability triage | Maintainer / Security owner | +| A.5.8 Information security in project management | [Development Flow](../Git/Development%20Flow.md) | Issue risk assessment, threat model | Product owner / Developer | +| A.5.9 Inventory of information and associated assets | [Release Management](../Version%20Management/Release%20New%20Version.md), repository contract | Component/dependency inventory, SBOM, owners | Maintainer / Release owner | +| A.5.10 Acceptable use of information and assets | [Engineering Standards — AI](../Engineering/Engineering%20Standards.md#ai-assisted-development), [Secrets and Data](../Security/Secrets%20and%20Data%20Handling.md) | Approved tools and handling records | Developer / Manager | +| A.5.12–A.5.14 Classification, labelling, and transfer | [Secrets and Data Handling](../Security/Secrets%20and%20Data%20Handling.md) | Classification, redaction, approved transfer | Information owner / Developer | +| A.5.15–A.5.18 Access control, identity, authentication information, and access rights | [Secure Development — Authentication](../Security/Secure%20Development%20Standard.md#authentication-sessions-and-authorization) | Authn/authz tests, access reviews, least-privilege configuration | Maintainer / Security owner | +| A.5.19–A.5.22 Supplier and ICT supply-chain security | [Secure Development — Supply chain](../Security/Secure%20Development%20Standard.md#dependencies-and-software-supply-chain) | Supplier/dependency review, lockfile, scan, remediation | Maintainer / Procurement / Security | +| A.5.23 Cloud services | [Secure Development — CI/CD](../Security/Secure%20Development%20Standard.md#cicd-and-deployment-security), [AI and LLM](../Security/Secure%20Development%20Standard.md#ai-and-llm-features) | Approved service, region, account, access, exit/retention terms | Service owner / Security owner | +| A.5.24–A.5.28 Incident preparation, assessment, response, learning, and evidence | [Security Policy](../SECURITY.md), exposure procedure | Private report, incident record, evidence, corrective actions | Incident owner / Developer | +| A.5.29–A.5.30 Security during disruption and ICT readiness | [Release rollback and recovery](../Version%20Management/Release%20New%20Version.md#rollback-and-recovery), resilience controls | Recovery objectives, backups, restore/rollback test | Service / Release owner | +| A.5.31 Legal, statutory, regulatory, and contractual requirements | README precedence, dependency and data rules | Requirement traceability, license/privacy review | Product / Legal / ISMS owner | +| A.5.32 Intellectual property rights | [Dependencies](../Engineering/Engineering%20Standards.md#dependencies), [AI-assisted development](../Engineering/Engineering%20Standards.md#ai-assisted-development) | License review, attribution, provenance | Developer / Maintainer | +| A.5.33 Protection of records | [README — Required evidence](../README.md#required-evidence), quality evidence | Controlled PR, CI, release, and risk records | Maintainer / ISMS owner | +| A.5.34 Privacy and protection of PII | [Secrets and Data Handling](../Security/Secrets%20and%20Data%20Handling.md) | Privacy impact, minimization, masking, deletion | Information / Product owner | +| A.5.36 Compliance with policies and standards | [Quality Gates](../Engineering/Testing%20and%20Quality%20Gates.md), this mapping | CI checks, review, exceptions, audit findings | Maintainer / ISMS owner | +| A.5.37 Documented operating procedures | Development, testing, and release procedures | Current runbooks and execution evidence | Service / Release owner | +| A.6.3 Awareness, education, and training | README applicability and maintenance | Training/onboarding acknowledgement | Engineering manager / ISMS owner | +| A.6.7 Remote working | [Secrets and Data Handling](../Security/Secrets%20and%20Data%20Handling.md) | Approved device, storage, transfer, and access | Manager / User | +| A.6.8 Information security event reporting | [Security Policy](../SECURITY.md) | Timely private report | All contributors | +| A.8.1 User endpoint devices | Local data and secret-handling controls | Managed device and approved local storage | User / IT owner | +| A.8.2–A.8.5 Privileged access, access restriction, source-code access, secure authentication | Authentication and CI/CD controls | Repository access, protected branches, MFA/SSO, tests | Maintainer / IT / Security | +| A.8.6 Capacity management | [Capacity and resilience](../Security/Secure%20Development%20Standard.md#capacity-resilience-and-concurrency) | Limits, load evidence, alerts | Service owner | +| A.8.7 Protection against malware | File, upload, dependency, and artifact controls | Malware scan and upload validation | Developer / Release owner | +| A.8.8 Management of technical vulnerabilities | Supply-chain and vulnerability process | Inventory, scan, triage, remediation SLA/risk acceptance | Maintainer / Security owner | +| A.8.9 Configuration management | [Engineering Standards — Configuration](../Engineering/Engineering%20Standards.md#configuration), CI/CD controls | Reviewed config, secure defaults, change history | Service owner | +| A.8.10–A.8.12 Deletion, masking, and data leakage prevention | [Secrets and Data Handling](../Security/Secrets%20and%20Data%20Handling.md) | Retention/deletion evidence, masked data, secret scans | Information owner / Developer | +| A.8.13–A.8.14 Backup and redundancy | Release recovery and resilience controls | Restore tests, redundancy/failover evidence | Service / Operations owner | +| A.8.15–A.8.16 Logging and monitoring | [Secure Development — Logging](../Security/Secure%20Development%20Standard.md#logging-monitoring-and-errors) | Safe audit logs, alerts, monitored events | Service / Security owner | +| A.8.17 Clock synchronization | [Secure Development — Logging](../Security/Secure%20Development%20Standard.md#logging-monitoring-and-errors) | Synchronized timestamps and time-source configuration | Operations / Service owner | +| A.8.18–A.8.19 Privileged utilities and software installation | CI/CD, extension, and release controls | Restricted tools, approved packages and deployment | Maintainer / Release owner | +| A.8.20–A.8.22 Network security and segregation | Outbound request and deployment controls | Network design, allowlists, environment separation | Architecture / Operations owner | +| A.8.24 Use of cryptography | [Cryptography and TLS](../Security/Secure%20Development%20Standard.md#cryptography-and-tls) | Approved algorithms/services, key lifecycle, tests | Security / Service owner | +| A.8.25 Secure development life cycle | Entire guide, especially [Development Flow](../Git/Development%20Flow.md) | End-to-end issue-to-release traceability | Engineering owner | +| A.8.26 Application security requirements | Development risk and threat-model steps | Security acceptance criteria | Product / Security / Developer | +| A.8.27 Secure system architecture and engineering principles | Threat modeling and secure design | Architecture decision and review | Architect / Security reviewer | +| A.8.28 Secure coding | [Secure Development Standard](../Security/Secure%20Development%20Standard.md) | Code review and security tests | Developer / Reviewer | +| A.8.29 Security testing in development and acceptance | [Testing and Quality Gates](../Engineering/Testing%20and%20Quality%20Gates.md) | Automated/acceptance security evidence | Developer / QA / Reviewer | +| A.8.30 Outsourced development | Applicability, supplier, review, and evidence requirements | Contract, access, deliverable review | Engineering / Supplier owner | +| A.8.31 Separation of development, test, and production | CI/CD and data-handling controls | Separate identities, data, configuration, approvals | Operations / Service owner | +| A.8.32 Change management | Git, pull request, and release procedures | Issue, branch, review, checks, release record | Maintainer / Release owner | +| A.8.33 Test information | [Testing](../Engineering/Testing%20and%20Quality%20Gates.md), [data handling](../Security/Secrets%20and%20Data%20Handling.md) | Synthetic/masked data, access and cleanup | QA / Information owner | +| A.8.34 Protection during audit testing | Evidence and data-minimization rules | Approved audit plan, restricted evidence, cleanup | Audit / Service / Security owner | + +## Controls primarily outside this guide + +People screening and employment terms, physical security, facilities, corporate endpoint management, legal interpretation, organization-wide business continuity, internal audit, management review, and certification are primarily owned by other ISMS processes. Engineering teams MUST cooperate with those controls and retain requested evidence, but SHOULD NOT invent local substitutes or mark them complete in this repository. + +## Evidence review questions + +For each applicable control, the owner should be able to answer: + +1. What risk or requirement does the control address? +2. Where is the approved procedure or technical enforcement? +3. Who owns operation and review? +4. What recent evidence proves the control operated? +5. What exceptions, failures, vulnerabilities, or residual risks remain? +6. When will effectiveness and applicability be reviewed again? + +A document stating that a control exists is not sufficient evidence that the control is implemented and effective. diff --git a/Engineering/Engineering Standards.md b/Engineering/Engineering Standards.md new file mode 100644 index 0000000..d1aefbd --- /dev/null +++ b/Engineering/Engineering Standards.md @@ -0,0 +1,122 @@ +# Engineering Standards + +## General rules + +- Follow the repository's architecture, supported runtimes, formatter, linter, type checker, and dependency manager. +- Prefer explicit, readable, testable code over clever abstractions. +- Keep changes small and reversible. Do not refactor unrelated code. +- Make invalid states difficult to represent and validate untrusted data at the boundary. +- Preserve existing accepted input, output, errors, UX, debug behavior, and compatibility unless an approved requirement changes them. +- Use clear domain names. Avoid vague helpers, broad utility modules, and abstractions used only once. +- Treat warnings from compilers, linters, tests, migrations, and packaging as defects unless the repository records an approved baseline exception. + +## Repository contract + +Each repository MUST document: + +- supported operating systems and runtime versions; +- setup and dependency installation; +- configuration templates and secret sources; +- local run, format, lint, type-check, test, build, and packaging commands; +- database and migration workflow; +- architecture and ownership boundaries; +- release and rollback process; +- known external services needed for integration testing. + +Commands in repository documentation take precedence over generic examples in this guide. A repository MUST keep its CI commands consistent with its documented local commands. + +## Python + +Cubewise Asia's current service baseline is Python 3.12 where the repository declares that target. Do not change a repository's supported Python version as part of unrelated work. + +### Style and structure + +- Use the configured YAPF, isort, lint, and type-check settings; do not apply personal formatting preferences. +- Use four-space indentation and the line length configured by the repository. +- Organize imports in standard-library, third-party, and local groups through the configured import sorter. +- Use snake_case for modules, functions, methods, and variables; CapWords for classes and exceptions; and UPPER_CASE for constants. +- Avoid wildcard imports, mutable default arguments, hidden global state, and broad except Exception handlers that convert failure into success. +- Use context managers for files, connections, locks, temporary resources, and other owned resources. +- Keep route/controller code thin. Put domain logic in the repository's established service or domain layer. + +### Types and contracts + +- Type API, storage, service, and serialization boundaries explicitly. +- Avoid Any, unchecked casts, and unvalidated dictionaries at trust boundaries. +- Use the repository's established request/response schema library for external payloads. +- Do not silently trim, coerce, normalize, or default user input unless the contract explicitly requires it. +- Return explicit errors for invalid or failed operations; do not leak stack traces or sensitive internal detail to clients. + +### Async, concurrency, and resources + +- Do not block an async event loop with synchronous network, file, database, subprocess, or CPU-heavy work. +- Bound concurrency, queues, retries, timeouts, payload sizes, and resource use. +- Clean up tasks, processes, browser sessions, files, database sessions, and locks on success, failure, cancellation, and timeout. +- Add regression tests for race conditions, cancellation, replay, duplicate requests, and partial failure where relevant. + +## TypeScript and React + +Repositories with frontend code currently target the repository-declared Node version, commonly Node 22, and MUST use the committed lockfile with deterministic installation such as npm ci in CI. + +- Keep strict types at API, component, state, and storage boundaries. +- Avoid any, non-null assertions, and unsafe casts unless the reason is documented and tested. +- Do not duplicate derived state. Use effects only for genuine external side effects or async coordination. +- Include correct effect dependencies, cleanup subscriptions, and prevent stale async responses from overwriting current state. +- Verify loading, error, empty, disabled, timeout, retry, and unauthorized states. +- Keep client validation consistent with server validation, but never rely on client validation for security. +- Encode untrusted output using framework-safe rendering. Do not introduce unsafe HTML rendering without sanitization and security review. +- Preserve accessibility, keyboard behavior, and established UI copy unless the requirement changes them. + +## APIs and services + +- Define and validate request, response, error, pagination, authentication, authorization, rate, and idempotency contracts. +- Use appropriate HTTP status codes and avoid using 200 for a failed operation. +- Authorize the requested action and resource, not only the route. +- Apply size limits, timeouts, bounded pagination, and rate controls to externally reachable expensive operations. +- Propagate a safe correlation identifier across services. Do not use tokens, email addresses, or sensitive identifiers as correlation IDs. +- Version or provide a compatibility plan for breaking contracts. +- For gateway-scoped SSO, cookies, or routing, validate the integrated flow through the gateway rather than only through internal ports. + +## Persistence and migrations + +- Prefer additive, backward-compatible migrations that support rolling deployment and rollback. +- Review data type, nullability, default, index, uniqueness, foreign-key, and retention effects. +- Do not combine destructive data removal with the first release that stops reading the data. +- Make migrations deterministic, bounded, restartable where practical, and safe for the expected production volume. +- Back up or otherwise protect affected data before an irreversible change. +- Ensure migration history has a single expected head where the migration tool requires it. +- Test upgrade, application compatibility, failure recovery, and downgrade or forward-fix procedures. + +## Configuration + +- Commit safe example configuration, never live configuration or credentials. +- Keep environment-specific configuration outside the artifact when the platform supports it. +- Validate configuration on startup and fail closed for missing security-critical values or known insecure defaults. +- Document each setting's purpose, type, default, sensitivity, valid range, and restart impact. +- Production security settings MUST NOT default to a development bypass. + +## Dependencies + +- Add a dependency only when the requirement cannot be met safely with the existing stack or standard library. +- Record the purpose, owner, version constraint, license, source, transitive risk, and maintenance posture. +- Use the repository's lock or constraints mechanism and deterministic installation. +- Remove unused dependencies and do not import packages from untrusted indexes or arbitrary URLs. +- Follow the vulnerability and supply-chain requirements in the [Secure Development Standard](../Security/Secure%20Development%20Standard.md). + +## Documentation + +Documentation is part of the change. Update it when setup, configuration, API behavior, security assumptions, support boundaries, deployment, recovery, or operator action changes. + +- Use English for repository engineering documentation unless a customer deliverable requires another language. +- Keep examples runnable, safe, and free of secrets and production data. +- Mark assumptions, limitations, destructive steps, and environment-specific deviations explicitly. +- Link to the source of truth instead of duplicating volatile values. +- Do not describe a control as implemented unless code, configuration, tests, and operational ownership support the claim. + +## AI-assisted development + +- Use only organization-approved AI services and accounts for company work. +- Do not submit secrets, customer data, personal data, private keys, production logs, confidential contracts, or restricted source code to an unapproved service. +- The developer remains accountable for correctness, security, licensing, attribution, tests, and review. +- Inspect generated dependencies, commands, links, licenses, and code; never assume generated output is safe or current. +- AI-generated changes follow the same issue, branch, review, testing, and evidence requirements as human-authored changes. diff --git a/Engineering/Testing and Quality Gates.md b/Engineering/Testing and Quality Gates.md new file mode 100644 index 0000000..e810b6c --- /dev/null +++ b/Engineering/Testing and Quality Gates.md @@ -0,0 +1,131 @@ +# Testing and Quality Gates + +## Principle + +Reasoning, screenshots, a successful command exit, or an HTTP status alone are not proof of correct behavior. Validation MUST demonstrate the acceptance criteria and important failure modes with reproducible evidence. + +## Test layers + +| Layer | Purpose | Typical evidence | +|---|---|---| +| Unit | Domain behavior and edge cases in isolation | Deterministic tests with focused assertions. | +| Component / service | Boundaries such as database, files, queues, auth, and external adapters | Test database, fakes, contract fixtures, or controlled local services. | +| API / contract | Request and response shape, status, authn/authz, validation, compatibility | Client tests and schema assertions. | +| Integration | Real interaction between owned components | Controlled environment results with sanitized logs. | +| End-to-end | Critical user and operator journeys | Gateway-based tests and artifact/content validation. | +| Security | Abuse cases and control enforcement | Negative tests, scanners, and focused regression suites. | +| Release smoke | Exact packaged artifact in a release-like environment | Version, health, critical flow, migration, and rollback evidence. | + +Tests SHOULD be isolated from real customer and production systems. Live integration tests MUST be opt-in, use approved non-production accounts and data, have bounded timeouts and cleanup, and never place credentials in the repository or test output. + +## Change-based minimums + +| Change | Minimum additional validation | +|---|---| +| Bug fix | A regression test that fails before the fix and passes after it. | +| New behavior | Positive, negative, boundary, permission, and error-path tests. | +| Authentication or session | Missing, invalid, expired, replayed, rotated, revoked, cross-user, and logout cases. | +| Authorization | Allowed and denied actors at both route and resource level; fail-closed dependency failure. | +| Input or parser | Empty, whitespace, malformed, oversized, duplicate, traversal, injection, encoding, and unexpected-type cases. | +| Database migration | Upgrade, compatibility, partial failure, realistic volume, and rollback or forward-fix. | +| Concurrency or subprocess | Timeout, cancellation, process cleanup, resource cap, partial failure, and duplicate/replay cases. | +| Dependency or build | Lockfile/constraints change, clean install, license review, vulnerability scan, build, and package smoke. | +| Frontend | Type check, lint, component tests, build, and loading/error/empty/disabled/unauthorized states. | +| Release or packaging | Build from clean source, artifact version, checksum/provenance, install/upgrade, critical smoke, and rollback. | +| Documentation only | Pre-commit, internal-link validation, rendered structure review, and command/example review. | + +## Local quality gate + +Run repository-specific commands. Common Cubewise Asia examples include: + +~~~bash +pre-commit run --all-files +python -m pytest +npm ci --prefix frontend +npm run tsc --prefix frontend +npm run lint --prefix frontend +npm test --prefix frontend +npm run build --prefix frontend +~~~ + +The repository MAY use different commands, but the control outcomes remain required. Install dependencies in an isolated environment and use the repository-declared runtime versions. + +If a formatter changes files, review and keep only in-scope changes, then rerun the complete quality gate until a second run is clean. Do not bypass a hook or change a test merely to obtain a green result. + +## CI requirements + +CI for an active product repository MUST: + +- run on pull requests to protected branches; +- use least-privilege workflow permissions; +- install from committed lock or constraints files; +- run formatting/lint/static checks, tests, and builds relevant to the change; +- run secret and dependency/security scans appropriate to the stack; +- isolate jobs or test processes when shared state or module mocking can contaminate results; +- use bounded timeouts for jobs, external calls, browsers, and subprocesses; +- avoid exposing secrets to forked or untrusted pull requests; +- retain useful, access-controlled evidence without logging sensitive data; +- prevent deployment when required checks are skipped, cancelled, stale, or failed. + +Third-party CI actions MUST use reviewed, pinned versions; immutable commit pins are preferred for high-risk pipelines. Updates to CI actions are dependency changes and require review. + +## Security test baseline + +Add applicable automated cases for: + +- authentication, authorization, privilege escalation, identity binding, and tenant isolation; +- CSRF, XSS, injection, SSRF, open redirects, path traversal, archive extraction, and unsafe deserialization; +- secure cookies, token rotation/replay, logout revocation, OAuth state/PKCE, and redirect allowlists; +- secret scanning, unsafe logs, sensitive error messages, and insecure default configuration; +- dependency, wheel/package, plugin, connector, and artifact validation; +- file size/count limits, decompression bombs, symlinks, executable content, and atomic writes; +- subprocess isolation, environment allowlists, timeouts, process trees, and cleanup; +- rate limits, pagination bounds, capacity limits, and fail-closed behavior; +- encryption, key configuration, TLS verification, and prohibited fallback behavior. + +Tests MUST target the real control path where practical. A test that mocks away the authorization, parser, or security control it intends to validate is not sufficient. + +## Coverage and test quality + +Coverage is an indicator, not an objective by itself. Changed critical logic SHOULD have branch coverage for meaningful decisions. Do not add assertions that merely execute lines without validating outcomes. + +Tests MUST be: + +- deterministic and independent of execution order; +- explicit about expected behavior and failure; +- bounded in runtime and resources; +- free of production secrets and customer data; +- responsible for cleanup; +- named by behavior, not implementation detail. + +Skipped and quarantined tests require a linked issue, owner, reason, risk, and expiry. Flaky tests are defects; do not normalize rerunning CI until it passes. + +## Manual and live validation + +When automation cannot prove behavior: + +1. document the environment and sanitized preconditions; +2. execute a repeatable procedure; +3. validate the resulting content and state, not only the response status; +4. capture sanitized evidence and correlate it to the commit or artifact; +5. clean up accounts, data, files, and configuration; +6. record limitations and residual risk. + +Cross-service authentication, cookies, SSO, and routing MUST be tested through the supported gateway unless the objective is specifically to test an internal port. + +## Baseline failures + +An unrelated existing failure does not authorize a new failure. Record the exact command, failing test/check, relevant output, comparison with the approved baseline, and why the change does not contribute to it. Link the owning issue. A required check remains blocking unless the maintainer and risk owner approve a time-bound exception. + +## Evidence in the pull request + +Provide: + +- commands and CI jobs run; +- pass/fail/skip counts and relevant versions; +- sanitized integration or manual results; +- generated artifact validation where applicable; +- known gaps, baseline failures, and approved exceptions; +- deployment and rollback validation for release-impacting changes. + +Never claim a check passed if it did not run to completion on the reviewed commit. diff --git a/Git/Branch Management.md b/Git/Branch Management.md index f80bb31..40c9dc6 100644 --- a/Git/Branch Management.md +++ b/Git/Branch Management.md @@ -1,43 +1,86 @@ -# Git Branch Management Guide +# Branch Management -This guide outlines best practices for branch management in our projects to ensure a smooth, efficient, and error-free development process. +## Objectives -## 1. Branch Organization +Branches provide change isolation, independent review, reliable releases, and rollback traceability. Repository maintainers MUST document the approved integration and production branches and enforce them with branch protection or organization rulesets. -- **Main Branch**: - - The `main` or `master` branch is the production branch. All production-ready code lives here. -- **Development Branch**: - - The `dev` branch serves as an integration branch for features. This is where all development branches merge before they are tested and moved to the `main` branch. -- **Feature Branches**: - - Create feature branches from `dev` for new features or significant changes. -- **Version Branches**: - - Create Version branches from `dev` for new version release. +## Branch roles -## 2. Code Quality Checks +| Branch | Purpose | Required controls | +|---|---|---| +| main or master | Production-ready history | Protected; pull requests only; required checks; independent approval; no force push or deletion. | +| dev | Normal integration base where the repository uses a GitFlow-style model | Protected; pull requests only; required checks; independent approval. | +| Release branch, for example V5.1.0 | Stabilization of an approved release | Created from the documented base; accepts only release-scoped fixes; protected while active. | +| Feature or fix branch | Short-lived implementation branch | Created from the approved base; one issue or cohesive change; deleted after merge. | +| Hotfix branch | Urgent production correction | Created from the affected production tag or branch; incident/change approval; merged back to all affected maintained branches. | -- **Pull Requests**: - - Always use pull requests to merge branches into `dev`, `version branch` and `main`. This ensures that the code is reviewed and tested. -- **Code Reviews**: - - Require at least one other team member to review the code in a pull request to maintain code quality and catch errors early. +Repositories that do not use dev MUST document their alternative flow. Do not create a new permanent branch model as part of an unrelated change. -## 3. Commit Management +## Naming -- **Small Commits**: - - Keep commits small and focused. Each commit should represent a single logical change. This makes it easier to identify where issues were introduced and to roll back changes if necessary. +Use lowercase ASCII branch names except where an established release convention uses an uppercase V. Use hyphens in the description. -## 4. Branch Lifespan +~~~text +/- +~~~ -- **Short-lived Feature Branches**: - - Feature branches should be kept short-lived to minimize divergence from the main development line (`dev`). Aim to merge back within 1-2 weeks. -- **Branch Cleanup**: - - Delete branches once they are merged and are no longer needed. +Approved types: -## 5. Handling Large Changes +- feat — new user-visible capability; +- fix — defect correction; +- hotfix — approved urgent production fix; +- docs — documentation-only change; +- test — test-only change; +- chore — maintenance with no product behavior change; +- research — time-boxed investigation that is not release code. -- **Sub-branches**: - - If a feature is too large, consider breaking it into smaller sub-branches that can be merged into the main feature branch incrementally. +Examples: -## Additional Recommendations +~~~text +feat/484-rundoc-failure-alerts +fix/870-view-alias-labels +docs/102-secure-release-process +hotfix/615-session-cookie-regression +~~~ -- **Tagging Releases**: - - Use tags for each release to mark a point in history. This makes it easier to track versions and rollback if necessary. +If no issue identifier exists, create the issue before the branch. Incident branches MAY use the approved incident identifier. + +## Creating and updating a branch + +1. Confirm the issue, risk classification, target release, and approved base branch. +2. Fetch the remote and verify the local working tree contains no unrelated changes. +3. Create the branch from the latest approved remote base. +4. Keep the branch current using the repository's documented merge or rebase policy. +5. Never rewrite a shared branch without explicit agreement from all affected contributors. + +Force pushing to protected, release, or shared branches is prohibited. If a private feature branch must be rebased, use a lease-protected force push only when repository policy permits it. + +## Branch lifespan and scope + +- Prefer branches that merge within five working days. Split work that cannot be reviewed safely as one change. +- A branch SHOULD address one issue or one inseparable set of acceptance criteria. +- Do not mix refactors, dependency upgrades, formatting sweeps, and behavior changes unless the issue explicitly requires them. +- Generated files and build artifacts MUST be committed only when repository policy requires them and their provenance is reviewable. +- Delete merged branches unless retention is required for an active release or investigation. + +## Release and hotfix propagation + +Release fixes MUST be merged back to the integration branch so they are not lost. A hotfix MUST be applied to every supported version affected by the defect using reviewed pull requests or an approved, traceable cherry-pick process. + +Do not merge a production branch back blindly when it would include unrelated release-only commits. The release owner MUST choose and document the propagation method. + +## Protection baseline + +Protected integration, release, and production branches MUST enforce, where supported: + +- pull requests before merge; +- at least one independent approval, and two approvals for high-risk changes; +- dismissal or refresh of stale approvals after material changes; +- required CI and security checks; +- resolved review conversations; +- prevention of force pushes and deletion; +- restricted bypass rights with audit logging; +- linear, merge-commit, or squash policy documented per repository; +- signed commits or tags when required by the organizational signing policy. + +Temporary bypasses require a recorded reason, named approver, compensating validation, and retrospective review. diff --git a/Git/Commit Messages.md b/Git/Commit Messages.md index 4007169..8780e96 100644 --- a/Git/Commit Messages.md +++ b/Git/Commit Messages.md @@ -1,34 +1,80 @@ -# Semantic Commit Messages +# Commit Messages -See how a minor change to your commit message style can make you a better programmer. +## Format -Format: `(): ` +Cubewise Asia repositories use Conventional Commit types with the linked issue identifier in the scope: -`` is optional +~~~text +(#): +~~~ -## Example +Examples: -``` -feat: add hat wobble -^--^ ^------------^ -| | -| +-> Summary in present tense. -| -+-------> Type: chore, docs, feat, fix, refactor, style, or test. -``` +~~~text +feat(#484): add RunDoc failure alerts +fix(#870): preserve view alias labels +test(#973): cover sandbox process limits +docs(#102): document secure release evidence +~~~ -More Examples: +When a commit intentionally addresses multiple linked issues, list each identifier only if the repository's established history permits it: -- `feat`: (new feature for the user, not a new feature for build script) -- `fix`: (bug fix for the user, not a fix to a build script) -- `docs`: (changes to the documentation) -- `style`: (formatting, missing semi colons, etc; no production code change) -- `refactor`: (refactoring production code, eg. renaming a variable) -- `test`: (adding missing tests, refactoring tests; no production code change) -- `chore`: (updating grunt tasks etc; no production code change) +~~~text +fix(#574, #594): preserve named-range number formats +~~~ + +## Allowed types + +| Type | Use | +|---|---| +| feat | New user-visible capability. | +| fix | Defect or security correction. | +| docs | Documentation only. | +| test | Test-only change. | +| refactor | Internal restructuring with no intended behavior change. | +| perf | Measured performance improvement. | +| build | Build system or packaging. | +| ci | CI configuration. | +| chore | Maintenance not covered above. | +| revert | Reversal of an earlier commit. | + +Do not use style for a change that also alters behavior. Security fixes use the type that describes the change and are identified through the private issue/advisory process, not by exposing sensitive detail in a public commit message. + +## Subject rules + +The subject MUST: + +- use imperative mood: add, fix, remove; +- describe the outcome, not the editing activity; +- be concise and specific; +- omit a trailing period; +- avoid sensitive customer names, credentials, vulnerability details, and incident data. + +Avoid subjects such as update code, fix issue, changes, or address comments when a more precise outcome can be stated. + +## Commit body + +Add a body when the reason, risk, compatibility impact, or migration is not obvious from the diff. Explain: + +- why the change is necessary; +- important design or security decisions; +- behavior before and after; +- migration, deployment, or rollback constraints; +- known limitations and follow-up work. + +Use issue links and pull requests for detailed evidence rather than copying sensitive logs or data into the commit. + +## Atomicity and history + +- Each commit MUST be buildable or clearly marked as an intermediate commit on a private feature branch that will be squashed. +- Keep unrelated changes in separate commits and pull requests. +- Do not commit formatter output across unrelated files. +- Do not amend, reorder, or remove commits already used by another contributor without coordination. +- Never use history rewriting as the only response to a leaked secret. Revoke or rotate the secret first and follow the incident process. + +Breaking changes MUST use the repository's approved Conventional Commits notation and include migration and rollback guidance in the pull request and release notes. References: -- https://www.conventionalcommits.org/ -- https://seesparkbox.com/foundry/semantic_commit_messages -- http://karma-runner.github.io/1.0/dev/git-commit-msg.html \ No newline at end of file +- [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/) +- [Branch Management](Branch%20Management.md) diff --git a/Git/Development Flow.md b/Git/Development Flow.md index a4d9711..cb78ace 100644 --- a/Git/Development Flow.md +++ b/Git/Development Flow.md @@ -1,21 +1,131 @@ # Development Flow -## Developing New Features/Fixing Bugs -1. **Create an issue** – Start by creating a new issue in the tracking system. -2. **Describe the issue or feature** – Provide a detailed description of the feature to be developed or the bug to be fixed. -3. **Create a branch from the issue page** – The base for this branch should be the `dev` branch, or a specific version branch if the bug fix is for a particular release. -4. **Setup your development environment**: - - Open a terminal on your development machine. - - Navigate to the project folder. - - Run `git fetch`, then `git checkout` to switch to the new branch you just created. -5. **Complete the development** – Once you have implemented the feature or fixed the bug, create a pull request (PR) and assign a reviewer. - -## Reviewing PRs - -### Reviewer Responsibilities -1. **Ensure compatibility** – Check if the PR will cause any issues with the base branch. -2. **Assess code quality** – Evaluate if the code's quality is sufficient to be merged into the base branch. - -### Applier Responsibilities -1. **Test the code** – Ensure the code can be executed, built, compiled, or packaged on your side. -2. **Manage commits** – Check if there are too many commits in a PR. It is recommended to limit the number of commits per PR to maintain clarity and manageability. +## 1. Create the work record + +Every production change MUST link to an approved issue, incident, problem, or change record. The record MUST include: + +- current and expected behavior; +- acceptance criteria and out-of-scope items; +- affected services, customers, interfaces, and supported versions; +- data classification and privacy impact; +- security and operational risks; +- migration, compatibility, monitoring, and rollback expectations. + +Security vulnerabilities MUST use a private reporting channel. Do not create a public issue that exposes exploit details, secrets, customer data, or an unpatched weakness. + +## 2. Classify the change + +### Standard + +A standard change does not alter a trust boundary, authentication, authorization, cryptography, sensitive-data handling, production infrastructure, deployment authority, or externally exposed interface. It requires at least one independent reviewer. + +### High-risk + +A change is high-risk when it affects one or more of the following: + +- authentication, authorization, identity, sessions, API keys, OAuth, SSO, or impersonation; +- secrets, cryptography, TLS, certificates, signing, or key management; +- personal, customer, financial, production, or other sensitive data; +- public endpoints, uploads, archives, templates, parsers, redirects, outbound requests, or command execution; +- database migrations, destructive operations, backups, or recovery; +- CI/CD, release signing, package installation, dependencies, containers, gateways, network rules, or cloud configuration; +- plugins, connectors, MCP tools, AI agents, sandboxing, or code execution; +- a material availability, capacity, concurrency, or multi-service change. + +High-risk changes MUST include a lightweight threat model, explicit abuse cases, security-focused tests, rollback steps, and two independent approvals, including an appropriate maintainer or security reviewer. + +### Emergency + +Emergency changes are limited to active incidents or severe business disruption. They MUST have an incident/change record, named approver, minimal scope, pre-deployment validation proportional to the urgency, rollback instructions, and post-deployment verification. Missing normal controls MUST be recorded and completed through retrospective review within the period defined by the incident process. + +## 3. Design before implementation + +For standard changes, record design decisions in the issue or pull request. For high-risk or cross-service changes, document: + +- assets and data to protect; +- actors and privilege levels; +- entry points and trust boundaries; +- credible misuse and failure scenarios; +- selected controls and residual risk; +- dependency and supplier impact; +- compatibility, migration, deployment order, and rollback. + +Inspect every affected repository for cross-service contracts. Integrated authentication flows MUST be tested through the supported gateway when cookies, SSO, routing, or shared identity are gateway-scoped. + +## 4. Implement on a short-lived branch + +Follow [Branch Management](Branch%20Management.md) and [Engineering Standards](../Engineering/Engineering%20Standards.md). + +- Start from the approved and current base branch. +- Make the smallest change that satisfies the acceptance criteria. +- Preserve architecture, API behavior, input semantics, UX, and compatibility unless the requirement explicitly changes them. +- Do not perform opportunistic refactoring, broad renaming, dependency upgrades, or formatting. +- Treat all external input as hostile and all internal identity assertions as untrusted until verified. +- Add tests with the implementation, not after review finds the gap. +- Update operator and user documentation when behavior, configuration, deployment, or recovery changes. + +## 5. Validate locally + +Run the repository-defined checks. The normal minimum is: + +1. formatter and import ordering; +2. lint and static/type checks; +3. secret and security scans; +4. targeted tests for the changed area; +5. the full automated test suite; +6. frontend build and tests when frontend code changes; +7. migration, packaging, container, or deployment validation when affected; +8. manual or integration validation for behavior that automation cannot prove. + +Review the final diff line by line after tools finish. Confirm there are no unrelated changes, secrets, production data, debug bypasses, disabled checks, generated local files, or unexplained binary artifacts. + +See [Testing and Quality Gates](../Engineering/Testing%20and%20Quality%20Gates.md). + +## 6. Open the pull request + +Use the pull request template. The author MUST provide: + +- linked issue and concise change summary; +- risk classification and threat model where required; +- affected components and interfaces; +- security, privacy, dependency, and data impact; +- exact validation performed and results; +- screenshots or sanitized evidence where relevant; +- migration, deployment, monitoring, and rollback instructions; +- known limitations, residual risks, and follow-up issues. + +Draft pull requests MAY be used for early feedback but MUST NOT be treated as approval evidence. + +## 7. Review and approval + +Reviewers MUST verify the code and evidence, not only the description. At minimum, review: + +- requirement and scope match; +- authentication, authorization, validation, error handling, and logging; +- data handling and secret exposure; +- dependency and supply-chain changes; +- test adequacy, including negative cases; +- migrations, compatibility, deployment order, and rollback; +- documentation and operational observability. + +The author MUST respond to each actionable comment. Material updates invalidate earlier approvals unless the platform re-evaluates them automatically. Review conversations MUST be resolved only after the concern is addressed, rejected with evidence, or moved to an approved follow-up. + +## 8. Merge + +Merge only when: + +- required approvals are present and current; +- all required checks pass on the reviewed commit; +- conflicts are resolved and the base is sufficiently current; +- security exceptions and residual risks have named approval; +- release, migration, and rollback notes are complete. + +Do not merge with skipped, cancelled, stale, or manually overridden checks unless the documented exception or emergency process applies. + +## 9. Release and deploy + +Follow [Release and Version Management](../Version%20Management/Release%20New%20Version.md). Deploy the exact approved artifact, verify health and key business behavior, monitor for regressions, and record the result. A successful command or HTTP response alone is not sufficient evidence when output content or downstream state is the acceptance criterion. + +## 10. Learn and improve + +Defects that escape to production, security incidents, failed releases, recurring flaky tests, and control bypasses MUST produce an appropriate corrective action. Record the root cause, why existing controls did not prevent or detect it, the remediation owner and due date, and how recurrence will be tested. diff --git a/README.md b/README.md new file mode 100644 index 0000000..dfef69e --- /dev/null +++ b/README.md @@ -0,0 +1,125 @@ +# Cubewise Asia Developer Guide + +| Attribute | Value | +|---|---| +| Status | Mandatory engineering standard | +| Owner | Cubewise Asia Engineering | +| Security co-owner | Cubewise Asia ISMS owner | +| Review frequency | At least annually and after a material incident, audit finding, technology change, or change to an applicable requirement | + +## Purpose + +This guide defines the minimum engineering, security, quality, and release controls for software developed or maintained by Cubewise Asia. It is intended to make changes reviewable, reproducible, reversible, and supported by evidence. + +The guide is aligned with the software-development aspects of [ISO/IEC 27001:2022](https://www.iso.org/standard/27001) and its [2024 climate-action amendment](https://www.iso.org/standard/88435.html). It supports the Cubewise Asia Information Security Management System (ISMS); it does not, by itself, establish conformity or certification. Organizational risk assessment, the Statement of Applicability, policies, training, supplier management, incident management, internal audit, and management review remain required outside this repository. + +## Applicability and precedence + +This guide applies to: + +- employees, contractors, reviewers, release owners, and maintainers; +- source code, configuration, infrastructure, build scripts, data migrations, tests, documentation, and deployment artifacts; +- internally developed, customer-specific, open-source, and externally maintained components under Cubewise Asia control; +- human-authored and AI-assisted changes. + +The key words **MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**, and **MAY** are normative. + +Applicable law, contracts, customer requirements, and approved ISMS policies take precedence. Repository-level instructions MAY add stricter or more specific controls, commands, and approval requirements, but MUST NOT silently weaken this baseline. Conflicts MUST be escalated to the repository maintainer and ISMS owner before work continues. + +## Non-negotiable controls + +Every change MUST satisfy all applicable controls below: + +1. Start from an approved issue, incident, or change record with acceptance criteria. +2. Classify the change risk before implementation and record security, privacy, and operational impact. +3. Work on a short-lived branch; do not commit directly to a protected integration, release, or production branch. +4. Keep the change minimal and preserve existing behavior unless the approved requirement changes it. +5. Never commit secrets, credentials, tokens, private keys, customer data, production data, or unredacted security evidence. +6. Enforce authentication and authorization on the server side, use least privilege, and fail closed. +7. Add or update tests for changed behavior, including negative and abuse cases where relevant. +8. Run repository-defined formatting, linting, type checks, security checks, builds, migrations, and tests before review. +9. Use a pull request with independent review. The author MUST NOT be the sole approver. +10. Record validation evidence, deployment impact, and rollback steps in the pull request or linked change record. +11. Release only from an approved commit and preserve traceability from issue to commit, pull request, artifact, deployment, and rollback decision. +12. Report suspected security incidents immediately through a private approved channel. Do not investigate in a way that destroys evidence or broadens exposure. + +Exceptions MUST be explicit, risk-assessed, time-bound, approved by the accountable engineering owner and ISMS owner, and accompanied by compensating controls and an expiry or remediation issue. Schedule pressure is not an exception. + +## Roles and segregation of duties + +| Role | Minimum responsibility | +|---|---| +| Requester / Product Owner | Define the business need, acceptance criteria, data sensitivity, and priority. | +| Developer | Assess risk, implement the smallest safe change, test it, document evidence, and disclose limitations. | +| Reviewer | Independently verify correctness, security, test adequacy, scope, and rollback safety. | +| Maintainer | Enforce repository controls, branch protection, required checks, ownership, and merge policy. | +| Security / ISMS Owner | Approve security exceptions, guide incident handling, and maintain ISMS control applicability. | +| Release Owner | Verify release evidence, artifact provenance, approvals, deployment readiness, and rollback capability. | + +One person MAY hold more than one role for low-risk work, but no author may independently approve and release a security-sensitive or high-risk change. Emergency access and emergency merges require retrospective independent review. + +## Standard workflow + +1. Create or confirm the issue and acceptance criteria. +2. Classify the change as standard, high-risk, or emergency. +3. Identify affected assets, data, trust boundaries, dependencies, and rollback constraints. +4. Create a branch from the repository's approved base. +5. Implement a focused change using the repository's established architecture and tools. +6. Run local checks and inspect the final diff for secrets, unrelated changes, and generated artifacts. +7. Open a pull request using the repository template and attach reproducible evidence. +8. Resolve review findings and rerun affected checks after every material update. +9. Merge only when approvals and required checks are current and successful. +10. Release and deploy through the approved process, verify the result, and retain evidence. + +See [Development Flow](Git/Development%20Flow.md) for the complete lifecycle. + +## Guide index + +### Git and change management + +- [Branch Management](Git/Branch%20Management.md) +- [Commit Messages](Git/Commit%20Messages.md) +- [Development Flow](Git/Development%20Flow.md) + +### Engineering quality + +- [Engineering Standards](Engineering/Engineering%20Standards.md) +- [Testing and Quality Gates](Engineering/Testing%20and%20Quality%20Gates.md) + +### Security and data protection + +- [Secure Development Standard](Security/Secure%20Development%20Standard.md) +- [Secrets and Data Handling](Security/Secrets%20and%20Data%20Handling.md) +- [Security Reporting](SECURITY.md) + +### Release and compliance + +- [Release and Version Management](Version%20Management/Release%20New%20Version.md) +- [ISO/IEC 27001 Control Mapping](Compliance/ISO%20IEC%2027001%20Mapping.md) + +## Repository-specific baseline + +The following Cubewise Asia repositories informed this guide: + +- [cubewise_distro](https://github.com/Cubewise-Asia/cubewise_distro): a dev-based workflow, Python 3.12 and Node 22 targets, YAPF/isort/pre-commit checks, TypeScript checks, unit tests, secret detection, and versioned release branches. +- [olap_extend](https://github.com/Cubewise-Asia/olap_extend): a dev-based workflow, frontend builds, isolated Python test suites, and dedicated security regression coverage for authentication, authorization, sessions, OAuth, supply-chain inputs, sandboxing, and secret scanning. +- [fastapi_template](https://github.com/Cubewise-Asia/fastapi_template): the baseline Python service layout, editable development installation, pyproject.toml configuration, YAPF/isort/pre-commit, external configuration, and packaging conventions. + +These repositories are implementation references, not evidence that every historical implementation satisfies every control in this guide. Repository-specific commands and architecture remain authoritative for that repository. + +## Required evidence + +Git history, pull requests, reviews, required-check results, release records, risk acceptances, and incident records are controlled records. They MUST be accurate, access-controlled, retained according to the approved retention policy, and never fabricated or edited to hide a failure. + +At minimum, a pull request MUST preserve: + +- the linked issue or change record; +- the risk classification and security/privacy assessment; +- the reviewed diff and reviewer identity; +- commands or jobs run and their results; +- migration, deployment, monitoring, and rollback notes where applicable; +- accepted exceptions, residual risks, and follow-up issues. + +## Maintaining this guide + +Changes to mandatory controls require an issue, impact assessment, independent Engineering review, and ISMS-owner review. Control-removal changes MUST explain the risk, replacement control, affected repositories, and transition plan. Editorial corrections MAY use the standard documentation workflow. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..9f584fe --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,52 @@ +# Security Policy and Vulnerability Reporting + +## Report privately + +Do not open a public issue, discussion, or pull request for a suspected unpatched vulnerability, exposed secret, customer-data disclosure, or active security incident. + +Use one of these private paths: + +- Cubewise Asia personnel: the approved internal security/incident channel and the responsible engineering manager or ISMS owner. +- Customers and partners: the existing contractual Cubewise support channel. +- External reporters: GitHub Private Vulnerability Reporting through the repository's **Security** tab when enabled; otherwise use the [Cubewise contact form](https://cubewise.com/contact-us/) and request a private security-reporting channel without including exploit details in the initial message. + +If there is immediate risk of active compromise, state that clearly through the private channel so the incident process can begin without waiting for a complete technical report. + +## Include + +Provide only through the approved private channel: + +- affected repository, product, version, commit, endpoint, or component; +- a concise description of the weakness and potential impact; +- prerequisites and reproducible steps or a minimal proof of concept; +- whether exploitation or data exposure has been observed; +- suggested mitigation if known; +- your preferred contact method. + +Minimize personal and customer data. Redact credentials, tokens, private keys, and unrelated log content. Do not send live secrets when a fingerprint, identifier, or sanitized excerpt is sufficient. + +## Handling expectations + +The receiving team will follow the approved incident and vulnerability-management process to: + +1. acknowledge and protect the report according to the applicable service level; +2. triage severity, exploitability, affected versions, customers, and data; +3. contain active exposure and preserve evidence; +4. assign remediation, validation, release, and communication owners; +5. coordinate disclosure and customer communication; +6. record lessons learned and corrective actions. + +Do not promise a public disclosure date, severity, bounty, or fix timeline unless authorized to do so. + +## Safe handling by developers + +- Restrict issue, branch, CI, artifact, and log access to the response team. +- Use neutral commit and release wording until disclosure is approved. +- Never copy sensitive evidence into a public fork or personal repository. +- Add regression tests that demonstrate the control without publishing a practical exploit prematurely. +- Revoke or rotate exposed secrets; Git history cleanup alone is not containment. +- Coordinate backports across all affected maintained versions. + +## Public disclosure + +Public advisories and technical details require approval from the incident/vulnerability owner and relevant legal, customer, and ISMS stakeholders. Credit to a reporter is provided only with their consent and according to the approved disclosure process. diff --git a/Security/Secrets and Data Handling.md b/Security/Secrets and Data Handling.md new file mode 100644 index 0000000..d397e50 --- /dev/null +++ b/Security/Secrets and Data Handling.md @@ -0,0 +1,100 @@ +# Secrets and Data Handling + +## Classification + +Use the approved Cubewise Asia information-classification and handling policy. If a repository has no recorded classification, use the conservative defaults below until the information owner classifies it. + +| Default class | Examples | Minimum handling | +|---|---|---| +| Public | Approved public documentation and open-source content | Verify publication approval and remove non-public metadata. | +| Internal | Non-public source code, routine internal architecture, development notes | Approved company systems and identities; no public sharing. | +| Confidential | Customer configurations, contracts, non-public product plans, sanitized-but-linkable operational data | Need-to-know access, approved encrypted storage/transfer, controlled retention. | +| Restricted | Passwords, API keys, tokens, private keys, production/customer data, sensitive personal data, unpatched vulnerability details, incident evidence | Explicit authorization, strongest approved storage and transfer, minimal access and retention, no repository storage. | + +Customer, legal, privacy, and contractual classification overrides these defaults. When uncertain, handle the information as Restricted and ask the information owner or ISMS owner. + +## What is a secret + +Secrets include credentials or material that grants, derives, signs, decrypts, or impersonates access, including: + +- passwords, API keys, access and refresh tokens, cookies, session identifiers, and one-time codes; +- private keys, client secrets, signing keys, encryption keys, recovery codes, and certificate bundles containing private material; +- database, SMTP, cloud, SFTP, TM1, OAuth, webhook, and service-account credentials; +- live license material when it contains entitlement or identity secrets; +- complete connection strings, URLs with embedded credentials, and sensitive environment exports. + +Placeholders and documented dummy values MUST be obviously non-functional and MUST NOT resemble a real secret format closely enough to trigger accidental use. + +## Storage and configuration + +- Store secrets only in an approved secret manager, key vault, CI secret store, or protected local mechanism. +- Commit safe .env.example or configuration templates with placeholders, never a populated .env, config.ini, local database, token file, license file, or reference note containing live values. +- Add local secret-bearing paths to .gitignore, but do not rely on ignore rules as the security control. +- Separate secrets by environment and purpose. Development credentials MUST NOT grant production access. +- Limit secret access to the smallest set of people and workloads; review and revoke access when roles change. +- Rotate secrets on the approved schedule and immediately after suspected exposure, unauthorized access, or ownership change. +- Do not hard-code a fallback, default administrator password, shared production secret, or predictable generated token. + +Local developer reference files MUST use environment-variable names or placeholders. A file being ignored by Git does not authorize storing shared plaintext credentials in it. + +## Use in code and automation + +- Read secrets at runtime through the approved provider and keep them out of source, images, packages, caches, and generated frontend bundles. +- Never expose server secrets to browser code. +- Do not pass secrets through command-line arguments when process listings, shell history, CI logs, or audit tools can reveal them. +- Pass only required secret values to a process; do not inherit the entire parent environment. +- Redact authorization headers, cookies, tokens, connection strings, and sensitive payload fields before logging or attaching evidence. +- Do not include secrets in exceptions, metrics labels, traces, screenshots, test snapshots, prompts, comments, commit messages, issues, pull requests, or release notes. +- Compare, store, cache, and delete secrets using approved libraries and lifecycle controls. + +## Source and commit checks + +Before each commit and pull request: + +1. inspect staged and unstaged changes; +2. run the repository's secret scanner and pre-commit hooks; +3. inspect new binaries, archives, images, notebooks, fixtures, databases, and generated files; +4. verify examples contain only non-functional placeholders; +5. verify deleted secrets have been revoked or rotated if they were ever committed or shared. + +Secret-scanner baselines MUST contain only reviewed false positives. Never add a real secret to a baseline or broad exclusion. New suppressions require a justification in the pull request. + +## Production and customer data + +- Use synthetic data for development and automated tests whenever possible. +- Access to production or customer data requires an approved purpose, named owner, least privilege, time limit, and auditable method. +- Copying production data to a developer device, personal cloud, unmanaged tool, public issue, or AI service is prohibited. +- When realistic data is essential, use an approved masked or anonymized dataset and verify that re-identification risk is acceptable. +- Remove direct identifiers and sensitive free text; simple substitution or truncation may not be sufficient anonymization. +- Test datasets MUST follow retention and deletion requirements and MUST NOT be kept indefinitely for convenience. +- Screenshots and screen recordings MUST be reviewed for customer names, usernames, URLs, tokens, browser storage, notifications, and background windows. + +## Transfer and sharing + +- Use approved encrypted channels and authenticated recipients. +- Verify the recipient, destination, classification, purpose, and minimum necessary content before transfer. +- Do not use public paste sites, personal email, consumer storage, public chat rooms, or URL query strings for non-public data. +- Apply expiration, download restrictions, and access review where the approved platform supports them. +- Record transfers when required by the data owner, contract, privacy process, or incident process. + +## Retention and deletion + +- Retain information only for the approved business, legal, contractual, support, or security purpose. +- Define retention for logs, test data, exports, backups, artifacts, recordings, and incident evidence. +- Delete data through the approved process, including temporary files, caches, replicas, exported copies, and queued work where applicable. +- Preserve information subject to legal hold or incident evidence requirements; do not delete it through routine cleanup. +- Verify deletion outcomes for sensitive or customer data when the requirement calls for proof. + +## Suspected exposure + +If a secret or Restricted data may have been exposed: + +1. stop further disclosure without destroying evidence; +2. report immediately through the private security/incident channel; +3. revoke or rotate affected credentials and invalidate active sessions as directed; +4. preserve relevant timestamps, commit SHAs, audit logs, destinations, and access evidence; +5. assess repositories, forks, caches, artifacts, CI logs, packages, messages, and downstream systems; +6. remove exposed material using the incident owner's approved method; +7. add detection and regression controls and record corrective actions. + +Deleting a file, closing a pull request, or rewriting Git history does not remove copies and is not sufficient containment. diff --git a/Security/Secure Development Standard.md b/Security/Secure Development Standard.md new file mode 100644 index 0000000..31304be --- /dev/null +++ b/Security/Secure Development Standard.md @@ -0,0 +1,170 @@ +# Secure Development Standard + +## Security objectives + +Software MUST preserve the confidentiality, integrity, availability, authenticity, accountability, and privacy of information according to its approved risk assessment. Security is part of design, implementation, testing, review, release, operation, and retirement. + +This standard defines minimum engineering controls. The organization's risk assessment and Statement of Applicability determine which ISO/IEC 27001 controls apply and whether stronger controls are required. + +## Security requirements and threat modeling + +Every issue MUST consider security and privacy impact. High-risk changes require a lightweight threat model that records: + +- protected assets and data classification; +- actors, identities, roles, tenants, and privileges; +- entry points, trust boundaries, data flows, and external dependencies; +- credible misuse, tampering, disclosure, denial-of-service, and privilege-escalation scenarios; +- preventive, detective, and recovery controls; +- residual risk, owner, and approval. + +Reuse the system's established security architecture. A new authentication mode, cryptographic scheme, trust boundary, external execution path, or security bypass requires an architecture/security review before implementation. + +## Authentication, sessions, and authorization + +- Use an approved centralized identity mechanism. Do not build custom password storage, token formats, or authentication protocols when an approved implementation exists. +- Store passwords only with an approved adaptive password-hashing algorithm and parameters. Never store or log plaintext or reversibly encrypted passwords. +- Enforce authorization server-side for the action and resource on every request and tool call. +- Deny by default. A permission lookup, identity provider, policy engine, or dependency failure MUST fail closed. +- Prevent horizontal and vertical privilege escalation, cross-user access, cross-tenant access, and mass assignment. +- Use least privilege for users, service identities, CI tokens, database accounts, containers, and external integrations. +- Protect session and refresh tokens with appropriate expiry, rotation, revocation, replay detection, audience/issuer checks, and identity binding. +- Use secure, HTTP-only cookies and an appropriate SameSite policy when HTTPS is enabled. Do not let login, refresh, logout, or sibling services disagree on cookie scope or security attributes. +- Protect state-changing browser requests against CSRF. CORS is not a CSRF control and MUST use explicit approved origins. +- Require stronger authentication and explicit audit for privileged or destructive operations where the risk assessment requires it. +- Compare authentication secrets using an approved constant-time method where relevant. + +## Input validation and output safety + +- Define an allowlist-based schema at each trust boundary. Validate type, length, range, format, encoding, multiplicity, and relationships. +- Reject malformed, ambiguous, duplicate, unexpected, or oversized input. Do not silently coerce security-relevant values. +- Use parameterized database access. Never construct queries by concatenating untrusted input. +- Do not pass untrusted values to a shell. Use argument arrays, strict allowlists, a minimal environment, an unprivileged identity, resource limits, and timeouts when a subprocess is necessary. +- Encode output for its destination. Use framework-safe HTML rendering and sanitize only with an approved library when rich HTML is required. +- Prevent formula injection when exporting untrusted values to CSV or spreadsheets. +- Return safe client errors. Keep stack traces, internal paths, queries, credentials, and implementation details out of responses. + +## URLs, redirects, and outbound requests + +- Validate protocol, host, port, path, and resolved destination for outbound requests. +- Use explicit allowlists for OAuth redirects, callbacks, webhooks, proxy targets, and administrative integrations. +- Block loopback, link-local, private, metadata-service, and otherwise prohibited destinations unless the documented feature explicitly requires and authorizes them. +- Revalidate destinations after redirects and DNS resolution where SSRF risk exists. +- Apply connection and read timeouts, response size limits, redirect limits, and bounded retries. +- Do not place secrets in URLs because URLs may be retained in logs, browser history, referrers, and proxies. + +## Files, archives, and generated documents + +- Treat filenames, paths, MIME types, extensions, document metadata, templates, and archive entries as untrusted. +- Generate server-side storage names and keep uploads outside executable or web-served locations unless explicitly required. +- Prevent absolute paths, traversal, symlinks/hardlinks, device files, overwrite, extension confusion, and case-collision attacks. +- Limit compressed and expanded size, file count, nesting, dimensions, execution time, and memory use. +- Validate content using an approved parser; a client-supplied MIME type or extension is not proof. +- Write through a temporary location and atomically move only after complete validation. Clean up on error and cancellation. +- Scan uploads and third-party artifacts for malware where the risk assessment requires it. +- Validate generated Office, PDF, image, and archive content, not only file existence. + +## Data protection + +- Collect and retain only data required for the approved purpose. +- Apply classification, masking, minimization, retention, deletion, and transfer rules from [Secrets and Data Handling](Secrets%20and%20Data%20Handling.md). +- Enforce tenant and record-level access in queries, exports, caches, queues, and background work. +- Encrypt sensitive data in transit and at rest according to the organizational cryptography standard and risk assessment. +- Do not copy production or customer data into development, tests, screenshots, prompts, logs, or tickets without explicit approval and effective sanitization. +- Design deletion so replicas, caches, indexes, exports, temporary files, and backups are handled according to retention requirements. + +## Cryptography and TLS + +- Use approved, maintained libraries and platform services. Do not invent algorithms, protocols, key derivation, signing, or random-number generation. +- Keys and certificates MUST have documented ownership, purpose, environment, access, rotation, expiry, revocation, backup/recovery, and destruction. +- Use cryptographically secure random generation for tokens, keys, nonces, and security identifiers. +- Verify TLS certificates and hostnames. Disabling verification MUST NOT be a production default and requires a time-bound, documented non-production exception. +- Do not downgrade to plaintext or weak algorithms when secure configuration is missing. Fail closed with an actionable, non-sensitive error. +- Keep signing and encryption keys separate by purpose and environment. + +## Logging, monitoring, and errors + +Log security-relevant events needed for detection and investigation, including authentication outcomes, authorization denials, privileged changes, security configuration changes, key lifecycle events, and administrative data export or deletion. + +Logs MUST: + +- use synchronized timestamps and a safe correlation identifier; +- identify the event and outcome without recording secrets or excessive personal data; +- be access-controlled, integrity-protected, retained, and monitored according to policy; +- distinguish expected client errors from security events and unexpected server failures; +- avoid passwords, tokens, API keys, cookies, authorization headers, private keys, full connection strings, sensitive payloads, and unredacted customer data. + +Do not catch broad exceptions and report success. Ensure failed security checks and partial operations cannot leave an unsafe state. Alerting MUST avoid creating a second leak through email, chat, or third-party monitoring. + +## Capacity, resilience, and concurrency + +- Bound request bodies, queries, pagination, queues, threads, processes, browsers, retries, timeouts, and generated output. +- Apply rate limits and quotas appropriate to identity, tenant, operation cost, and abuse risk. +- Make retries safe with idempotency or duplicate detection where a repeated operation can create harm. +- Release resources on timeout, cancellation, disconnect, exception, and shutdown. +- Design critical services with backup, recovery, and redundancy consistent with recovery objectives. +- Test degradation and recovery, not only the happy path. + +## Dependencies and software supply chain + +Before adding or updating a dependency, package, container image, CI action, plugin, connector, wheel, browser, or binary: + +1. verify the official source, maintainer, integrity, version, and license; +2. assess necessity, maintenance activity, known vulnerabilities, transitive dependencies, and install/build behavior; +3. pin through the repository's lock or constraints mechanism; +4. review unexpected changes in the lockfile and generated metadata; +5. run vulnerability, license, and secret scans appropriate to the artifact; +6. record approval and remediation for unresolved material risk. + +Use approved registries and indexes. Do not install from unreviewed forks, personal repositories, arbitrary URLs, or ambiguous package names. Prevent dependency confusion through scoped names, index configuration, and internal package controls. + +Maintainers MUST monitor relevant vendor advisories and threat intelligence, triage vulnerabilities based on exploitability and business exposure, and track remediation or risk acceptance. Critical fixes follow the incident and emergency-change process. + +Release artifacts SHOULD include a software bill of materials when required by product policy, customer contract, or risk assessment. Preserve source commit, build environment, dependency resolution, checksums, and signing/provenance data. + +## CI/CD and deployment security + +- CI and deployment identities MUST use least privilege, short-lived credentials where supported, and separate permissions by environment. +- Untrusted pull-request code MUST NOT gain access to protected secrets or production deployment authority. +- Protect workflow files, build definitions, release scripts, and branch/ruleset configuration as security-sensitive code. +- Use reviewed and pinned build tools, actions, images, and runners. +- Build releases from an approved clean commit. Do not release uncommitted local changes. +- Separate development, test, staging, and production data, credentials, networks, and approval paths. +- Promote the same immutable artifact across environments rather than rebuilding different content for production. +- Require explicit approval for production deployment and destructive operations. +- Record who deployed what artifact, when, where, with which result and rollback decision. +- Verify a deployment through health, security, and critical business behavior; do not rely solely on process startup. + +If an offline or workstation build is unavoidable, the release record MUST capture the approved exception, clean source SHA, builder identity, tool versions, commands, dependency source, artifact hashes, malware scan, and independent verification. + +## Plugins, connectors, MCP tools, and executable extensions + +- Treat third-party and user-supplied extensions as untrusted code. +- Validate manifest, provenance, signature/hash, compatibility, declared permissions, dependency set, file layout, and entry point before installation. +- Run with the minimum filesystem, network, process, environment, identity, and tool permissions. +- Enforce authorization at tool invocation time, not only during discovery or UI filtering. +- Pass an allowlisted environment and prevent inherited secrets. +- Bound execution time, output, process count, memory, CPU, and descendant processes; terminate the full process tree on timeout. +- Prevent path traversal, symlink escape, unsafe archive extraction, and replacement races during installation. +- Log installation and execution outcomes without recording inputs or outputs that contain sensitive data. + +## AI and LLM features + +- Classify prompts, retrieved context, tool input/output, conversation history, model logs, and embeddings as application data. +- Send data only to approved providers, models, regions, and accounts under the required contract and retention terms. +- Minimize and redact context; never place secrets in prompts or tool descriptions. +- Treat model output as untrusted input. Validate schemas, permissions, destinations, commands, paths, queries, and side effects before use. +- Require user confirmation or policy approval for destructive, privileged, external-message, financial, or data-export actions. +- Defend against prompt injection by separating instructions from data and enforcing authorization outside the model. +- Provide timeouts, rate/cost limits, auditability, safe failure, and a way to disable model/tool access. + +## Vulnerability and incident handling + +Follow [Security Reporting](../SECURITY.md). Developers MUST NOT: + +- open a public issue for an unpatched vulnerability; +- include exploit detail or sensitive evidence in commit messages or public pull requests; +- delay reporting while attempting a complete investigation; +- delete or rewrite evidence without incident-owner approval; +- treat removal from Git history as a substitute for secret rotation or incident assessment. + +After containment, add regression coverage and update threat models, standards, monitoring, or training when the root cause shows a control gap. diff --git a/Version Management/Release New Version.md b/Version Management/Release New Version.md index b3a667e..28c3dac 100644 --- a/Version Management/Release New Version.md +++ b/Version Management/Release New Version.md @@ -1,39 +1,143 @@ -# Version Management +# Release and Version Management -## Version Naming Rule +## Objectives -- `x.y.z` Format - - `x` => Major Version - - `y` => Minor Version - - `z` => Patch Version +A release MUST be identifiable, reproducible, approved, tested, recoverable, and traceable to its source, dependencies, build, deployment, and change records. -## Release Version Flow +## Versioning -_Follow this flow to release our product:_ +Use Semantic Versioning unless the product has an approved alternative: -1. Create a new branch named after the version, e.g., `v2.0.0`. -2. Modify `file_version_info.txt`: - - `filevers` - - `prodvers` - - `FileVersion` - - `ProductVersion` -3. Update the version in the version API. -4. Commit the changes with the message: "Version x.x.x". -5. Tag the commit, e.g., `git tag v2.0.0`. -6. Push the branch from local to remote. -7. Create a release note. +~~~text +MAJOR.MINOR.PATCH +~~~ -## Major Version +- **MAJOR** — an incompatible public contract, data, deployment, or support change; +- **MINOR** — backward-compatible functionality; +- **PATCH** — backward-compatible defect or security correction. -- Release a major version only with significant new features. -- Needs to be merged into the main branch. +Pre-release identifiers such as -rc.1 MAY be used for release candidates. Build metadata MUST NOT be used as a substitute for source and artifact provenance. -## Minor Version +Version changes MUST follow behavior and compatibility impact. Do not increment a minor version merely because a patch count reached an arbitrary threshold. -- Release a minor version when: - - Merging the dev branch with the version's branch. - - The patch version number exceeds 5. +## Version sources -## Patch Version +Each repository MUST identify its authoritative version source and every derived location. Depending on the product, these may include: -- Used for bug fixes on the current version. +- file_version_info.txt fields such as filevers, prodvers, FileVersion, and ProductVersion; +- API or runtime constants; +- Python or Node package metadata; +- installer, container, chart, and release metadata; +- user-visible About or version endpoints. + +The release check MUST verify that all required locations agree. Prefer generating derived values from one authoritative source rather than manually maintaining duplicates. + +## Release branches and tags + +Follow the repository's established convention. Cubewise Asia product repositories commonly integrate through dev, stabilize on a version branch such as V5.1.0, and promote to main or master. + +- Create the release branch from the approved integration commit. +- Limit release-branch changes to approved release fixes, version metadata, release notes, and packaging. +- Apply release fixes back to dev and other affected maintained branches. +- Create an annotated tag such as v5.1.0 on the exact approved release commit. +- Sign tags and artifacts when the organizational signing policy or customer requirement applies. +- Never move or reuse a published release tag. Correct it with a new version. + +## Release readiness record + +Before building, the release owner MUST confirm: + +- approved scope and linked issues/pull requests; +- supported platforms, upgrade paths, and affected customers; +- security/privacy review and unresolved vulnerability disposition; +- successful required checks on the release commit; +- migration rehearsal and backup/recovery readiness where applicable; +- dependency lock, license review, vulnerability scan, and software bill of materials where required; +- release notes, operator instructions, compatibility notes, and known limitations; +- deployment order, monitoring, rollback trigger, and rollback/forward-fix procedure; +- named approvers and separation of build/deploy authority appropriate to risk. + +Known failed checks, unpatched vulnerabilities, or incomplete acceptance criteria require an explicit recorded risk decision. The release record MUST NOT present a partial validation as a pass. + +## Build and artifact controls + +- Build from a clean checkout of the approved tagged commit. +- Use reviewed build definitions, locked dependencies, approved registries, and a controlled builder. +- Prefer CI-produced immutable artifacts. Do not rebuild different content for later environments. +- Prevent untrusted pull-request code from accessing release credentials or signing material. +- Capture source SHA, version, timestamp, builder/workflow identity, toolchain, dependency resolution, artifact name, size, and cryptographic checksum. +- Scan relevant artifacts for malware, secrets, vulnerable components, and prohibited files. +- Validate that packages, installers, containers, static bundles, and API/UI version outputs contain the expected version. +- Store artifacts in an approved access-controlled repository with retention and immutability appropriate to the product. + +For an approved offline or workstation build, record the exception and reproduce the same evidence, including the clean source status and independent checksum verification. + +## Release validation + +Validate the exact packaged artifact in a release-like environment: + +1. clean install and supported upgrade; +2. configuration migration and security-critical startup validation; +3. health/readiness and version endpoints; +4. authentication, authorization, and critical user journeys; +5. database migration and application compatibility; +6. external integration and gateway behavior where applicable; +7. logs, metrics, alerts, backup, recovery, and operational procedures; +8. artifact content, generated files, or downstream state required by acceptance criteria; +9. rollback or forward-fix procedure. + +Use synthetic or approved non-production data. Sanitize evidence before attaching it to a release record. + +## Release notes + +Release notes MUST include: + +- version and release date; +- user-visible features and fixes; +- security fixes using disclosure-approved wording; +- breaking changes and deprecations; +- configuration, migration, deployment, and rollback actions; +- compatibility and supported-version changes; +- known issues and material residual risks; +- checksums or artifact-verification instructions when distributed directly. + +Do not disclose an exploitable weakness before coordinated disclosure approval. + +## Deployment + +- Deploy the exact approved artifact through the approved identity and environment path. +- Require explicit production approval and record the actor, environment, artifact digest, start/end time, and result. +- Back up affected state before an irreversible migration. +- Execute documented post-deployment health, security, and business checks. +- Monitor the defined error, latency, capacity, security, and business indicators for the planned observation period. +- Stop or roll back when a documented threshold is crossed; do not continue solely to protect the schedule. + +## Rollback and recovery + +Every material release MUST define: + +- the decision owner and trigger; +- last known good artifact and configuration; +- data and schema compatibility constraints; +- backup and restore location and verification; +- commands or automation to revert; +- validation after rollback; +- communication and evidence requirements. + +When database or data changes cannot safely roll back, document and test a forward-fix or restore strategy before release. + +## Hotfixes + +Hotfixes follow the emergency flow in [Development Flow](../Git/Development%20Flow.md): + +1. create the incident/change record and identify affected supported versions; +2. branch from the affected production tag or protected branch; +3. implement the smallest safe correction and regression test; +4. obtain the required emergency approval and run proportionate checks; +5. build, verify, deploy, and monitor a new patch version; +6. merge or cherry-pick the fix back to all affected maintained branches through reviewed pull requests; +7. complete retrospective review and corrective actions. + +## Retirement + +End-of-life decisions MUST define customer communication, support dates, dependency and vulnerability handling, data export/return, secure deletion, credential revocation, DNS/certificate cleanup, artifact retention, and archival ownership. diff --git a/python-guide-ist.md b/python-guide-ist.md deleted file mode 100644 index ff2bf62..0000000 --- a/python-guide-ist.md +++ /dev/null @@ -1,358 +0,0 @@ -# A Guide of Best Practices for Python - -A guide of best practices to developing in Python (meant for the first year students of the [Instituto Superior Técnico](https://www.tecnico.ulisboa.pt/), -[University of Lisbon](https://www.ulisboa.pt/pt/)). Do you want to have a hard-cover book on this, check this [list](https://hub.packtpub.com/top-7-python-programming-books-need-to-read/) out. - -Inspired in Steve Sloria's [gist](https://gist.github.com/sloria/7001839). - -## In General - -> "Beautiful is better than ugly." - [PEP 20][] - - -### General Development Guidelines - -- "Explicit is better than implicit" - [PEP 20][] -- "Readability counts." - [PEP 20][] -- "Anybody can fix anything." - [Khan Academy Development Docs][] -- Fix each issue (bad design, wrong decision, or poor code) *as soon as it is discovered*. -- "Now is better than never." - [PEP 20][] -- Test ruthlessly. Write docs for new features. -- Even more important that Test-Driven Development--*Human-Driven Development* -- These guidelines may--and probably will--change. - -## In Particular - -### Style - -Follow [PEP 8][], when sensible. - -#### Naming - -- Variables, functions, methods, packages, modules - - `lower_case_with_underscores` -- Classes and Exceptions - - `CapWords` -- Protected methods and internal functions - - `_single_leading_underscore(self, ...)` -- Private methods - - `__double_leading_underscore(self, ...)` -- Constants - - `ALL_CAPS_WITH_UNDERSCORES` - -###### General Naming Guidelines - -Avoid one-letter variables (esp. `l`, `O`, `I`). - -*Exception*: In very short blocks, when the meaning is clearly visible from the immediate context - -**Fine** -```python -for e in elements: - e.mutate() -``` - -Avoid redundant labeling. - -**Yes** -```python -import audio - -core = audio.Core() -controller = audio.Controller() -``` - -**No** -```python -import audio -from audio import * - -core = audio.AudioCore() -controller = audio.AudioController() -``` - -Prefer "reverse notation". - -**Yes** -```python -elements = ... -elements_active = ... -elements_defunct = ... -``` - -**No** -```python -elements = ... -active_elements = ... -defunct_elements ... -``` - -#### Indentation - -Up to you, but be consistent. [Enough said](https://thenewstack.io/spaces-vs-tabs-a-20-year-debate-and-now-this-what-the-hell-is-wrong-with-go/). - -![Alt Text](https://media.giphy.com/media/l0IylSajlbPRFxH8Y/giphy.gif) - -However, note that: A tab could be a different number of columns depending on your environment, but a space is always one column. In terms of how many spaces (or tabs) constitutes indentation, it's more important to be consistent throughout your code than to use any specific tab stop value. - -#### Equality checking - -Avoid comparing to `True`, `False` or `None`. - -**Yes** -```python -if attr: - print('True!') - -if attr is True: - print('True!') - -if not attr: - print('False!') - -if attr is None: - print('None') -``` - -**No** - -```python -if attr == True: - print('True!') - -if attr == False: - print('False!') - -if attr == None: - print('None') -``` - -#### List comprehensions - -Use list comprehension when possible. - -**Yes** -```python -a = [3, 4, 5] -b = [i for i in a if i > 4] - -#Or (filter is this case; map could also be more appropriate in other cases) -b = filter(lambda x: x > 4, a) -``` - -**No** - -```python -a = [3, 4, 5] -b = [] -for i in a: - if i > 4: - b.append(i) -``` - -#### Keyword `with` and files - -The `with` statement ensures that clean-up code is executed. When opening a file, `with` will make sure that the file is closed after the `with` block. - -**Yes** -```python -with open('file.txt') as f: - do_something_with_f -``` - -#### Imports - -Import entire modules instead of individual symbols within a module. For example, for a top-level module `canteen` that has a file `canteen/sessions.py`, - -**Yes** - -```python -import canteen -import canteen.sessions -from canteen import sessions -``` - -**No** - -```python -from canteen import get_user # Symbol from canteen/__init__.py -from canteen.sessions import get_session # Symbol from canteen/sessions.py -``` - -*Exception*: For third-party code where documentation explicitly says to import individual symbols. - -*Rationale*: Avoids circular imports. See [here](https://stackabuse.com/python-circular-imports/). - -Put all imports at the top of the page with three sections, each separated by a blank line, in this order: - -1. System imports -2. Third-party imports -3. Local source tree imports - -*Rationale*: Makes it clear where each module is coming from. - -#### Documentation - -Follow [PEP 257][]'s docstring guidelines. [reStructured Text](http://docutils.sourceforge.net/docs/user/rst/quickref.html) and [Sphinx](http://sphinx-doc.org/) can help to enforce these standards. - -When possible, use one-line docstrings for obvious functions. - -```python -"""Return the pathname of ``foo``.""" -``` - -Multiline docstrings should include - -- Summary line -- Use case, if appropriate -- Args -- Return type and semantics, unless ``None`` is returned - -```python -"""Train a model to classify Foos and Bars. - -Usage:: - - >>> import klassify - >>> data = [("green", "foo"), ("orange", "bar")] - >>> classifier = klassify.train(data) - -:param train_data: A list of tuples of the form ``(color, label)``. -:rtype: A :class:`Classifier ` -""" -``` - -Notes - -- Use action words ("Return") rather than descriptions ("Returns"). -- Document `__init__` methods in the docstring for the class. - -```python -class Person(object): - """A simple representation of a human being. - - :param name: A string, the person's name. - :param age: An int, the person's age. - """ - def __init__(self, name, age): - self.name = name - self.age = age -``` - -##### On comments - -Use them sparingly. Prefer code readability to writing a lot of comments. Often, small methods are more effective than comments. - -*No* - -```python -# If the sign is a stop sign -if sign.color == 'red' and sign.sides == 8: - stop() -``` - -*Yes* - -```python -def is_stop_sign(sign): - return sign.color == 'red' and sign.sides == 8 - -if is_stop_sign(sign): - stop() -``` - -When you do write comments, remember: "Strunk and White apply." - [PEP 8][] - -#### Line lengths - -Don't stress over it. 80-100 characters is fine. - -Use parentheses for line continuations. - -```python -wiki = ( - "The Colt Python is a .357 Magnum caliber revolver formerly manufactured " - "by Colt's Manufacturing Company of Hartford, Connecticut. It is sometimes " - 'referred to as a "Combat Magnum". It was first introduced in 1955, the ' - "same year as Smith & Wesson's M29 .44 Magnum." -) -``` - -
Advanced Material - -### Advanced Material: Testing - -Strive for 100% code coverage, but don't get obsess over the coverage score. - -#### General testing guidelines - -- Use long, descriptive names. This often obviates the need for doctrings in test methods. -- Tests should be isolated. Don't interact with a real database or network. Use a separate test database that gets torn down or use mock objects. -- Prefer [factories](https://github.com/rbarrois/factory_boy) to fixtures. -- Never let incomplete tests pass, else you run the risk of forgetting about them. Instead, add a placeholder like `assert False, "TODO: finish me"`. - -#### Unit Tests - -- Focus on one tiny bit of functionality. -- Should be fast, but a slow test is better than no test. -- It often makes sense to have one testcase class for a single class or model. - -```python -import unittest -import factories - -class PersonTest(unittest.TestCase): - def setUp(self): - self.person = factories.PersonFactory() - - def test_has_age_in_dog_years(self): - self.assertEqual(self.person.dog_years, self.person.age / 7) -``` - -#### Functional Tests - -Functional tests are higher level tests that are closer to how an end-user would interact with your application. They are typically used for web and GUI applications. - -- Write tests as scenarios. Testcase and test method names should read like a scenario description. -- Use comments to write out stories, *before writing the test code*. - -```python -import unittest - -class TestAUser(unittest.TestCase): - - def test_can_write_a_blog_post(self): - # Goes to the her dashboard - ... - # Clicks "New Post" - ... - # Fills out the post form - ... - # Clicks "Submit" - ... - # Can see the new post - ... -``` - -Notice how the testcase and test method read together like "Test A User can write a blog post". -
- -## Inspired by... - -- :bookmark_tabs: [The Hitchiker's Guide to Python][python-guide] :warning: -- [PEP 20 (The Zen of Python)][PEP 20] -- [PEP 8 (Style Guide for Python)][PEP 8] -- [Khan Academy Development Docs][] -- [Python Best Practice Patterns][] -- [Pythonic Sensibilities][] -- [The Pragmatic Programmer][] -- and many other bits and bytes - -[Pythonic Sensibilities]: http://www.nilunder.com/blog/2013/08/03/pythonic-sensibilities/ -[Python Best Practice Patterns]: http://youtu.be/GZNUfkVIHAY -[python-guide]: http://docs.python-guide.org/en/latest/ -[PEP 20]: http://www.python.org/dev/peps/pep-0020/ -[PEP 257]: http://www.python.org/dev/peps/pep-0257/ -[PEP 8]: http://www.python.org/dev/peps/pep-0008/ -[Khan Academy Development Docs]: https://sites.google.com/a/khanacademy.org/forge/for-developers -[The Pragmatic Programmer]: http://www.amazon.com/The-Pragmatic-Programmer-Journeyman-Master/dp/020161622X/ref=sr_1_1?ie=UTF8&qid=1381886835&sr=8-1&keywords=pragmatic+programmer diff --git a/scripts/check_markdown_links.py b/scripts/check_markdown_links.py new file mode 100644 index 0000000..f80c3f0 --- /dev/null +++ b/scripts/check_markdown_links.py @@ -0,0 +1,85 @@ +"""Validate repository-local Markdown links and heading anchors.""" + +from __future__ import annotations + +import pathlib +import re +import unicodedata +import urllib.parse + + +ROOT = pathlib.Path(__file__).resolve().parents[1] +LINK_PATTERN = re.compile(r"(? str: + """Return the GitHub-style base anchor for a Markdown heading.""" + without_html = re.sub(r"<[^>]+>", "", title).strip().lower() + normalized = unicodedata.normalize("NFKD", without_html) + anchor = re.sub(r"[^\w\- ]", "", normalized, flags=re.UNICODE) + return re.sub(r"-+", "-", anchor.replace(" ", "-")) + + +def collect_anchors(markdown: pathlib.Path) -> set[str]: + """Collect anchors, including GitHub's suffix for duplicate headings.""" + anchors: set[str] = set() + counts: dict[str, int] = {} + + for line in markdown.read_text(encoding="utf-8").splitlines(): + match = HEADING_PATTERN.match(line) + if not match: + continue + + base = github_anchor(match.group(2)) + count = counts.get(base, 0) + counts[base] = count + 1 + anchors.add(base if count == 0 else f"{base}-{count}") + + return anchors + + +def validate() -> list[str]: + """Return all invalid repository-local Markdown links.""" + markdown_files = sorted(path for path in ROOT.rglob("*.md") if ".git" not in path.parts) + anchors_by_file = {path.resolve(): collect_anchors(path) for path in markdown_files} + errors: list[str] = [] + + for source in markdown_files: + content = source.read_text(encoding="utf-8") + for raw_target in LINK_PATTERN.findall(content): + target = raw_target.strip() + if target.startswith(EXTERNAL_PREFIXES): + continue + + path_part, separator, anchor_part = target.partition("#") + if path_part: + decoded_path = urllib.parse.unquote(path_part) + destination = (source.parent / decoded_path).resolve() + else: + destination = source.resolve() + + try: + destination.relative_to(ROOT) + except ValueError: + errors.append(f"{source.relative_to(ROOT)}: link escapes repository: {target}") + continue + + if not destination.exists(): + errors.append(f"{source.relative_to(ROOT)}: missing target: {target}") + continue + + if separator and anchor_part and destination in anchors_by_file: + anchor = urllib.parse.unquote(anchor_part).lower() + if anchor not in anchors_by_file[destination]: + errors.append(f"{source.relative_to(ROOT)}: missing anchor: {target}") + + return errors + + +if __name__ == "__main__": + validation_errors = validate() + if validation_errors: + raise SystemExit("\n".join(validation_errors)) + print("All repository-local Markdown links and anchors resolve.")