docs: clarify release policy, lifecycle and security support

nijel · nijel · commit 1f52dd7e66a5 · 2026-06-16T11:06:51.000+02:00
This just better documents existing practices and consolidates
documentation in a shape that it is easier to find.
diff --git a/docs/admin/install/docker.rst b/docs/admin/install/docker.rst
@@ -30,6 +30,13 @@ behind HTTPS terminating proxy. You can also deploy with a HTTPS proxy, see
         git clone https://github.com/WeblateOrg/docker-compose.git weblate-docker
         cd weblate-docker
 
+   .. note::
+
+      The Docker Compose files are example deployment configurations. Operators
+      typically customize them for their own deployment and maintain those local
+      changes. Weblate application updates are delivered through Docker image
+      tags; there is no release-bound update path for customized Compose files.
+
 2. Create a :file:`docker-compose.override.yml` file with your settings.
    See :ref:`docker-environment` for full list of environment variables.
 
@@ -253,8 +260,11 @@ should be no need for additional manual actions.
     calendar year. If you need to upgrade from an older release, upgrade first
     to an intermediate version listed in :ref:`version-specific-instructions`.
 
-You might also want to update the ``docker-compose`` repository, though it's
-not needed in most case. See :ref:`docker-postgres-upgrade` for upgrading the PostgreSQL server.
+If you use the example Compose files without local changes, you can also
+review updates in the ``docker-compose`` repository, though this is not needed
+for most Weblate upgrades. Customized Compose files need to be maintained as
+part of your deployment. See :ref:`docker-postgres-upgrade` for upgrading the
+PostgreSQL server.
 
 .. _docker-postgres-upgrade:
 
diff --git a/docs/changes.rst b/docs/changes.rst
@@ -24,11 +24,8 @@ Weblate 2026.7
 * Translate pages with filtered searches and nearby strings now load more efficiently.
 * Translation form submissions now avoid loading complete search result sets when saving strings.
 * Added :ref:`distribution-packaging` guidance for distribution maintainers.
-* Documented :ref:`release-artifact-inventory` for Weblate release and deployment artifacts.
-* Added :doc:`/security/releases` with release, security-update, and upgrade support lifecycle details.
-* Documented release artifact signatures, attestations, SBOMs, and checksum verification coverage.
-* Organized release lifecycle, release artifact verification, and dependency security documentation into separate security pages.
-* Filled repository-backed security metadata and removed unsupported empty placeholders.
+* Expanded security documentation for release artifacts, supported versions, security updates, release verification, SBOMs, and dependency handling.
+* Clarified security metadata, vulnerability reporting, hosted-service incident response, and self-hosted operator responsibilities.
 * Large component imports now avoid duplicate translation-memory processing.
 * :ref:`gettext` files can now be configured to remove obsolete strings on save.
 * Added :wladmin:`analyze_translator_work` to estimate realistic daily translator throughput from change history.
@@ -44,7 +41,6 @@ Weblate 2026.7
 * Project and workspace translation license defaults now follow component and project licenses more closely.
 * Component and category API ``PATCH`` requests no longer remove the category when the field is omitted.
 * Hardened HTML and AJAX object lookups against private project enumeration.
-* Out-of-range cached search offsets no longer cause translate form submissions to fail.
 * Document and translation-memory uploads now enforce :setting:`TRANSLATION_UPLOAD_MAX_SIZE`, and API document uploads validate file extensions.
 * :ref:`check-rst-syntax` now detects inline roles wrapped in stray backticks.
 * :ref:`auto-translation` no longer validates hidden component fields when using machine translation.
diff --git a/docs/index.rst b/docs/index.rst
@@ -153,6 +153,8 @@ Learn more about :ref:`contributing`.
    :hidden:
 
    security/index
+   security/product-information
+   security/governance
    security/releases
    security/release-artifacts
    security/dependencies
diff --git a/docs/security/dependencies.rst b/docs/security/dependencies.rst
@@ -1,38 +1,126 @@
 Dependencies
 ============
 
-This page describes dependency monitoring and container vulnerability scanning.
-For published release artifacts, SBOMs, signatures, and provenance
-attestations, see :doc:`release-artifacts`.
+This page describes dependency inventory, vulnerability monitoring, dependency
+triage, and container vulnerability scanning. For published release artifacts,
+SBOMs, signatures, and provenance attestations, see
+:doc:`release-artifacts`.
+
+Dependency inventory
+--------------------
+
+Weblate dependency information is maintained in several repository files:
+
+* Python dependencies are declared in :file:`pyproject.toml` and resolved in
+  :file:`uv.lock`.
+* Frontend dependencies are declared in :file:`client/package.json` and
+  resolved in :file:`client/yarn.lock`.
+* Vendored frontend libraries and generated license data are documented in
+  :doc:`/contributing/submodules`.
+* Release SBOMs are published for Weblate releases as described in
+  :ref:`sbom`.
+* Docker image and Helm chart dependencies are maintained in the
+  Weblate-owned Docker and Helm repositories listed in
+  :ref:`release-artifact-inventory`.
+
+The dependency ranges in :file:`pyproject.toml` describe the supported runtime
+requirements. The lock files describe the tested dependency set used by CI and
+release automation.
 
 Tracking dependencies for vulnerabilities
 -----------------------------------------
 
-Security issues in our dependencies are monitored using `Renovate`_. This
-covers the Python and JavaScript libraries, and the latest stable release has
-its dependencies updated to avoid vulnerabilities.
+Security issues in Weblate dependencies are monitored using `Renovate`_,
+GitHub dependency review, FOSSA_, release SBOMs, and container vulnerability
+scans.
+
+The Weblate repositories extend the shared Renovate preset from
+`WeblateOrg/meta`_. That preset enables the dependency dashboard, OSV
+vulnerability alerts, platform vulnerability alerts, semantic dependency
+commits, and Renovate custom managers for GitHub Actions, Dockerfiles, Helm
+chart application versions, and other pinned tool versions. It also configures
+selected package grouping, schedules, and automerge behavior.
+
+This repository adds ``main`` and ``stable`` as Renovate base branches.
+General dependency updates and lockfile maintenance are disabled on
+``stable``; security update coverage for Weblate releases is described in
+:ref:`security-updates`.
+
+GitHub dependency review runs on pull requests to show dependency changes
+before they are merged. FOSSA runs on pushes to ``main`` and records scan
+and policy-test results in the FOSSA service.
+
+Dependency vulnerability triage
+-------------------------------
+
+When a dependency vulnerability is reported by Renovate, GitHub dependency
+review, FOSSA, a release SBOM review, a container scan, or a vulnerability
+report, maintainers evaluate whether it affects Weblate. The triage checks
+include:
+
+* whether the affected dependency and version are used by Weblate, a published
+  release artifact, or a maintained deployment artifact;
+* whether the vulnerable code path is reachable through supported Weblate
+  functionality or supported deployment modes;
+* whether the issue is in Weblate's use of the dependency or should be
+  reported to the upstream project;
+* whether a dependency update, configuration change, mitigation, advisory, or
+  Weblate security update is needed.
 
 .. hint::
 
    There might be vulnerabilities in third-party libraries which do not affect
    Weblate, so those are not addressed by releasing bugfix versions of Weblate.
 
+Dependency and lockfile maintenance
+-----------------------------------
+
+The Python lock file is maintained by the ``uv lock update`` workflow. The
+frontend dependency lock file and vendored frontend files are maintained by the
+``yarn update`` workflow.
+
+Generated maintenance changes are passed through the ``Apply maintenance
+patch`` workflow. That workflow applies only validated patch artifacts and
+limits the paths that each maintenance workflow is allowed to update.
+
 Docker container security
 -------------------------
 
 The Weblate and Weblate Client Docker containers are scanned for security
 vulnerabilities in CI. This allows us to detect vulnerabilities early and
 release improvements quickly.
 
-You can get the results of these scans at GitHub — they are stored as artifacts
-on our CI as :abbr:`SARIF (Static Analysis Results Interchange Format)`.
+The inspected Weblate Docker and Weblate Client workflows scan built container
+images with Anchore_ and Trivy_. Results are uploaded to GitHub code scanning
+as :abbr:`SARIF (Static Analysis Results Interchange Format)` data. The
+inspected workflows also store Trivy SARIF artifacts, and the Weblate Client
+workflow stores Anchore SARIF artifacts.
+
+Known external policy details
+-----------------------------
+
+Some dependency and vulnerability-management details are maintained outside
+this documentation:
+
+* complete Renovate behavior is defined in the shared `WeblateOrg/meta`_
+  preset and repository platform settings;
+* GitHub dependency graph, Dependabot alert, and branch-protection state are
+  GitHub platform configuration;
+* FOSSA result history and policy thresholds are stored in FOSSA;
+* scanner output is stored in GitHub code scanning and workflow artifacts.
 
 .. seealso::
 
    * :ref:`ci-tests`
-   * `Renovate <https://www.mend.io/renovate/>`_
-   * `Anchore <https://anchore.com/>`_
+   * Renovate_
+   * `GitHub dependency review`_
+   * FOSSA_
+   * Anchore_
    * Trivy_
 
 .. _Renovate: https://www.mend.io/renovate/
+.. _WeblateOrg/meta: https://github.com/WeblateOrg/meta
+.. _GitHub dependency review: https://github.com/actions/dependency-review-action
+.. _FOSSA: https://fossa.com/
+.. _Anchore: https://anchore.com/
 .. _Trivy: https://github.com/aquasecurity/trivy
diff --git a/docs/security/governance.rst b/docs/security/governance.rst
@@ -0,0 +1,45 @@
+Security governance and assessment status
+=========================================
+
+This page summarizes where Weblate publishes security governance information
+and records the current formal assessment status. It is a factual
+documentation index and does not claim certification, audit completion, or
+regulatory compliance.
+
+For product identity, contact, support, release, and SBOM identity, see
+:doc:`product-information`.
+
+Governance documentation
+------------------------
+
+Weblate publishes security governance information in these documentation
+areas:
+
+* Contribution rules, code review expectations, and project participation are
+  documented in :doc:`/contributing/index`, :doc:`/contributing/code`, and
+  :doc:`/contributing/code_of_conduct`.
+* Release lifecycle, security update coverage, and upgrade support are
+  documented in :doc:`releases`.
+* Vulnerability reporting, disclosure handling, and service incident reporting
+  are documented in :doc:`issues`.
+* Dependency inventory, vulnerability triage, update automation, and container
+  scanning are documented in :doc:`dependencies`.
+* Security assumptions and boundaries are documented in :doc:`threat-model`.
+* Release artifact inventory, SBOMs, signatures, attestations, and verification
+  are documented in :doc:`release-artifacts`.
+
+Formal assessment status
+------------------------
+
+This repository does not currently record a formal third-party security
+assessment, certification, audit report, penetration-test report, or formal
+self-assessment for Weblate.
+
+Automated security checks and compliance tools such as CodeQL, GitHub
+dependency review, FOSSA, OpenSSF Scorecard, and container vulnerability scans
+are security evidence and automation signals. They are not formal assessments,
+certifications, or audit reports.
+
+If Weblate publishes formal assessment evidence in the future, this page and
+the repository security metadata should be updated with the assessment
+reference and date.
diff --git a/docs/security/incident-response-plan.rst b/docs/security/incident-response-plan.rst
@@ -32,7 +32,9 @@ Communication logistics
     - **E-mail** is used to reach customers.
     - Customer contact lists are maintained in several locations to ensure access during service outages.
 - **Public Disclosure:**
-    - If a security vulnerability is discovered, follow :doc:`/security/issues`.
+    - If an incident includes a Weblate product vulnerability, follow the
+      product vulnerability reporting process and
+      :ref:`vulnerability-disclosure-policy` in :doc:`/security/issues`.
 
 Incident categories and severity
 --------------------------------
diff --git a/docs/security/index.rst b/docs/security/index.rst
@@ -23,12 +23,15 @@ SBOMs. See :doc:`release-artifacts`.
 Security policies
 -----------------
 
+* :doc:`product-information` - product identity, contact, support, release,
+  and SBOM metadata.
+* :doc:`governance` - security governance documentation and assessment status.
 * :doc:`releases` - release cycle, security update coverage, and upgrade
   support.
 * :doc:`release-artifacts` - release artifact inventory, SBOMs, signatures,
   attestations, and verification.
-* :doc:`dependencies` - dependency monitoring and container vulnerability
-  scanning.
+* :doc:`dependencies` - dependency inventory, vulnerability triage, update
+  automation, and container scanning.
 * :doc:`issues` - vulnerability reporting and disclosure.
 * :doc:`disaster-recovery-plan`
 * :doc:`incident-response-plan`
diff --git a/docs/security/issues.rst b/docs/security/issues.rst
@@ -3,8 +3,8 @@ Vulnerability and incident handling
 
 .. _security:
 
-Reporting security issues
--------------------------
+Product vulnerability reports
+-----------------------------
 
 .. seealso::
 
@@ -14,6 +14,10 @@ Weblate’s development team is strongly committed to responsible reporting and
 disclosure of security-related issues. We have adopted and follow policies that
 are geared toward delivering timely security updates to Weblate.
 
+Product vulnerability reports cover security issues in Weblate source code,
+release artifacts, and documented Weblate security properties. They do not
+replace operational incident response for a particular deployment.
+
 Most normal bugs in Weblate are reported to our public `GitHub issues tracker
 <https://github.com/WeblateOrg/weblate/issues>`_, but due to the sensitive
 nature of security issues, we ask them not to be publicly reported in this
@@ -24,6 +28,11 @@ implications, please submit a description of the issue to security@weblate.org,
 `GitHub <https://github.com/WeblateOrg/weblate/security/advisories/new>`_,
 or using `HackerOne <https://hackerone.com/weblate>`_.
 
+Self-hosted operators should use this process when they believe an incident in
+their own deployment is caused by a Weblate product vulnerability. Local
+containment, recovery, customer notification, provider escalation, and other
+deployment-specific incident response remain the operator's responsibility.
+
 A member of the security team will respond to you within 48 hours, and
 depending on what action is taken, you may get more follow-up emails.
 
@@ -54,19 +63,44 @@ depending on what action is taken, you may get more follow-up emails.
 
    * :doc:`/contributing/issues`
 
+Weblate-operated service incidents
+----------------------------------
+
+Operational incidents affecting Hosted Weblate, Dedicated Weblate, or other
+deployments operated by Weblate s.r.o. are handled using
+:doc:`/security/incident-response-plan`.
+
+When such an incident also involves a Weblate product vulnerability, the
+vulnerability report and public advisory follow the product vulnerability
+reporting process and :ref:`vulnerability-disclosure-policy` on this page.
+
+Self-hosted deployment incidents
+--------------------------------
+
+Operators of self-hosted Weblate deployments are responsible for their local
+incident response process, including containment, recovery, notification, and
+provider-specific escalation. The Weblate-operated
+:doc:`/security/incident-response-plan` can be used as a reference, but it is
+not a maintained incident response plan for third-party deployments.
+
+If a self-hosted incident appears to be caused by a Weblate product
+vulnerability, report it using the product vulnerability reporting process
+above.
+
 .. _vulnerability-disclosure-policy:
 
 Vulnerability disclosure policy
 -------------------------------
 
-Within 30 days following a release containing a vulnerability fix, a security
-advisory is published at
+For Weblate product vulnerabilities, within 30 days following a release
+containing a vulnerability fix, a security advisory is published at
 https://github.com/WeblateOrg/weblate/security/advisories. The advisory is
 available immediately with a release when possible.
 
-Any actively exploited vulnerability or severe incidents are notified to CSIRT
-within 24 hours, general info is provided to CSIRT within 72 hours, and a full
-report is provided within 14 days.
+Any actively exploited Weblate vulnerability, or any severe incident affecting
+Weblate-operated services, is notified to CSIRT within 24 hours, general info
+is provided to CSIRT within 72 hours, and a full report is provided within 14
+days.
 
 All users of Hosted or Dedicated Weblate impacted by a severe incident
 or an actively exploited vulnerability are notified within 7 days.
diff --git a/docs/security/product-information.rst b/docs/security/product-information.rst
diff --git a/docs/security/release-artifacts.rst b/docs/security/release-artifacts.rst
diff --git a/security.yaml b/security.yaml
