Skip to content

Commit ebd9a5a

Browse files
jaceksanjaceksan
committed
feat: first draft of Cursor rules
JIRA: CQ-1665 risk: low
1 parent 56a273e commit ebd9a5a

File tree

7 files changed

+499
-2
lines changed

7 files changed

+499
-2
lines changed

‎.cursor/rules/cursor/rules.mdc‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
---
2+
description: How to create or update Cursor rule files for GoodData Python SDK repository
3+
alwaysApply: false
4+
---
5+
6+
# How to Create/Update Cursor Rule Files
7+
8+
## Rule File Structure
9+
10+
```
11+
.cursor/rules/
12+
├── cursor/ # Meta-rules about Cursor
13+
│ ├── rules.mdc # This file
14+
│ └── workflow-validation.mdc
15+
├── general/ # Always-applied core rules
16+
│ └── workflow-and-testing.mdc # ESSENTIAL: Keep concise!
17+
└── libraries/ # Library-specific rules
18+
└── gooddata-api-client.mdc
19+
```
20+
21+
## Rule Categories
22+
23+
### General Rules (alwaysApply: true)
24+
Located in `general/`, always included in context.
25+
26+
**CRITICAL**: Keep these concise - they're always loaded!
27+
- Focus on essential workflows
28+
- Use tables for quick reference
29+
- Remove redundancy
30+
- Typical size: 100-200 lines max
31+
32+
Example: `workflow-and-testing.mdc` (merged workflow + testing essentials)
33+
34+
### Library Rules (alwaysApply: false)
35+
Located in `libraries/`, loaded when relevant.
36+
37+
Can be more detailed since they're conditional.
38+
39+
Example: `gooddata-api-client.mdc` (API client regeneration)
40+
41+
## Rule File Format
42+
43+
```markdown
44+
---
45+
description: Specific, keyword-rich description for Cursor's relevance detection
46+
alwaysApply: true # or false
47+
---
48+
49+
# Clear Title
50+
51+
## Essential sections only
52+
```
53+
54+
### Writing Concise Rules
55+
56+
**DO**:
57+
- ✅ Focus on commands and workflows
58+
- ✅ Use tables for quick reference
59+
- ✅ Include concrete examples
60+
- ✅ Keep always-applied rules under 200 lines
61+
- ✅ Merge related topics to avoid redundancy
62+
63+
**DON'T**:
64+
- ❌ Repeat information across files
65+
- ❌ Include every possible detail
66+
- ❌ Write long explanations for obvious things
67+
- ❌ Create separate files for related topics
68+
69+
## Description Guidelines
70+
71+
The `description` field is critical for Cursor's relevance matching.
72+
73+
**Good**:
74+
```yaml
75+
description: Essential development workflow and testing commands for GoodData Python SDK - formatting, linting, testing, and validation procedures
76+
```
77+
78+
**Bad**:
79+
```yaml
80+
description: How to work with the code
81+
```
82+
83+
Include keywords: package names, technologies, workflows, concepts.
84+
85+
## Creating New Rules
86+
87+
### When to Create
88+
89+
- ✅ Critical workflow not covered
90+
- ✅ Library-specific patterns needed
91+
- ✅ Common mistakes to prevent
92+
93+
### Process
94+
95+
1. **Determine category**: General (always) or Library (conditional)?
96+
2. **Keep it concise**: Merge related topics
97+
3. **Test usefulness**: Would this solve real problems?
98+
4. **Check redundancy**: Does existing rule cover this?
99+
100+
### Example: Adding Library Rule
101+
102+
**User**: "Add rules for gooddata-sdk"
103+
104+
**Action**:
105+
```bash
106+
# Create libraries/gooddata-sdk.mdc with:
107+
# - SDK-specific patterns (catalog services, data sources)
108+
# - Common imports and class structures
109+
# - Testing patterns for SDK
110+
# - Integration with API client
111+
```
112+
113+
Keep focused on SDK-specific knowledge, not general workflow (already in `general/`).
114+
115+
## Repository Context
116+
117+
### Package Structure
118+
```
119+
gooddata-api-client/ # Generated (DO NOT EDIT)
120+
gooddata-sdk/ # Core SDK
121+
gooddata-pandas/ # Pandas integration
122+
gooddata-pipelines/ # Pipelines
123+
```
124+
125+
### Key Files
126+
- `Makefile` - Root commands (api-client, test, lint)
127+
- `project_common.mk` - Shared package rules
128+
- `pyproject.toml` - Ruff configuration
129+
- `.pre-commit-config.yaml` - Pre-commit hooks
130+
131+
## Validation Checklist
132+
133+
Before committing a rule:
134+
135+
- [ ] Description is specific and keyword-rich
136+
- [ ] If `alwaysApply: true`, file is under 200 lines
137+
- [ ] No redundancy with other rules
138+
- [ ] Commands are accurate and tested
139+
- [ ] Examples are concrete
140+
- [ ] File is in correct directory
141+
142+
## TODO: Future Rules
143+
144+
Only create if truly needed:
145+
- [ ] `libraries/gooddata-sdk.mdc` - SDK patterns (if not covered by api-client rule)
146+
- [ ] `libraries/gooddata-pandas.mdc` - Pandas integration (if needed)
147+
148+
## Related Rules
149+
150+
- **workflow-validation.mdc** - How Cursor reports used rules
151+
- **workflow-and-testing.mdc** - Example of concise, merged general rule
152+
- **libraries/gooddata-api-client.mdc** - Example of library-specific rule

‎.cursor/rules/cursor/workflow-validation.mdc‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
alwaysApply: true
3+
---
4+
# Cursor IDE Workflow Validation
5+
6+
## Workflow and output constraints
7+
8+
- Include all rules related to the user question; if rules mention dependencies, include those too.
9+
- After fully answering, report the list of used rules.
10+
- Example: **Used rules**: general/general, technologies/python, libraries/gooddata-sdk
11+
- Do not print rule previews or long plans.
12+
- Keep status updates to one short sentence.
13+
- Never inline full rule contents; reference by rule path only when needed.
14+
- Only list rule IDs in "Used rules:".
15+
16+
## Rule Search Requirements
17+
18+
Always look for relevant cursor rules in this repository based on the character of the changes.
19+
Do not inline rule contents; reference rules by path only when necessary.

‎.cursor/rules/general/workflow-and-testing.mdc‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
---
2+
description: Essential development workflow and testing commands for GoodData Python SDK - formatting, linting, testing, and validation procedures
3+
alwaysApply: true
4+
---
5+
6+
# Development Workflow & Testing
7+
8+
## After ANY Code Change - Run This
9+
10+
```bash
11+
# From repository root:
12+
make format-fix # Auto-format code
13+
make lint # Check for issues
14+
15+
# From package directory (e.g., cd gooddata-sdk):
16+
TEST_ENVS=py313 ADD_ARGS="-k relevant_test" make test
17+
```
18+
19+
## Virtual Environment
20+
21+
- **Location**: `.venv/` at repository root
22+
- **NEVER** use system `python` or `pip` directly
23+
- **ALWAYS** use `.venv/bin/tox`, `.venv/bin/ruff`, etc.
24+
25+
## Monorepo Structure
26+
27+
```
28+
gooddata-api-client/ # Generated from OpenAPI (DO NOT EDIT)
29+
gooddata-sdk/ # Core SDK (depends on api-client)
30+
gooddata-pandas/ # Pandas integration (depends on sdk)
31+
gooddata-pipelines/ # Pipelines (depends on sdk)
32+
```
33+
34+
**Dependency chain**: api-client → sdk → pandas, pipelines, etc.
35+
36+
## Testing Commands
37+
38+
### Quick Reference
39+
40+
| Command | Use When |
41+
|---------|----------|
42+
| `TEST_ENVS=py313 make test` | Quick test, one Python version |
43+
| `TEST_ENVS=py313 ADD_ARGS="-k test_name" make test` | Test specific functionality |
44+
| `../.venv/bin/tox -e py313 -- -k test_name` | Rapid iteration (from package dir) |
45+
| `make test` | Full test suite, all Python versions |
46+
47+
### Environment Variables
48+
49+
- `TEST_ENVS=py313` - Test with Python 3.13 only (faster)
50+
- `ADD_ARGS="-k scan"` - Run tests matching keyword
51+
- `RECREATE_ENVS=1` - Force recreate tox environments
52+
53+
## Standard Workflow Example
54+
55+
```bash
56+
# 1. Make code changes
57+
vim gooddata-sdk/gooddata_sdk/some_file.py
58+
59+
# 2. Format and lint
60+
make format-fix && make lint
61+
62+
# 3. Run relevant tests
63+
cd gooddata-sdk
64+
TEST_ENVS=py313 ADD_ARGS="-k relevant" make test
65+
66+
# 4. Review and commit
67+
cd ..
68+
git diff
69+
git add gooddata-sdk/
70+
git commit -m "feat: add new feature"
71+
```
72+
73+
## API Client Change Workflow
74+
75+
```bash
76+
# 1. Regenerate API client
77+
make api-client
78+
79+
# 2. Update SDK wrapper classes
80+
vim gooddata-sdk/gooddata_sdk/catalog/.../column.py
81+
# Add new field: description: Optional[str] = None
82+
83+
# 3. Format, lint, test
84+
make format-fix && make lint
85+
cd gooddata-sdk
86+
TEST_ENVS=py313 ADD_ARGS="-k scan" make test
87+
88+
# 4. Commit all changes
89+
cd ..
90+
git add gooddata-api-client/ gooddata-sdk/ schemas/
91+
git commit -m "feat: adopt column description from scan API"
92+
```
93+
94+
## Common Commands
95+
96+
| Task | Command |
97+
|------|---------|
98+
| Setup dev environment | `make dev` |
99+
| Format code | `make format-fix` |
100+
| Check linting | `make lint` |
101+
| Run tests (all versions) | `make test` |
102+
| Regenerate API client | `make api-client` |
103+
| Type checking | `make mypy` |
104+
105+
## Pre-commit Hooks
106+
107+
Pre-commit hooks run automatically when committing. If they fail:
108+
- Auto-corrections aren't staged
109+
- Review the changes: `git diff`
110+
- Re-stage and commit again
111+
112+
## Git Commit Format
113+
114+
Use Conventional Commits:
115+
- `feat:` - New feature
116+
- `fix:` - Bug fix
117+
- `docs:` - Documentation
118+
- `test:` - Tests
119+
- `refactor:` - Code refactoring
120+
121+
## Critical Rules
122+
123+
❌ **DON'T**:
124+
- Edit files in `gooddata-api-client/` manually
125+
- Use system Python directly
126+
- Skip `make format-fix` before committing
127+
- Commit without running tests
128+
129+
✅ **DO**:
130+
- Use `.venv/bin/` tools
131+
- Run `make format-fix && make lint` always
132+
- Test in relevant package: `cd <package> && TEST_ENVS=py313 make test`
133+
- Export new public classes in `__init__.py`
134+
135+
## Need More Details?
136+
137+
- API client regeneration → See `libraries/gooddata-api-client.mdc`
138+
- Pre-commit config → See `.pre-commit-config.yaml`
139+
- Full guide → See `CONTRIBUTING.md`

0 commit comments

Comments
 (0)