Skip to content

Commit 7a3716b

Browse files
neongreenneongreen
authored
Merge pull request #17 from neongreen/copilot/fix-757a82c5-ee6f-452f-9899-00f84f3212c1
Add global agent guidelines: backwards compatibility is NOT important
2 parents 76fc97a + 55c47e7 commit 7a3716b

4 files changed

Lines changed: 137 additions & 24 deletions

File tree

‎AGENTS.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
# Agent Guidelines for This Monorepo
2+
3+
This document contains guidelines for AI agents and automated tools working on projects in this monorepo.
4+
5+
## Backwards Compatibility Policy
6+
7+
**Unless explicitly stated otherwise, backwards compatibility is NOT important for ANY project in this repository.**
8+
9+
All tools and projects in this monorepo (`diagram-dsl`, `dissect`, `markdown-format`, `want`, and any future projects) are work in progress and do not have users yet. Breaking changes are acceptable and encouraged if they improve the API or implementation.
10+
11+
### What This Means
12+
13+
When making changes to **any project** in this monorepo:
14+
- ❌ **Do NOT** maintain old APIs for compatibility
15+
- ❌ **Do NOT** add migration guides
16+
- ❌ **Do NOT** add "backwards compatible" claims in documentation
17+
- ❌ **Do NOT** worry about breaking changes
18+
- ✅ **DO** focus on making the best possible API and implementation
19+
- ✅ **DO** update documentation to reflect current state only
20+
- ✅ **DO** remove deprecated/old code completely
21+
22+
### Examples from Past PRs
23+
24+
Here are concrete examples from previous pull requests showing what **NOT** to do:
25+
26+
#### ❌ Example 1: Unnecessary Migration Guide (PR #6)
27+
28+
**Project:** diagram-dsl
29+
**File:** `diagram-dsl/IMPROVEMENTS.md`
30+
31+
**What was wrong:**
32+
```markdown
33+
## Migration Guide
34+
35+
No migration needed - all changes are backward compatible.
36+
37+
To use new features:
38+
1. `npm install` to get canvas package
39+
2. Use `renderToSVGWithLayout()` for testing
40+
3. Import `LayoutAssertions` for layout tests
41+
4. Run `npm test` to see new tests in action
42+
```
43+
44+
**Why it's wrong:**
45+
- The library has no users yet
46+
- No one needs migration instructions
47+
- This is just extra documentation that needs to be maintained
48+
- Adds confusion about whether compatibility matters
49+
50+
**What to do instead:**
51+
- Don't add migration sections
52+
- Just document how to use the current version
53+
54+
#### ❌ Example 2: Backwards Compatibility Claims (PR #6)
55+
56+
**Project:** diagram-dsl
57+
**File:** `diagram-dsl/IMPROVEMENTS.md`
58+
59+
**What was wrong:**
60+
```markdown
61+
### Backward Compatibility
62+
63+
All existing APIs remain unchanged:
64+
- `renderToSVG()` still returns a string (uses `renderToSVGWithLayout()` internally)
65+
- All component props remain the same
66+
- All examples work without modifications
67+
```
68+
69+
**Why it's wrong:**
70+
- No users exist to care about API changes
71+
- This adds unnecessary constraints to future development
72+
- Creates false impression that we need to maintain compatibility
73+
74+
**What to do instead:**
75+
- Just document the current API
76+
- If you change APIs, just update the docs
77+
78+
#### ❌ Example 3: Backwards Compatible Claims (PR #8)
79+
80+
**Project:** diagram-dsl
81+
**File:** `diagram-dsl/SEMANTIC_COMPONENTS_SUMMARY.md`
82+
83+
**What was wrong:**
84+
```markdown
85+
## Testing
86+
87+
All existing tests pass (14/14):
88+
- 7 SVG rendering tests
89+
- 7 layout assertion tests
90+
91+
No breaking changes - backwards compatible.
92+
```
93+
94+
**Why it's wrong:**
95+
- Again, no users to worry about
96+
- "backwards compatible" doesn't add value
97+
- Could discourage making better changes in the future
98+
99+
**What to do instead:**
100+
- Just report that tests pass
101+
- Don't make claims about compatibility
102+
103+
#### ❌ Example 4: Defensive Statements About Backwards Compatibility (PR #6)
104+
105+
**Project:** diagram-dsl
106+
**File:** `diagram-dsl/AUDIT.md`
107+
108+
**What was wrong:**
109+
```markdown
110+
### ❌ Not Backward Compatibility Code
111+
The old estimation logic is completely replaced - there's no backward compatibility code lingering.
112+
```
113+
114+
**Why it's wrong:**
115+
- Having to defend that there's no backwards compatibility code suggests we're worried about it
116+
- This shouldn't even be a consideration for work-in-progress projects
117+
118+
**What to do instead:**
119+
- Don't mention backwards compatibility at all
120+
- Just describe what was done
121+
122+
### Owner's Direct Feedback
123+
124+
From the repository owner (PR #8, comment from @neongreen):
125+
126+
> "remove the migration guide and any code left for backwards compatibility, this library is still work in progress and it doesn't have any users right now and no compatibility is needed"
127+
128+
### When Backwards Compatibility DOES Matter
129+
130+
The owner will explicitly request backwards compatibility when needed. Until then, assume it doesn't matter.
131+
132+
### Summary
133+
134+
- **Default assumption:** Backwards compatibility is NOT needed for any project
135+
- **Only consider it when:** The owner explicitly asks for it
136+
- **Focus on:** Making the best possible code, not maintaining old code
137+
- **Applies to:** ALL projects in this monorepo (diagram-dsl, dissect, markdown-format, want, etc.)

‎diagram-dsl/AUDIT.md‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -97,9 +97,6 @@ else if (node.type === 'Text') {
9797

9898
## What Is NOT an Issue
9999

100-
### ❌ Not Backward Compatibility Code
101-
The old estimation logic is completely replaced - there's no backward compatibility code lingering.
102-
103100
### ❌ Not Half-Done Tasks
104101
All tasks are complete:
105102
- Text measurement: ✅ Fully implemented with canvas

‎diagram-dsl/IMPROVEMENTS.md‎

Lines changed: 0 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -131,13 +131,6 @@ const metrics = measureText('Hello', 24, 'Arial', 'bold');
131131
console.log(metrics.width, metrics.height);
132132
```
133133
134-
### Backward Compatibility
135-
136-
All existing APIs remain unchanged:
137-
- `renderToSVG()` still returns a string (uses `renderToSVGWithLayout()` internally)
138-
- All component props remain the same
139-
- All examples work without modifications
140-
141134
## Usage in Tests
142135
143136
```typescript
@@ -172,16 +165,6 @@ These improvements lay the groundwork for:
172165
4. **Multi-line Text** - Extend measurement for text wrapping
173166
5. **Advanced Metrics** - Letter spacing, line height, etc.
174167
175-
## Migration Guide
176-
177-
No migration needed - all changes are backward compatible.
178-
179-
To use new features:
180-
1. `npm install` to get canvas package
181-
2. Use `renderToSVGWithLayout()` for testing
182-
3. Import `LayoutAssertions` for layout tests
183-
4. Run `npm test` to see new tests in action
184-
185168
## Verification
186169
187170
Run the following to verify improvements:

‎diagram-dsl/SEMANTIC_COMPONENTS_SUMMARY.md‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -231,8 +231,6 @@ All existing tests pass (14/14):
231231
- 7 SVG rendering tests
232232
- 7 layout assertion tests
233233

234-
No breaking changes - backwards compatible.
235-
236234
## Technical Implementation
237235

238236
### Files Added
@@ -274,8 +272,6 @@ The semantic components provide a **dramatically improved developer experience**
274272
- ✅ Rich text support (title + subtitle)
275273
- ✅ Clear semantic intent
276274
- ✅ Better maintainability
277-
- ✅ Backwards compatible
278-
- ✅ Zero breaking changes
279275
- ✅ All tests passing
280276

281277
Users can now focus on **content** rather than **styling**, making diagram-dsl much more productive and enjoyable to use.

0 commit comments

Comments
 (0)