This repository was archived by the owner on Mar 11, 2026. It is now read-only.
This repository was archived by the owner on Mar 11, 2026. It is now read-only.
docs(docs): Document update process for reused components #104
Description
Documentation Location
CONTRIBUTING.md, docs/dependencies.md
Issue Description
Background
OpenSSF Best Practices (Silver) requirement documentation_reuse_component_update requires projects to document the process for updating reused (external) components. This includes:
- How dependency updates are identified
- How updates are vetted and tested
- When updates should be applied
- How breaking changes in dependencies are handled
Current State
| Component | Status |
|---|---|
| Dependency update process | |
| Update vetting process | ❌ Not documented |
| Breaking change handling | ❌ Not documented |
| Component inventory |
Evidence
- Dependabot is configured but process for handling its PRs isn't documented
- requirements.txt exists but no process for updating it
- Terraform versions are specified but update process not documented
- OpenSSF Silver requirement: documentation_reuse_component_update
Suggested Fix
1. Add component update process to CONTRIBUTING.md
## Updating External Components
### Identifying Updates
We use these tools to identify available updates:
| Component Type | Tool | Configuration |
|----------------|------|---------------|
| Python packages | Dependabot | .github/dependabot.yml |
| Terraform providers | Dependabot | .github/dependabot.yml |
| GitHub Actions | Dependabot | .github/dependabot.yml |
| Helm charts | Manual | Check upstream releases |
### Update Process
1. **Review Dependabot PR** — Check the changelog and release notes
2. **Assess impact** — Determine if it's a patch, minor, or major update
3. **Test locally** — For major updates, test deployment locally
4. **Verify CI passes** — Ensure all checks pass
5. **Merge or close** — Merge if safe, close with reason if not
### Update Vetting Criteria
Before merging dependency updates:
- [ ] Release notes reviewed for breaking changes
- [ ] Security implications assessed
- [ ] CI tests pass
- [ ] For Terraform: `terraform plan` shows expected changes
- [ ] For Python: Core functionality verified
### Breaking Changes in Dependencies
When an upstream dependency has breaking changes:
1. Open an issue to track the upgrade
2. Assess scope of changes needed
3. Create a PR with all necessary changes
4. Update documentation if user-facing behavior changes
5. Consider whether this requires a major version bump for this project
### Component Inventory
Key external components tracked:
| Component | Current Version | Location |
|-----------|-----------------|----------|
| Terraform AzureRM | See deploy/001-iac/versions.tf | Terraform |
| Helm charts | See deploy/002-setup/values/ | Kubernetes |
| Python packages | See requirements.txt | Training scripts |
| Azure ML SDK | See src/training/requirements.txt | ML |2. Document in README or dedicated file
For larger inventories, create docs/dependencies.md with full component list and update process.
Acceptance Criteria
- Component update identification tools are documented
- Update process (review, test, merge) is documented
- Vetting criteria checklist exists
- Breaking change handling process is documented
- Key component inventory is maintained
- Dependabot configuration is referenced
Dependencies
None
Validation
- Review CONTRIBUTING.md for component update section
- Verify process covers all component types (Python, Terraform, Actions)
- Confirm vetting criteria are practical and complete
- Check breaking change process is clear
OpenSSF IDs: documentation_reuse_component_update