Add best practices section

Author: spoorcc

doc/vendoring.rst

@@ -164,6 +164,105 @@ that trade is clearly worthwhile. In others, it introduces more cost than benefi
 Used intentionally and with an understanding of its limitations, vendoring is
 simply one tool among many for managing dependencies.
 
+Best Practices
+--------------
+
+The following practices are drawn from our own usage of *Dfetch* and real-world policies and respected guidelines.
+They *mitigate* vendoring risks; they do not eliminate them.
+
+.. admonition :: Explicit Version Pinning and Provenance
+
+    Every vendored dependency must be pinned to an explicit version, tag, or commit, and its source must be documented.
+
+    **Rationale** Vendored code is often added once and then forgotten. Without automation, vulnerabilities, license issues,
+    and inconsistencies can persist unnoticed long after initial inclusion.
+
+    * pip: `vendor.txt` tracks versions and sources
+    * Go/Kubernetes: `go.mod`, `go.sum`, `vendor/modules.txt`
+    * Cargo: `Cargo.lock` + vendored sources
+    * Guidelines: `OWASP SCVS <https://scvs.owasp.org/scvs/v1-inventory/>`_, OpenSSF, NIST SP 800-161, SLSA
+
+    *Dfetch* addresses this by having a declarative :ref:`manifest` and the option to :ref:`freeze` dependences to make each
+    revision exiplicit.
+
+.. admonition :: Reproducible and Offline Builds
+
+    Vendoring must enable fully reproducible and offline builds.
+
+    **Rationale** The point of vendoring code is to remove external dependencies, by making sure an offline build succeeds it is
+    proven that builds are not dependent on external sources.
+
+    * Go: committed `vendor/`
+    * Cargo: `.cargo/config.toml` + `cargo vendor`
+    * pip: vendored wheels and pure-Python dependencies
+    * Guidelines: SLSA, OpenSSF
+
+    *Dfetch* doesn't directly addresses this, this is a policy to follow.
+
+.. admonition :: Do Not Review Vendored Code Line-by-Line
+
+    External vendored code is not reviewed line-by-line. Review focuses on *metadata*.
+
+    **Rationale** Reviewing external code will place a burden on maintainers.
+    When first selecting an external dependency perform Due Diligence.
+
+    Reviewers verify:
+
+    * Version changes
+    * Changelogs / release notes
+    * License compatibility
+    * CI and test results
+
+    This principle is explicitly aligned with:
+
+    * OWASP Software Component Verification Standard
+    * Google Open Source Security Guidelines
+    * OpenSSF Best Practices
+
+    *Dfetch* addresses this by having a manifest and a metadata file (``.dfetch_data.yaml``) which can be reviewed.
+
+.. admonition :: Separation of Vendor Updates from Product Changes
+
+    Vendored dependency updates must be isolated from functional code changes.
+
+    * Separate PRs or commits
+    * Clear commit messages documenting versions and rationale
+
+    **Rationale** By separation the review noise will be reduced, letting maintainers focus on important changes.
+
+    *Dfetch* doesn't address this directly.
+
+.. admonition :: No Manual Modifications Without Documentation
+
+    Vendored code must not be modified directly unless unavoidable.
+
+    If modifications are required:
+
+    * Document patches explicitly
+    * Prefer patch/overlay mechanisms
+    * Upstream changes whenever possible
+    * pip: documented adaptations
+    * Cargo: `[patch]` mechanism
+    * Guidelines: Google OSS, OWASP, OpenSSF
+
+    **Rationale** The vendored dependency may diverge,  and patch rot
+
+    *Dfetch* addresses this by providing a ``dfetch diff`` (:ref:`Diff`) command and a ``patch`` :ref:`Patch` attribute in the manifest.
+    Next to this there is a CI system to detect local changes using :ref:`Check`.
+
+.. admonition :: Continuous Automation and Security Scanning
+
+    Vendored dependencies must be continuously verified through automation.
+
+    * CI verifies vendor consistency
+    * Dependency and CVE scanning
+    * SBOM generation
+
+    **Rationale** By copy-pasting a dependency, there may m=be silent security degradation since there is no automatic updates.
+
+    *Dfetch* addresses this by providing a ``dfetch check`` (:ref:`Check`) command to see if dependencies are out-of-date and
+    various report formats (including SBoM) to check vulnerabilities.
+
 Real-world projects using vendoring
 -----------------------------------