# Description

Updates the tradeoffs section in the design documentation to accurately reflect copa's ability to work with or without vulnerability scanner reports.

The changes:
- Remove outdated statements about scanner report dependencies
- Clarify the package-based update model
- Maintain information about package manager dependencies and platform limitations
- Improve document structure for better readability

# Changes
- Replace outdated tradeoffs content with updated, accurate information
- Add clearer section organization with numbered points
- Update description of scanner integration to reflect optional usage

Closes project-copacetic#818

website/docs/design.md

@@ -76,7 +76,22 @@ type PackageManager interface {
 
 ## Tradeoffs
 
-- The core architectural choice of relying on packages as the unit of patching creates a couple of constraints:
-  - By relying on existing vulnerability scanner behavior that only detects vulnerabilities via presence/absence of vulnerable packages, copa is limited in the kinds of vulnerabilities it can address and false positive/negatives from scanners flow downstream to copa.
-  - copa depends on individual package manager adapters to correctly deploy patches to the target images, but there is a long tail of compatibility issues that arise depending on the target image itself (e.g. outdated package manager config/keys, invalid/missing package graph, etc.). Overall, the maintenance cost of the project is expected to be non-trivial to address this.
-- No support for windows containers given the dependency on buildkit.
+1. **Package-Based Update Model**:
+   - While copa can work with or without vulnerability scanner reports, its patching capability is fundamentally based on OS package updates
+   - When using scanner reports, false positives/negatives from scanners flow downstream to copa
+   - The package-based approach limits the kinds of vulnerabilities copa can address to those fixable via package updates
+
+2. **Package Manager Dependencies**:
+   - Copa depends on individual package manager adapters to correctly deploy patches to target images
+   - There is a long tail of compatibility issues that arise depending on the target image itself:
+     - Outdated package manager config/keys
+     - Invalid/missing package graph
+     - Repository configuration issues
+   - Overall, the maintenance cost of the project is expected to be non-trivial to address these package manager complexities
+
+3. **Platform Limitations**:
+   - Limited Windows container support:
+   - While BuildKit has experimental Windows container support
+   - Windows containers lack a standardized package upgrade mechanism
+
+This makes package-based patching currently impractical on Windows

website/versioned_docs/version-v0.7.x/design.md

@@ -76,7 +76,22 @@ type PackageManager interface {
 
 ## Tradeoffs
 
-- The core architectural choice of relying on packages as the unit of patching creates a couple of constraints:
-  - By relying on existing vulnerability scanner behavior that only detects vulnerabilities via presence/absence of vulnerable packages, copa is limited in the kinds of vulnerabilities it can address and false positive/negatives from scanners flow downstream to copa.
-  - copa depends on individual package manager adapters to correctly deploy patches to the target images, but there is a long tail of compatibility issues that arise depending on the target image itself (e.g. outdated package manager config/keys, invalid/missing package graph, etc.). Overall, the maintenance cost of the project is expected to be non-trivial to address this.
-- No support for windows containers given the dependency on buildkit.
+1. **Package-Based Update Model**:
+   - While copa can work with or without vulnerability scanner reports, its patching capability is fundamentally based on OS package updates
+   - When using scanner reports, false positives/negatives from scanners flow downstream to copa
+   - The package-based approach limits the kinds of vulnerabilities copa can address to those fixable via package updates
+
+2. **Package Manager Dependencies**:
+   - Copa depends on individual package manager adapters to correctly deploy patches to target images
+   - There is a long tail of compatibility issues that arise depending on the target image itself:
+     - Outdated package manager config/keys
+     - Invalid/missing package graph
+     - Repository configuration issues
+   - Overall, the maintenance cost of the project is expected to be non-trivial to address these package manager complexities
+
+3. **Platform Limitations**:
+   - Limited Windows container support:
+   - While BuildKit has experimental Windows container support
+   - Windows containers lack a standardized package upgrade mechanism
+
+This makes package-based patching currently impractical on Windows

website/versioned_docs/version-v0.8.x/design.md

@@ -76,7 +76,22 @@ type PackageManager interface {
 
 ## Tradeoffs
 
-- The core architectural choice of relying on packages as the unit of patching creates a couple of constraints:
-  - By relying on existing vulnerability scanner behavior that only detects vulnerabilities via presence/absence of vulnerable packages, copa is limited in the kinds of vulnerabilities it can address and false positive/negatives from scanners flow downstream to copa.
-  - copa depends on individual package manager adapters to correctly deploy patches to the target images, but there is a long tail of compatibility issues that arise depending on the target image itself (e.g. outdated package manager config/keys, invalid/missing package graph, etc.). Overall, the maintenance cost of the project is expected to be non-trivial to address this.
-- No support for windows containers given the dependency on buildkit.
+1. **Package-Based Update Model**:
+   - While copa can work with or without vulnerability scanner reports, its patching capability is fundamentally based on OS package updates
+   - When using scanner reports, false positives/negatives from scanners flow downstream to copa
+   - The package-based approach limits the kinds of vulnerabilities copa can address to those fixable via package updates
+
+2. **Package Manager Dependencies**:
+   - Copa depends on individual package manager adapters to correctly deploy patches to target images
+   - There is a long tail of compatibility issues that arise depending on the target image itself:
+     - Outdated package manager config/keys
+     - Invalid/missing package graph
+     - Repository configuration issues
+   - Overall, the maintenance cost of the project is expected to be non-trivial to address these package manager complexities
+
+3. **Platform Limitations**:
+   - Limited Windows container support:
+   - While BuildKit has experimental Windows container support
+   - Windows containers lack a standardized package upgrade mechanism
+
+This makes package-based patching currently impractical on Windows

website/versioned_docs/version-v0.9.x/design.md

@@ -76,7 +76,22 @@ type PackageManager interface {
 
 ## Tradeoffs
 
-- The core architectural choice of relying on packages as the unit of patching creates a couple of constraints:
-  - By relying on existing vulnerability scanner behavior that only detects vulnerabilities via presence/absence of vulnerable packages, copa is limited in the kinds of vulnerabilities it can address and false positive/negatives from scanners flow downstream to copa.
-  - copa depends on individual package manager adapters to correctly deploy patches to the target images, but there is a long tail of compatibility issues that arise depending on the target image itself (e.g. outdated package manager config/keys, invalid/missing package graph, etc.). Overall, the maintenance cost of the project is expected to be non-trivial to address this.
-- No support for windows containers given the dependency on buildkit.
+1. **Package-Based Update Model**:
+   - While copa can work with or without vulnerability scanner reports, its patching capability is fundamentally based on OS package updates
+   - When using scanner reports, false positives/negatives from scanners flow downstream to copa
+   - The package-based approach limits the kinds of vulnerabilities copa can address to those fixable via package updates
+
+2. **Package Manager Dependencies**:
+   - Copa depends on individual package manager adapters to correctly deploy patches to target images
+   - There is a long tail of compatibility issues that arise depending on the target image itself:
+     - Outdated package manager config/keys
+     - Invalid/missing package graph
+     - Repository configuration issues
+   - Overall, the maintenance cost of the project is expected to be non-trivial to address these package manager complexities
+
+3. **Platform Limitations**:
+   - Limited Windows container support:
+   - While BuildKit has experimental Windows container support
+   - Windows containers lack a standardized package upgrade mechanism
+
+This makes package-based patching currently impractical on Windows