proagents 1.0.0

package/proagents/api-versioning/README.md

@@ -0,0 +1,257 @@
+# API Versioning
+
+Manage API versions, deprecation, and backward compatibility.
+
+---
+
+## Overview
+
+API versioning ensures smooth evolution of your APIs while maintaining backward compatibility for existing clients. ProAgents helps you manage API versions throughout the development lifecycle.
+
+---
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Versioning Strategy](./versioning-strategy.md) | URL vs header versioning, semantic versioning |
+| [Deprecation Workflow](./deprecation-workflow.md) | Deprecation timeline, migration guides |
+| [Changelog Template](./changelog-template.md) | API changelog format and automation |
+
+---
+
+## Versioning Strategies
+
+### 1. URL-Based Versioning (Recommended)
+
+```
+https://api.example.com/v1/users
+https://api.example.com/v2/users
+```
+
+**Pros:**
+- Clear and explicit
+- Easy to understand
+- Cache-friendly
+- Easy to test
+
+**Cons:**
+- URL changes between versions
+- Multiple endpoints to maintain
+
+### 2. Header-Based Versioning
+
+```http
+GET /users HTTP/1.1
+Accept: application/vnd.api+json;version=2
+```
+
+**Pros:**
+- Clean URLs
+- Same resource URL across versions
+
+**Cons:**
+- Less visible
+- Harder to test in browser
+- Cache configuration needed
+
+### 3. Query Parameter Versioning
+
+```
+https://api.example.com/users?version=2
+```
+
+**Pros:**
+- Simple to implement
+- Easy to test
+
+**Cons:**
+- Not RESTful
+- Caching issues
+
+---
+
+## Quick Start
+
+```yaml
+# proagents.config.yaml
+api_versioning:
+  strategy: "url"              # url | header | query
+  current_version: "v2"
+  supported_versions: ["v1", "v2"]
+  deprecation_notice: "6 months"
+
+  # Version lifecycle
+  lifecycle:
+    alpha: "unstable, may change"
+    beta: "stable, may have bugs"
+    stable: "production ready"
+    deprecated: "will be removed"
+    sunset: "no longer available"
+```
+
+---
+
+## Version Lifecycle
+
+```
+Alpha → Beta → Stable → Deprecated → Sunset
+  ↓       ↓       ↓          ↓          ↓
+Unstable  Testing  Current    Notice     Removed
+```
+
+### Timeline Example
+
+| Version | Status | Date | Notes |
+|---------|--------|------|-------|
+| v1 | Deprecated | 2024-01 | Migration notice sent |
+| v1 | Sunset | 2024-07 | No longer available |
+| v2 | Stable | 2024-01 | Current version |
+| v3 | Beta | 2024-06 | Testing phase |
+
+---
+
+## Commands
+
+```bash
+# Check API compatibility between versions
+proagents api check-compatibility v1 v2
+
+# Generate API changelog
+proagents api changelog
+
+# Generate migration guide
+proagents api migration-guide v1 v2
+
+# Mark version deprecated
+proagents api deprecate v1 --sunset "2024-06-01"
+
+# Check for breaking changes
+proagents api breaking-changes v1 v2
+
+# Validate API schema
+proagents api validate-schema
+```
+
+---
+
+## Breaking vs Non-Breaking Changes
+
+### Breaking Changes (Require New Version)
+
+| Change Type | Example |
+|-------------|---------|
+| Remove endpoint | DELETE /api/v1/legacy |
+| Remove field | Remove `user.username` |
+| Rename field | `user_id` → `userId` |
+| Change field type | `id: number` → `id: string` |
+| Add required field | Add required `email` |
+| Change HTTP method | GET → POST |
+| Change authentication | API key → OAuth |
+
+### Non-Breaking Changes (Same Version)
+
+| Change Type | Example |
+|-------------|---------|
+| Add endpoint | New POST /api/v1/preferences |
+| Add optional field | Add `user.nickname` |
+| Add enum value | Status: `active` → `active, pending` |
+| Widen type | `int` → `number` |
+| Deprecate (not remove) | Mark field deprecated |
+| Add optional parameter | Add `?limit=10` |
+
+---
+
+## Deprecation Process
+
+### Phase 1: Announcement (T-6 months)
+- Add deprecation warnings to responses
+- Update documentation
+- Notify API consumers
+
+### Phase 2: Migration Support (T-3 months)
+- Provide migration guides
+- Offer migration tools/scripts
+- Support both versions
+
+### Phase 3: Final Notice (T-1 month)
+- Send final reminders
+- Reduce support for deprecated version
+- Track remaining usage
+
+### Phase 4: Sunset (T-0)
+- Remove deprecated version
+- Return 410 Gone for old endpoints
+- Archive documentation
+
+---
+
+## Response Headers
+
+```http
+HTTP/1.1 200 OK
+X-API-Version: 2
+X-API-Deprecated: true
+X-API-Sunset: 2024-06-01
+Link: <https://api.example.com/v2/users>; rel="successor-version"
+```
+
+---
+
+## Changelog Format
+
+```markdown
+# API Changelog
+
+## [v2.1.0] - 2024-01-15
+
+### Added
+- `GET /users/{id}/preferences` - Fetch user preferences
+- `POST /users/{id}/avatar` - Upload user avatar
+
+### Changed
+- `GET /users` now supports pagination (breaking: removed `all` parameter)
+
+### Deprecated
+- `GET /users/{id}/settings` - Use `/preferences` instead
+
+### Removed
+- None
+
+### Fixed
+- Fixed rate limit calculation for authenticated requests
+
+### Security
+- Added input validation for user search endpoint
+```
+
+---
+
+## Integration with Development
+
+### During Implementation
+- Check for breaking changes before implementation
+- Generate version comparison reports
+- Suggest migration strategies
+
+### During Testing
+- Test against multiple API versions
+- Verify backward compatibility
+- Check deprecation warnings
+
+### During Documentation
+- Generate version-specific docs
+- Create migration guides
+- Update changelog automatically
+
+---
+
+## Best Practices
+
+1. **Version early** - Add versioning from the start
+2. **Document changes** - Keep detailed changelogs
+3. **Communicate** - Give advance notice of breaking changes
+4. **Support transitions** - Maintain deprecated versions during migration
+5. **Monitor usage** - Track version usage to guide sunset decisions
+6. **Test thoroughly** - Test both old and new versions
+7. **Use semantic versioning** - Major.Minor.Patch for clear communication

package/proagents/api-versioning/changelog-template.md

@@ -0,0 +1,225 @@
+# API Changelog Template
+
+Document API changes for each version.
+
+---
+
+## Changelog Format
+
+```markdown
+# API Changelog
+
+All notable changes to the API are documented here.
+
+## [v2.1.0] - 2024-01-15
+
+### Added
+- `GET /users/{id}/preferences` - Fetch user preferences
+- `PUT /users/{id}/preferences` - Update user preferences
+- `avatar_url` field to user response
+
+### Changed
+- `POST /auth/login` now returns refresh token in response body
+- Rate limit increased from 100 to 200 requests/minute
+
+### Deprecated
+- `GET /users/{id}/settings` - Use `/preferences` instead (removal: v3.0.0)
+
+### Fixed
+- Fixed pagination returning duplicate items
+- Fixed date format inconsistency in responses
+
+### Security
+- Added rate limiting to password reset endpoint
+
+---
+
+## [v2.0.0] - 2024-01-01
+
+### Breaking Changes
+- Response wrapper: All responses now wrapped in `{ data: ... }`
+- Authentication: Moved from query parameter to Bearer token
+- User ID: Changed from integer to UUID
+
+### Added
+- `POST /auth/refresh` - Refresh access token
+- `DELETE /users/{id}` - Delete user account
+- Pagination metadata in list responses
+
+### Changed
+- Error response format standardized
+- All timestamps now in ISO 8601 format
+
+### Removed
+- `GET /users/search` - Use query parameters on `GET /users` instead
+- `api_key` query parameter authentication
+
+### Migration
+See [v1 to v2 Migration Guide](./migration/v1-to-v2.md)
+```
+
+---
+
+## Entry Types
+
+### Added
+New endpoints, fields, or features.
+
+```markdown
+### Added
+- `GET /products/{id}/reviews` - List product reviews
+- `rating` field added to product response
+- Support for `sort` query parameter on list endpoints
+```
+
+### Changed
+Modifications to existing behavior.
+
+```markdown
+### Changed
+- `POST /orders` now requires `shipping_address` field
+- Default page size changed from 10 to 20
+- Error messages now include request ID
+```
+
+### Deprecated
+Features marked for future removal.
+
+```markdown
+### Deprecated
+- `GET /legacy/users` - Use `GET /users` instead
+  - Deprecation date: 2024-03-01
+  - Removal date: 2024-09-01
+  - Migration guide: [link]
+```
+
+### Removed
+Features that have been removed.
+
+```markdown
+### Removed
+- `GET /v1/users` - Sunset completed
+- `api_key` authentication method
+- `legacy_id` field from user response
+```
+
+### Fixed
+Bug fixes.
+
+```markdown
+### Fixed
+- Fixed 500 error when email contains special characters
+- Fixed incorrect count in pagination response
+- Fixed timezone handling in date filters
+```
+
+### Security
+Security-related changes.
+
+```markdown
+### Security
+- Added CSRF protection to all state-changing endpoints
+- Implemented rate limiting on authentication endpoints
+- Fixed XSS vulnerability in user bio field
+```
+
+---
+
+## Version Entry Template
+
+```markdown
+## [vX.Y.Z] - YYYY-MM-DD
+
+### Summary
+Brief description of this release.
+
+### Breaking Changes
+- [List breaking changes with migration instructions]
+
+### Added
+- [New endpoint/feature] - [Description]
+
+### Changed
+- [Modified behavior] - [What changed]
+
+### Deprecated
+- [Feature] - [Replacement and timeline]
+
+### Removed
+- [Feature] - [Reason]
+
+### Fixed
+- [Bug] - [What was fixed]
+
+### Security
+- [Security improvement]
+
+### Documentation
+- [Documentation updates]
+
+### Internal
+- [Internal changes not affecting API consumers]
+```
+
+---
+
+## Automation
+
+### Auto-Generate Changelog Entry
+
+```yaml
+# When creating PR for API changes
+api_changelog:
+  auto_generate: true
+
+  detect_from:
+    - route_changes
+    - schema_changes
+    - middleware_changes
+
+  require_entry_for:
+    - breaking_changes
+    - new_endpoints
+    - deprecated_features
+```
+
+### PR Template for API Changes
+
+```markdown
+## API Change Description
+
+### Type of Change
+- [ ] New endpoint
+- [ ] Modified endpoint
+- [ ] Deprecated endpoint
+- [ ] Breaking change
+- [ ] Bug fix
+- [ ] Security fix
+
+### Changelog Entry
+```
+### Added/Changed/Deprecated/Fixed
+- [Your changelog entry here]
+```
+
+### Breaking Change Details
+If breaking change, describe:
+- What breaks
+- Migration steps
+- Timeline
+
+### Documentation
+- [ ] API docs updated
+- [ ] Changelog updated
+- [ ] Migration guide created (if breaking)
+```
+
+---
+
+## Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/api-changelog add` | Add changelog entry |
+| `/api-changelog view` | View API changelog |
+| `/api-changelog generate` | Auto-generate from changes |