Always provide clear documentation and implementation for caching strategies, including key generation, invalidation policies, and default behaviors. When implementing caching:
- Choose appropriate cache keys that balance specificity and reusability:
- For CI environments, consider using commit SHA with restore-keys fallback:
```yaml
- uses: actions/cache@v4
with:
path: .turbo
key: ${{ runner.os }}-turbo-${{ github.sha }}
restore-keys: |
${{ runner.os }}-turbo-
```
- Document cache configuration options explicitly:
- Explain what happens when cache configuration is missing
- Specify available cache sources and their permissions (e.g., local vs. remote)
- Describe the behavior of cache invalidation
- Make cache behavior predictable and configurable:
- Allow users to control cache sources (e.g.,
--cache=local:rw,remote:r)
- Provide clear indicators when caching is enabled/disabled
- Document which artifacts will be cached by default
Proper cache strategy documentation prevents unexpected behavior, improves performance, and gives users control over how and where their data is cached.