github.com/grafana/pyroscope@v1.18.0/.cursor/rules/development-workflow.mdc (about)

     1  ---
     2  description: Development workflow, commands, and commit guidelines for Pyroscope
     3  globs:
     4  alwaysApply: false
     5  ---
     6  
     7  # Development Workflow
     8  
     9  ## Prerequisites
    10  
    11  - Go 1.24+
    12  - Docker
    13  - Node v18
    14  - Yarn v1.22
    15  - All other tools auto-download to `.tmp/bin/`
    16  
    17  ## Build Commands
    18  
    19  ```bash
    20  # Build backend
    21  make go/bin
    22  
    23  # Run Go tests
    24  make go/test
    25  
    26  # Build frontend
    27  yarn install
    28  yarn dev          # Dev server on :4041
    29  
    30  # Run backend for frontend development
    31  yarn backend:dev  # Runs Pyroscope server
    32  
    33  # Docker image
    34  make GOOS=linux GOARCH=amd64 docker-image/pyroscope/build
    35  ```
    36  
    37  ## Running Locally
    38  
    39  ```bash
    40  # Run all components in monolithic mode with embedded Grafana
    41  go run ./cmd/pyroscope --target all,embedded-grafana
    42  # Pyroscope: http://localhost:4040
    43  # Grafana: http://localhost:4041
    44  ```
    45  
    46  ## Code Generation
    47  
    48  **CRITICAL**: After changing protobuf, configs, or flags:
    49  
    50  ```bash
    51  make generate
    52  ```
    53  
    54  Commit the generated files with your changes.
    55  
    56  ## Useful Make Targets
    57  
    58  ```bash
    59  make help              # Show all available targets
    60  make lint              # Run linters
    61  make go/test           # Run Go unit tests
    62  make go/bin            # Build binaries
    63  make go/mod            # Tidy go modules
    64  make generate          # Generate code (protobuf, mocks, etc.)
    65  make docker-image/pyroscope/build  # Build Docker image
    66  ```
    67  
    68  ## Commit Guidelines
    69  
    70  1. **Atomic Commits**: Each commit should be a logical unit
    71  2. **Commit Messages**: Focus on "why" not just "what"
    72  3. **Generated Code**: Include generated files in the same commit as source changes
    73  4. **Format**: Follow existing commit message style (see `git log --oneline -20`)
    74  
    75  ## When Working on Features
    76  
    77  1. **Read Component Docs**: Check `docs/sources/reference-pyroscope-architecture/components/` for the component you're modifying
    78  2. **Understand the Ring**: If working on write/read path, understand consistent hashing
    79  3. **Multi-tenancy First**: Always consider multi-tenant implications
    80  4. **Check for Similar Code**: Pyroscope is inspired by Cortex/Mimir - similar patterns apply
    81  5. **Test Multi-tenancy**: Test with multiple tenants to catch isolation issues
    82  6. **Profile Your Changes**: Use `go test -bench` and verify performance impact
    83  7. **Update Documentation**: If changing user-facing behavior, update docs
    84  
    85  ## Documentation Locations
    86  
    87  - **User Docs**: `docs/sources/` - Published to grafana.com
    88  - **Contributing**: `docs/internal/contributing/README.md`
    89  - **Component Docs**: `docs/sources/reference-pyroscope-architecture/components/`
    90  
    91  ## Getting Help
    92  
    93  - **Contributing Guide**: `docs/internal/contributing/README.md`
    94  - **Code Comments**: The codebase has extensive comments - read them
    95  - **Git History**: Use `git blame` and `git log` to understand design decisions