d4ea931bf8
* feat(agents): add modular engineering rules from 2026 standards Add a rules directory with individual rule files derived from the Cal.com Engineering in 2026 and Beyond blog post. Rules are organized by section (architecture, quality, data, api, performance, testing, patterns, culture) following the Vercel agent-skills structure. Includes: - _sections.md defining rule categories and impact levels - _template.md for creating new rules - 14 individual rule files covering key engineering standards - README documenting the rules structure and usage Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> * feat(agents): consolidate DI and Repository+DTO docs into rules - Move di-pattern.md content to rules/patterns-di-pattern.md - Extract Repository + DTO section from knowledge-base.md into: - rules/data-repository-methods.md (method naming conventions) - rules/data-dto-boundaries.md (DTO location and naming) - Update knowledge-base.md to reference the new rule files - Delete old di-pattern.md file Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> * chore(agents): remove stub reference sections from knowledge-base.md The rules directory is self-contained with its own README, so these redirect sections are unnecessary clutter. Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> * refactor(agents): combine DI pattern rules into single file Merged patterns-di-pattern.md into patterns-dependency-injection.md to eliminate overlap and create one comprehensive DI guide. Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --------- Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
61 lines
1.7 KiB
Markdown
61 lines
1.7 KiB
Markdown
---
|
|
title: Never Introduce Breaking API Changes
|
|
impact: CRITICAL
|
|
impactDescription: Maintains developer trust and prevents integration nightmares
|
|
tags: api, stability, versioning, backwards-compatibility
|
|
---
|
|
|
|
## Never Introduce Breaking API Changes
|
|
|
|
**Impact: CRITICAL**
|
|
|
|
Once an API endpoint is public, it must remain stable. Breaking changes destroy developer trust and create integration nightmares for our users.
|
|
|
|
**Strategies for avoiding breaking changes:**
|
|
- Always add new fields as optional
|
|
- Use API versioning when you must change existing behavior
|
|
- Deprecate old endpoints gracefully with clear migration paths
|
|
- Maintain backward compatibility for at least two major versions
|
|
|
|
**Incorrect (breaking change):**
|
|
|
|
```typescript
|
|
// v1 - Original response
|
|
interface BookingResponse {
|
|
id: number;
|
|
startTime: string; // ISO string
|
|
}
|
|
|
|
// v1 - Breaking change: renamed field
|
|
interface BookingResponse {
|
|
id: number;
|
|
start: string; // Renamed from startTime - BREAKS CLIENTS
|
|
}
|
|
```
|
|
|
|
**Correct (non-breaking evolution):**
|
|
|
|
```typescript
|
|
// v1 - Original response
|
|
interface BookingResponse {
|
|
id: number;
|
|
startTime: string;
|
|
}
|
|
|
|
// v1 - Non-breaking: add new field, keep old one
|
|
interface BookingResponse {
|
|
id: number;
|
|
startTime: string; // Keep for backwards compatibility
|
|
start: string; // New preferred field
|
|
}
|
|
```
|
|
|
|
**When you must make breaking changes:**
|
|
- Create a new API version using date-specific versioning in API v2
|
|
- Run both versions simultaneously during transition
|
|
- Provide automated migration tools when possible
|
|
- Give users ample time to migrate (minimum 6 months for public APIs)
|
|
- Document exactly what changed and why
|
|
|
|
Reference: [Cal.com Engineering Blog](https://cal.com/blog/engineering-in-2026-and-beyond)
|