Skip to content

dependency-management.md

Latest commit

 

History

History
230 lines (162 loc) · 5.16 KB

dependency-management.md

File metadata and controls

230 lines (162 loc) · 5.16 KB

Dependency Management

Dependency hygiene is critical for security, reproducibility, and developer experience. Follow these practices to ensure our module stays stable, up to date, and secure.



📦 Module Management

  • All dependencies must be managed via Go Modules (go.mod, go.sum)

  • After adding, updating, or removing imports, run:

    go mod tidy

or via magex command:

magex deps:tidy

  • Periodically refresh dependencies with:

    go get -u ./...

    or via magex command:

    magex deps:update

Avoid unnecessary upgrades near release windows—review major version bumps carefully for breaking changes.



🛡️ Security Scanning

  govulncheck ./...
  • Run via magex command:
  magex deps:audit
  • Run gitleaks before committing code to detect hardcoded secrets or sensitive data in the repository:
brew install gitleaks
gitleaks detect --source . --log-opts="--all" --verbose

  • Address critical advisories before merging changes into main/master

  • Document any intentionally ignored vulnerabilities with clear justification and issue tracking

  • We follow the OpenSSF best practices to ensure this repository remains compliant with industry‑standard open source security guidelines



📁 Version Control

  • Never manually edit go.sum
  • Do not vendor dependencies; we rely on modules for reproducibility
  • Lockstep upgrades across repos (when applicable) should be coordinated and noted in PRs

Changes to dependencies should be explained in the PR description and ideally linked to the reason (e.g., bug fix, security advisory, feature requirement).



🔄 Dependency Update Workflow

Regular Updates

  1. Check for updates

    go list -u -m all

  2. Update minor/patch versions

    go get -u ./...
go mod tidy

  3. Test thoroughly

    magex test
magex test:race
magex bench

  4. Security scan

    magex deps:audit

Major Version Updates

  1. Review breaking changes in release notes
  2. Update import paths if required
  3. Fix compilation errors
  4. Update tests for new behavior
  5. Document in PR what changed and why



🤖 Automated Dependency Management

Dependabot Configuration

  • Configured in .github/dependabot.yml
  • Checks for updates weekly
  • Groups minor/patch updates
  • Creates separate PRs for major versions

Auto-merge Rules

  • Minor/patch updates with passing CI can auto-merge
  • Major updates require manual review
  • Security updates prioritized for review



📊 Dependency Analysis

Check dependency graph

go mod graph

Identify unused dependencies

go mod tidy -v

Analyze module size impact

go mod download -json | jq '.Dir' | xargs du -sh | sort -h



🚫 Dependency Guidelines

DO:

  • Pin to specific versions in production
  • Review licenses before adding dependencies
  • Prefer standard library when possible
  • Use minimal dependencies for core functionality
  • Document unusual dependencies in code comments

DON'T:

  • Use latest tags in production
  • Import unused packages
  • Use replace directives except for emergencies
  • Add dependencies for trivial functionality
  • Ignore security advisories



🔍 Evaluating New Dependencies

Before adding a new dependency, consider:

  1. Necessity: Can we implement this ourselves simply?
  2. Maintenance: Is the project actively maintained?
  3. Security: Any known vulnerabilities?
  4. License: Compatible with our project?
  5. Size: How much does it increase binary size?
  6. Quality: Well-tested? Good documentation?
  7. Dependencies: Does it bring many transitive dependencies?



📝 Replace Directives

Use replace only when absolutely necessary:

// Temporary fix for critical bug until upstream releases
replace github.com/broken/package v1.2.3 => github.com/fork/package v1.2.4-fixed

// Local development only - remove before committing
replace github.com/company/module => ../local-module

Document why the replacement is needed and track removal in an issue.



🔐 Private Dependencies

For private modules:

  1. Configure authentication

    git config --global url."git@github.com:company/".insteadOf "https://github.com/company/"

  2. Set GOPRIVATE

    export GOPRIVATE=github.com/company/*

  3. Document setup in README for team members



📈 Monitoring Dependencies

Track outdated dependencies

# Show available updates
go list -u -m all | grep '\['

# Count total dependencies
go mod graph | wc -l

Review dependency changes

# See what changed in go.mod
git diff go.mod

# Detailed view of go.sum changes
git diff go.sum | grep '^[+-]' | sort

Regular dependency maintenance prevents security issues and reduces upgrade complexity.