📦 Third-Party Code Policy¶

🚫 Never Modify Directly¶

❌ BAD: Edit vendor/library/code.cpp ✅ GOOD: Wrapper or patch file

Reason: Updates overwrite changes

🔧 If Modification Needed¶

Option 1: Wrapper (Preferred)¶

Wrap the library with your own interface.

// our_wrapper.hpp
#include <vendor/library.hpp>

namespace our {
    class Library {
        vendor::Library impl_;
    public:
        // Our API
        void ourAPI() {
            // Adapt vendor API
            impl_.vendorAPI();
        }

        // Add missing functionality
        void extraFeature() {
            // Build on vendor
            impl_.method1();
            impl_.method2();
        }
    };
}

Pros: - No modification to vendor code - Easy to update vendor library - Clear separation of concerns

Cons: - Slight indirection overhead - Must maintain wrapper

Option 2: Patch File¶

For small fixes that can't be wrapped.

# patches/library.patch
diff --git a/vendor/library.cpp b/vendor/library.cpp
index 1234567..abcdefg 100644
--- a/vendor/library.cpp
+++ b/vendor/library.cpp
@@ -42,7 +42,7 @@
 void Library::process() {
-    // Bug: off-by-one
-    for (int i = 0; i <= size; ++i) {
+    // Fixed: correct bounds
+    for (int i = 0; i < size; ++i) {
         buffer[i] = 0;
     }
 }

Apply patch:

# scripts/apply_patches.sh
#!/bin/bash
cd vendor/library
patch -p1 < ../../patches/library.patch

Document in README:

## Third-Party Library Patches

Apply patches after updating library:

    ./scripts/apply_patches.sh

### Patches Applied:
- `library.patch` - Fix off-by-one error (reported upstream #456)

Pros: - Minimal changes - Easy to see what was modified - Can submit upstream

Cons: - May break on updates - Manual reapplication needed

Option 3: Fork (Last Resort)¶

Fork the library and maintain your own version.

# Fork on GitHub
# Clone your fork
git clone https://github.com/yourorg/library-fork.git vendor/library

# Track upstream
git remote add upstream https://github.com/original/library.git

When to fork: - Library is unmaintained - Need extensive modifications - Upstream won't accept patches - License allows

Maintenance burden: - Must merge upstream updates - Maintain your changes - Test on every update - Document all modifications

Avoid if possible.

📝 Documentation¶

Required for all third-party code:

## Third-Party: LibraryName

- **Version:** 1.2.3
- **License:** MIT
- **Homepage:** https://github.com/original/library
- **Modifications:** None / See patches/ / Forked
- **Update strategy:** Manual / Automated
- **Last updated:** 2025-01-15
- **Maintained by:** @team-name

### Why This Library?

Chosen because:
- Feature X that we need
- Performance benchmarks (link)
- Active maintenance
- Compatible license

### Alternatives Considered:

1. **OtherLibrary** - Rejected: Missing feature Y
2. **AnotherLibrary** - Rejected: Incompatible license
3. **RollOurOwn** - Rejected: Too much effort

### Update Process:

1. Check release notes
2. Test in staging branch
3. Run full test suite
4. Reapply patches (if any)
5. Merge to main

⚖️ License Compliance¶

Before adding any third-party library:

✓ License compatible with our license
✓ Attribution provided (in code + docs)
✓ License file included (vendor/library/LICENSE)
✓ Documented in THIRD_PARTY_NOTICES.md

License Compatibility Matrix¶

Our License: MIT

✅ Compatible:
- MIT
- BSD (2-clause, 3-clause)
- Apache 2.0
- ISC
- Public Domain / Unlicense

⚠️ Review Required:
- LGPL (dynamic linking usually OK)
- MPL 2.0 (file-level copyleft)

❌ Incompatible:
- GPL (copyleft)
- AGPL (network copyleft)
- Proprietary (no source)

If unsure, consult legal.

🔄 Update Strategy¶

Automated Updates (Preferred)¶

Use Dependabot, Renovate, or similar.

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    reviewers:
      - "team-name"

Pros: - Stay up-to-date automatically - Security patches applied quickly

Cons: - May break on major updates - Requires good test coverage

Manual Updates¶

For critical or modified libraries.

Process:

Check release notes
Test in isolated branch
Run full test suite
Check for API changes
Reapply patches if needed
Update documentation
Ship

Frequency: Quarterly or when security issue

🚨 Security¶

Vulnerability Scanning¶

# Scan dependencies
npm audit        # For npm packages
cargo audit      # For Rust crates

# Or use GitHub Security Advisories

Security Updates¶

Treat as high priority:

Update immediately
Test thoroughly
Ship ASAP
Document in release notes

📂 Directory Structure¶

vendor/
├── library-name/          # Full library source
│   ├── LICENSE           # Original license
│   ├── README.md         # Original README
│   └── src/              # Source code
├── another-lib/
└── README.md             # Our documentation

patches/
├── library.patch         # Our modifications
└── another.patch

docs/
└── THIRD_PARTY_NOTICES.md   # Aggregated licenses

🎯 Best Practices¶

✅ DO:¶

Use package manager when possible (npm, cargo, vcpkg)
Document why each library is used
Track version numbers
Automate updates when safe
Wrap libraries with your API
Submit patches upstream

❌ DON'T:¶

Copy-paste code from libraries
Modify vendor code directly
Mix your code with vendor code
Forget to check licenses
Use libraries for trivial functionality
Add dependencies without review

📋 Addition Checklist¶

Before adding new third-party library: