Skip to content

Commit c82e146

Browse files
speierspeier
committed
feat: Add comprehensive documentation for new DSL features and migration guide
- Introduced a new quick reference guide for DSL syntax improvements, including bulk environment variables and secrets path shorthand. - Expanded the "It's Just JavaScript!" documentation to emphasize the flexibility of Comet's DSL and provide examples of user-defined helper functions. - Created a detailed migration guide to assist users in upgrading to the new DSL features, ensuring backward compatibility. - Documented userland patterns to encourage users to create their own abstractions and helpers. - Added example stacks demonstrating the new DSL features, including bulk environment variables, shorthand secrets, and domain name helpers. - Implemented tests for new features to verify functionality and backward compatibility.
1 parent eb47912 commit c82e146

13 files changed

Lines changed: 2024 additions & 14 deletions

‎AGENTS.md‎

Lines changed: 302 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,302 @@
1+
# AGENTS.md - Guidelines for AI Agents Working on Comet
2+
3+
This document provides clear instructions for AI agents (like GitHub Copilot, Claude, ChatGPT, etc.) working on the Comet codebase.
4+
5+
## 🎯 Core Principles
6+
7+
### 1. **Code Over Documentation**
8+
- Focus on **writing code** that solves problems
9+
- Keep documentation **minimal and essential**
10+
- Don't create documentation for the sake of creating documentation
11+
- Only update docs when functionality actually changes
12+
13+
### 2. **No Random Markdown Generation**
14+
**❌ DO NOT:**
15+
- Create summary files after every change
16+
- Generate "IMPLEMENTATION_SUMMARY.md", "FINAL_SUMMARY.md", "SUCCESS.md", etc.
17+
- Create progress tracking documents
18+
- Make duplicate documentation
19+
- Create meta-documentation about what you just did
20+
21+
**✅ DO:**
22+
- Update existing relevant documentation (README.md, CHANGELOG.md)
23+
- Create documentation only for NEW user-facing features
24+
- Keep documentation in appropriate places (see structure below)
25+
26+
### 3. **Documentation Structure**
27+
28+
```
29+
Root Level:
30+
├── README.md (User-facing overview and quick start)
31+
├── CHANGELOG.md (Version history)
32+
├── CONTRIBUTING.md (If we have contribution guidelines)
33+
└── AGENTS.md (This file - for AI agents)
34+
35+
docs/:
36+
├── architecture.md (System design)
37+
├── best-practices.md (Usage recommendations)
38+
├── dsl-improvements.md (DSL features documentation)
39+
├── dsl-quick-reference.md (Quick syntax reference)
40+
├── userland-patterns.md (User-created patterns guide)
41+
├── its-just-javascript.md (JavaScript extensibility guide)
42+
└── cross-stack-references.md (Feature-specific docs)
43+
44+
stacks/_examples/:
45+
└── *.stack.js (Working code examples)
46+
```
47+
48+
**Do not create files like:**
49+
- ❌ IMPLEMENTATION_SUMMARY.md
50+
- ❌ FINAL_SUMMARY.md
51+
- ❌ SUCCESS.md
52+
- ❌ IMPLEMENTATION_COMPLETE.md
53+
- ❌ EMPHASIS_COMPLETE.md
54+
- ❌ Or any other meta-summary files
55+
56+
## 🛠️ Development Workflow
57+
58+
### When Implementing a Feature:
59+
60+
1. **Write the code** in appropriate Go files
61+
2. **Add tests** if applicable
62+
3. **Update CHANGELOG.md** with the change
63+
4. **Update README.md** only if it's a user-facing feature
64+
5. **Add documentation** in `docs/` only if it's a complex feature needing explanation
65+
6. **Add examples** in `stacks/_examples/` if it helps users understand
66+
67+
**Stop there.** Don't create summary files.
68+
69+
### When Fixing a Bug:
70+
71+
1. **Fix the code**
72+
2. **Update CHANGELOG.md** in the "Fixed" section
73+
3. **Done.** No documentation needed for most bug fixes.
74+
75+
### When Refactoring:
76+
77+
1. **Refactor the code**
78+
2. **Update CHANGELOG.md** if it affects users
79+
3. **Done.** Internal refactoring rarely needs documentation.
80+
81+
## 📝 Documentation Guidelines
82+
83+
### What to Document:
84+
85+
✅ **User-facing features** - How users interact with new functionality
86+
✅ **Breaking changes** - Migration guides when necessary
87+
✅ **Complex concepts** - Architecture decisions, design patterns
88+
✅ **API changes** - New functions, changed signatures
89+
✅ **Configuration options** - New settings in comet.yaml
90+
91+
### What NOT to Document:
92+
93+
❌ **Implementation details** - Code should be self-documenting
94+
❌ **Obvious functionality** - Don't over-explain simple code
95+
❌ **Work-in-progress** - No "TODO" documents
96+
❌ **Summary of what you just did** - No meta-documentation
97+
❌ **Multiple versions of the same info** - No duplication
98+
99+
### Documentation Style:
100+
101+
- **Concise** - Get to the point quickly
102+
- **Practical** - Show code examples
103+
- **Accurate** - Test examples before documenting
104+
- **Up-to-date** - Remove outdated info
105+
106+
## 🏗️ Code Guidelines
107+
108+
### Go Code:
109+
110+
- Follow existing code style in the project
111+
- Add comments for non-obvious logic
112+
- Keep functions small and focused
113+
- Use meaningful variable names
114+
- Handle errors appropriately
115+
116+
### File Structure:
117+
118+
```
119+
internal/
120+
├── parser/
121+
│ └── js/
122+
│ └── js.go (JavaScript parser/interpreter)
123+
├── schema/ (Data structures)
124+
├── secrets/ (Secrets management)
125+
├── exec/ (Terraform/OpenTofu execution)
126+
└── cli/ (CLI output formatting)
127+
128+
cmd/ (CLI commands)
129+
├── root.go
130+
├── plan.go
131+
├── apply.go
132+
└── ...
133+
```
134+
135+
### Adding New DSL Functions:
136+
137+
When adding new JavaScript functions available in stack files:
138+
139+
1. **Add the function** in `internal/parser/js/js.go`
140+
2. **Register it** in the `Parse()` method with `vm.rt.Set()`
141+
3. **Test it** with a real stack file
142+
4. **Document it** in `docs/dsl-quick-reference.md` (one place only!)
143+
5. **Add example** in `stacks/_examples/` if helpful
144+
145+
### Testing:
146+
147+
- Write tests for new functionality
148+
- Test with real stack files in `stacks/`
149+
- Don't create test-specific markdown documentation
150+
151+
## 🚫 Common Mistakes to Avoid
152+
153+
### ❌ Mistake 1: Documentation Proliferation
154+
```
155+
Agent creates:
156+
- IMPLEMENTATION_SUMMARY.md
157+
- FINAL_SUMMARY.md
158+
- SUCCESS.md
159+
- IMPLEMENTATION_COMPLETE.md
160+
```
161+
**Why it's bad:** Clutters the repository, duplicates information, confuses users.
162+
163+
**✅ Instead:** Update CHANGELOG.md and README.md only.
164+
165+
### ❌ Mistake 2: Over-documenting Obvious Code
166+
```markdown
167+
## The envs() Function
168+
This function sets environment variables...
169+
(20 more paragraphs explaining what environment variables are)
170+
```
171+
**Why it's bad:** Users don't need computer science lectures.
172+
173+
**✅ Instead:** Show a code example and move on.
174+
175+
### ❌ Mistake 3: Creating Duplicate Docs
176+
```
177+
Same information in:
178+
- README.md
179+
- docs/guide.md
180+
- docs/quickstart.md
181+
- docs/introduction.md
182+
```
183+
**Why it's bad:** Hard to maintain, versions get out of sync.
184+
185+
**✅ Instead:** One piece of information in one logical place.
186+
187+
## ✅ Good Examples
188+
189+
### Example 1: Adding a Feature
190+
191+
```
192+
Files changed:
193+
✓ internal/parser/js/js.go (code implementation)
194+
✓ CHANGELOG.md (added to unreleased)
195+
✓ docs/dsl-quick-reference.md (syntax added)
196+
✓ stacks/_examples/new-feature.js (working example)
197+
198+
Files NOT created:
199+
✗ IMPLEMENTATION_SUMMARY.md
200+
✗ FEATURE_COMPLETE.md
201+
```
202+
203+
### Example 2: Fixing a Bug
204+
205+
```
206+
Files changed:
207+
✓ internal/exec/tf/terraform.go (bug fix)
208+
✓ CHANGELOG.md (noted in "Fixed" section)
209+
210+
Files NOT created:
211+
✗ BUG_FIX_SUMMARY.md
212+
✗ Any other documentation
213+
```
214+
215+
### Example 3: Refactoring
216+
217+
```
218+
Files changed:
219+
✓ internal/parser/parser.go (refactored code)
220+
✓ CHANGELOG.md (only if user-visible)
221+
222+
Files NOT created:
223+
✗ REFACTORING_NOTES.md
224+
✗ CODE_IMPROVEMENTS.md
225+
```
226+
227+
## 📋 Checklist for Agents
228+
229+
Before completing a task, verify:
230+
231+
- [ ] Code is written and tested
232+
- [ ] CHANGELOG.md is updated (if user-visible change)
233+
- [ ] README.md is updated (if major feature)
234+
- [ ] Existing docs are updated (if behavior changed)
235+
- [ ] Examples added (if helpful for understanding)
236+
- [ ] **Did NOT create summary/meta documentation files**
237+
- [ ] **Did NOT duplicate information across files**
238+
- [ ] **Did NOT over-document obvious functionality**
239+
240+
## 🎓 Philosophy
241+
242+
**Comet's philosophy extends to documentation:**
243+
244+
> Provide **minimal, essential documentation**. Users are smart - they can read code and examples. Don't patronize them with verbose explanations.
245+
246+
**Code > Docs**
247+
248+
- Good code is self-documenting
249+
- Examples are better than prose
250+
- Less is more
251+
252+
## 🤝 When in Doubt
253+
254+
**Ask yourself:**
255+
256+
1. Does this documentation help users accomplish a task?
257+
2. Is this information already documented elsewhere?
258+
3. Will this document need to be maintained?
259+
4. Is this creating noise in the repository?
260+
261+
**If unsure, default to:**
262+
- ✅ Update CHANGELOG.md
263+
- ✅ Update README.md if truly necessary
264+
- ❌ Don't create new markdown files
265+
266+
## 📚 Required Reading
267+
268+
Before working on Comet, understand:
269+
270+
1. **Philosophy:** Minimal, unopinionated tooling
271+
2. **DSL Design:** JavaScript superset, users build their own abstractions
272+
3. **Documentation:** Essential only, no fluff
273+
274+
## 🔄 This File
275+
276+
**AGENTS.md itself should be:**
277+
- Updated when development guidelines change
278+
- Kept concise and practical
279+
- The **single source of truth** for AI agent guidelines
280+
281+
**AGENTS.md should NOT be:**
282+
- A changelog of agent activities
283+
- A list of every task completed
284+
- Documentation about documentation
285+
286+
---
287+
288+
## Summary
289+
290+
**TL;DR for AI Agents:**
291+
292+
1. **Write code, not documentation**
293+
2. **Update CHANGELOG.md for changes**
294+
3. **Update README.md for major features**
295+
4. **Don't create random markdown files**
296+
5. **Keep it simple**
297+
298+
**When you finish a task, stop.** Don't create summary files. The git commit message is your summary.
299+
300+
---
301+
302+
*Last updated: 2025-10-07*

‎CHANGELOG.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,18 +8,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
88
## [Unreleased]
99

1010
### Added
11+
- **DSL Improvements** - Two core enhancements to reduce boilerplate by ~30%:
12+
- Bulk environment variables: `envs({})` accepts objects to set multiple vars at once
13+
- Secrets path shorthand: New `secret()` function with configurable defaults and dot notation support
14+
- **"It's Just JavaScript!" philosophy** - Emphasized that users can create any helper functions they need
15+
- **AGENTS.md** - Guidelines for AI agents working on the codebase
1116
- Comprehensive comparison table with Terragrunt, Atmos, and plain OpenTofu
1217
- "Why Comet?" section explaining benefits and use cases
1318
- Architecture documentation (`docs/architecture.md`)
1419
- Best practices guide (`docs/best-practices.md`)
20+
- DSL improvements documentation (`docs/dsl-improvements.md`)
21+
- DSL quick reference guide (`docs/dsl-quick-reference.md`)
22+
- **Userland patterns guide (`docs/userland-patterns.md`)** - Comprehensive guide on building your own abstractions
23+
- **"It's Just JavaScript!" guide (`docs/its-just-javascript.md`)** - Prominent documentation emphasizing extensibility
24+
- Example stacks demonstrating new features and patterns
1525
- `export` command for generating standalone Terraform files
1626
- Integration tests for basic CLI operations
1727
- Advanced examples in README
1828
- Enhanced feature descriptions in README
1929

2030
### Changed
2131
- Enhanced README with better feature descriptions and emojis
32+
- **Emphasized JavaScript extensibility** throughout documentation
2233
- Improved documentation structure
34+
- `envs()` function now accepts both old syntax (key, value) and new object syntax for backward compatibility
2335

2436
### Fixed
2537
- (List any bugs fixed in future releases)

‎Makefile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
VERSION=v0.4.0
1+
VERSION=v0.4.1
22

33
tag:
44
@git tag -a ${VERSION} -m "version ${VERSION}" && git push origin ${VERSION}

0 commit comments

Comments
 (0)