[Policy]: Define policy for deprecated interfaces #105
Description
Documentation Location
CONTRIBUTING.md, docs/deprecation-policy.md
Issue Description
Background
OpenSSF Best Practices (Silver) requirement interfaces_deprecation requires projects to have a documented policy for handling deprecated external interfaces. This includes:
- How deprecation is announced
- How long deprecated interfaces are maintained
- How users migrate to replacements
- How breaking changes are communicated
Current State
| Component | Status |
|---|---|
| Deprecation policy documented | ❌ Missing |
| Deprecation announcement process | ❌ Not defined |
| Migration guidance process | ❌ Not defined |
| Versioning/changelog | ❌ No formal versioning |
Evidence
- No deprecation policy exists
- No CHANGELOG.md
- No versioning scheme documented
- OpenSSF Silver requirement: interfaces_deprecation
Suggested Fix
1. Add deprecation policy to CONTRIBUTING.md
## Deprecation Policy
### Scope
This policy applies to:
- Shell script interfaces (arguments, environment variables)
- Terraform module inputs/outputs
- Configuration file schemas
- Directory structure conventions users depend on
### Deprecation Process
When an interface needs to change or be removed:
1. **Announcement** — Document deprecation in:
- README.md under "Deprecations" section
- Release notes (if using releases)
- Deprecation comment in code where applicable
2. **Deprecation period** — Maintain deprecated interface for:
- 1 major release, OR
- 90 days from announcement, whichever is longer
3. **Migration guidance** — Provide:
- Clear migration path in deprecation notice
- Examples of new approach
- Tooling/scripts to assist migration if complex
4. **Removal** — After deprecation period:
- Remove deprecated interface
- Document removal in release notes
### Communication Channels
| Change Type | Communication |
|-------------|---------------|
| Deprecation | README "Deprecations" section |
| Migration path | Documentation update with examples |
| Removal | Release notes |
| Emergency removal (security) | Same plus GitHub Security Advisory |
### Example Deprecation Notice
In README.md:
```markdown
## Deprecations
### `deploy/old-script.sh` (deprecated 2024-03-01)
**Replacement:** `deploy/002-setup/new-script.sh`
**Migration:** Rename script calls and update environment variables:
- `OLD_VAR` → `NEW_VAR`
- `--old-flag` → `--new-flag`
**Removal planned:** 2024-06-01No Breaking Changes Without Notice
We commit to not removing or changing interfaces without:
- Prior deprecation notice
- Migration guidance
- Reasonable deprecation period
Emergency security fixes may bypass this process if necessary, with explanation.
### 2. Add deprecations section to README.md (placeholder)
```markdown
## Deprecations
There are currently no deprecated interfaces. See [Deprecation Policy](CONTRIBUTING.md#deprecation-policy) for how we handle changes.
Acceptance Criteria
- Deprecation policy is documented in CONTRIBUTING.md
- Scope of policy is defined (what interfaces are covered)
- Deprecation process is defined (announce, period, migrate, remove)
- Deprecation period is specified (90 days or 1 major release)
- Migration guidance requirements are documented
- README has "Deprecations" section (even if empty)
Dependencies
None
Validation
- Review CONTRIBUTING.md for deprecation policy
- Verify deprecation period is reasonable
- Confirm migration guidance requirements are clear
- Check README has deprecations placeholder section
OpenSSF IDs: interfaces_deprecation