-
Notifications
You must be signed in to change notification settings - Fork 4
Dependency Management
Managing dependencies is essential for keeping projects stable, secure, and maintainable.
This page explains how to safely upgrade packages, audit for vulnerabilities, track changes, and prevent breaking updates — all without introducing instability into shared repos.
- How to Audit Dependencies
- Keeping Libraries Updated
- Understanding Vulnerability Alerts
- Guidelines for Node + Package Upgrades
- Upgrade Template
- Best Practices
- Handling Issues & Compatibility
- Updating the Changelog
Expand Dependency Audit Methods
Use dependency audit tools to check for vulnerabilities, outdated libraries, or deprecated packages.
| Tool | Usage |
|---|---|
npm audit |
Detect known security vulnerabilities |
npm outdated |
Lists packages behind latest version |
npm-check-updates (ncu) |
Displays upgrade options interactively |
| Dependabot Alerts | Built into GitHub repositories |
Goal: Identify issues early — before they affect production.
| Frequency | Why |
|---|---|
| Weekly | Stay ahead of security patches |
| Before major feature work | Prevent compounding conflicts |
| Before new release | Ensure production stability |
Expand Upgrade Procedures
Keeping dependencies modern prevents security risk + tech debt.
Updates should be done carefully and incrementally.
- Identify outdated packages
- Upgrade one at a time (or a safe related set)
- Test locally + run full suite
- Document version changes
- Fix conflicts before upgrading more
You lose traceability — and debugging becomes painful.
Expand Alert Handling & Action Steps
GitHub may warn about:
- High-risk dependency CVEs
- Supply chain attacks
- Outdated or abandoned packages
- Licence conflict / compliance issues
| Severity | Action |
|---|---|
| Critical | Patch or upgrade immediately |
| High | Upgrade within sprint cycle |
| Medium/Low | Schedule for standard update cycle |
If a vulnerability cannot be resolved → document why and propose path forward.
Rollout Strategy for Safe Upgrades
Follow this upgrade order every time:
- Upgrade Node.js first → Latest stable LTS
- Update dependencies gradually — do not rush
- Review major version release notes before upgrading
- If something breaks → revert changes and isolate cause
- Test incrementally (unit + integration)
Full breakdown + logic pulled from practicum standards below:
- Always upgrade Node.js first
- Perform incremental updates
- Use the official template to track progress
- Test early + often
- Document all changes
- Track compatibility + release notes
This template is not mandatory, but meant to help guide you on your journey of updating packages. A good reference to use if you are unsure of steps to take or what you are looking for. You can download the Google Doc and fill it out locally or just use it as reference, you’re choice.
Click to Expand Template
https://docs.google.com/document/d/1COc9Xr2deF32-Mz9V9qaf0S022Z4OP-AjcDft69G4pU/edit?usp=sharing
General Dependency Management Rules
When managing packages, these symbols control how much flexibility npm has when installing versions:
| Symbol | Meaning | Example Installs | Use Case |
|---|---|---|---|
^ |
Allows minor & patch updates automatically |
^4.17.0 → 4.18.x, 4.19.x
|
Default for most development — keeps packages modern |
~ |
Allows patch updates only, no minor upgrades |
~4.17.0 → 4.17.1, 4.17.2
|
When you want stability, but still want bugfix releases |
| (No symbol — pinned version) | Version is fully locked — no updates unless manually changed |
4.17.0 stays exactly 4.17.0
|
Best for debugging, migrations, high-risk upgrades |
| Stability | Flexibility | Symbol |
|---|---|---|
| Most stable — never auto updates | Manual upgrades only | No symbol / pinned |
| Safe-ish — only patch fixes | No new features | ~ |
| Most flexible — minor + patch auto updates | Feature updates included | ^ |
Use ^ during normal development.
Use ~ when risk of breaking changes increases.
Use no symbol when debugging, refactoring, or locking down a production build.
- All developers must use same Node.js LTS
- Changelogs must reflect version history
- PRs should be clear + upgrade-focused
- Create one PR per upgrade or small group upgrade
- Include summary, changed packages, test results, and expected impact
- Reference relevant release notes
When Updates Break the Build
- Run tests immediately after each upgrade
- Check peer-dependency compatibility
- Revert if unresolved within reasonable timeframe
- Document fallbacks + retry later with more data
Version Tracking & Release Notes
- Document all changes at end of each sprint
- Include version jumps, conflicts & resolutions
- Use GitHub Release automations when possible
https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes