1  # Contributing to Planar.jl
  2  
  3  Thank you for your interest in contributing to Planar.jl! This document provides guidelines for contributing to the project, with special attention to documentation standards.
  4  
  5  ## Getting Started
  6  
  7  1. Fork the repository
  8  2. Clone your fork with submodules:
  9     ```bash
 10     git clone --recurse-submodules https://github.com/yourusername/Planar.jl
 11     cd Planar.jl
 12     direnv allow
 13     ```
 14  3. Set up the development environment:
 15     ```bash
 16     julia --project=Planar
 17     ] instantiate
 18     ```
 19  
 20  ## Types of Contributions
 21  
 22  ### Code Contributions
 23  - Bug fixes
 24  - New features
 25  - Performance improvements
 26  - Test coverage improvements
 27  
 28  ### Documentation Contributions
 29  - Fixing errors in existing documentation
 30  - Adding new guides and tutorials
 31  - Improving code examples
 32  - Updating API documentation
 33  
 34  ### Other Contributions
 35  - Reporting bugs
 36  - Suggesting features
 37  - Improving CI/CD
 38  - Community support
 39  
 40  ## Documentation Standards
 41  
 42  ### Code Block Requirements
 43  
 44  All code blocks in documentation must follow these standards to ensure they pass the automated testing suite:
 45  
 46  #### 1. Self-Contained Examples
 47  Every code block should be executable independently:
 48  
 49  ```julia
 50  # ✅ Good - includes all necessary imports
 51  using Planar
 52  using TimeTicks
 53  
 54  # Your example code here
 55  ```
 56  
 57  #### 2. Project Activation
 58  When using different Planar modules, explicitly activate the correct project:
 59  
 60  ```julia
 61  # For basic Planar features
 62  import Pkg
 63  Pkg.activate("Planar")
 64  using Planar
 65  
 66  # For interactive features (plotting, optimization)
 67  import Pkg
 68  Pkg.activate("PlanarInteractive")
 69  using PlanarInteractive
 70  @environment!
 71  ```
 72  
 73  #### 3. Variable Definitions
 74  Define all variables used in examples:
 75  
 76  ```julia
 77  # ✅ Good - variables are defined
 78  exchange_name = "binance"
 79  pair = "BTC/USDT"
 80  timeframe = tf"1h"
 81  
 82  # Use variables in your example
 83  @info "Fetching data for $pair from $exchange_name"
 84  ```
 85  
 86  #### 4. Error Handling
 87  Include appropriate error handling for robustness:
 88  
 89  ```julia
 90  # ✅ Good - handles potential errors
 91  try
 92      exchange = getexchange!(:binance)
 93      data = fetch_ohlcv(exchange, tf"1h", "BTC/USDT"; from=-100)
 94      @info "Successfully fetched $(nrow(data)) candles"
 95  catch e
 96      @warn "Data fetch failed: $e"
 97      @info "This is normal without proper API configuration"
 98  end
 99  ```
100  
101  #### 5. Module Scoping
102  When showing strategy examples, use proper module structure:
103  
104  ```julia
105  # ✅ Good - properly scoped strategy module
106  module ExampleStrategy
107  using Planar
108  
109  const DESCRIPTION = "Example strategy"
110  const EXC = :binance
111  const MARGIN = NoMargin
112  const TF = tf"1h"
113  
114  @strategyenv!
115  
116  function call!(::Type{<:SC}, ::LoadStrategy, config)
117      # Strategy implementation
118  end
119  
120  end
121  ```
122  
123  ### Testing Documentation
124  
125  Before submitting documentation changes:
126  
127  1. **Test individual code blocks**:
128     ```bash
129     julia --project=Planar -e "
130     # Paste your code block here to test it
131     "
132     ```
133  
134  2. **Run the full documentation test suite**:
135     ```bash
136     julia --project=Planar docs/test/runtests.jl --skip-external --verbose
137     ```
138  
139  3. **Check for common issues**:
140     - All imports are included
141     - Variables are defined before use
142     - Realistic example values are used
143     - Error handling is appropriate
144     - Code blocks are properly scoped
145  
146  ### Documentation Guidelines Reference
147  
148  For detailed guidelines on writing testable documentation, see:
149  - [Documentation Code Block Guidelines](docs/DOCUMENTATION_CODE_BLOCK_GUIDELINES.md)
150  
151  ## Code Style
152  
153  ### Julia Code
154  - Follow [Blue Style](https://github.com/invenia/BlueStyle) formatting
155  - Use JuliaFormatter with the project's `.JuliaFormatter.toml`
156  - Maximum line length: 92 characters
157  - Use descriptive variable names
158  - Add docstrings for public functions
159  
160  ### Documentation
161  - Use clear, concise language
162  - Include working code examples
163  - Add proper frontmatter to documentation files:
164    ```yaml
165    ---
166    title: "Clear, descriptive title"
167    description: "1-2 sentence summary"
168    category: "getting-started|guides|advanced|reference|troubleshooting"
169    difficulty: "beginner|intermediate|advanced"
170    ---
171    ```
172  
173  ## Submission Process
174  
175  ### Pull Request Guidelines
176  
177  1. **Create a feature branch**:
178     ```bash
179     git checkout -b feature/your-feature-name
180     # or
181     git checkout -b docs/your-documentation-improvement
182     ```
183  
184  2. **Make your changes**:
185     - Follow the coding standards
186     - Add tests for new functionality
187     - Update documentation as needed
188     - Test your changes thoroughly
189  
190  3. **Commit with conventional format**:
191     ```bash
192     git commit -m "feat: add new strategy optimization feature"
193     git commit -m "docs: improve data management guide with error handling"
194     git commit -m "fix: resolve import conflicts in strategy examples"
195     ```
196  
197  4. **Submit pull request**:
198     - Use a clear, descriptive title
199     - Include a detailed description of changes
200     - Reference any related issues
201     - Ensure all tests pass
202  
203  ### PR Review Process
204  
205  1. Automated checks must pass:
206     - Code formatting (JuliaFormatter)
207     - Documentation tests
208     - Unit tests
209     - Integration tests
210  
211  2. Manual review focuses on:
212     - Code quality and design
213     - Documentation clarity
214     - Test coverage
215     - Breaking changes
216  
217  3. Address review feedback promptly
218  
219  ## Development Setup
220  
221  ### Environment Variables
222  Check and configure the environment variables in `.envrc`:
223  ```bash
224  export JULIA_PROJECT=Planar  # or PlanarInteractive
225  export JULIA_NUM_THREADS=auto
226  # ... other variables
227  ```
228  
229  ### Testing
230  Run tests before submitting:
231  ```bash
232  # Unit tests
233  julia --project=Planar -e "using Pkg; Pkg.test()"
234  
235  # Documentation tests
236  julia --project=Planar docs/test/runtests.jl
237  
238  # Integration tests (if applicable)
239  julia --project=Planar test/integration/runtests.jl
240  ```
241  
242  ### Building Documentation
243  To build documentation locally:
244  ```bash
245  julia --project=docs docs/make.jl
246  ```
247  
248  ## Community Guidelines
249  
250  ### Code of Conduct
251  - Be respectful and inclusive
252  - Focus on constructive feedback
253  - Help newcomers learn and contribute
254  - Maintain a professional tone in all interactions
255  
256  ### Getting Help
257  - Check existing documentation and issues first
258  - Use GitHub Discussions for questions
259  - Join the Discord server for real-time help
260  - Tag maintainers only when necessary
261  
262  ### Reporting Issues
263  When reporting bugs:
264  1. Use the issue template
265  2. Include minimal reproduction steps
266  3. Provide system information
267  4. Include relevant logs/error messages
268  
269  ## Recognition
270  
271  Contributors are recognized in:
272  - Git commit history
273  - Release notes for significant contributions
274  - Documentation acknowledgments
275  - Community highlights
276  
277  ## Questions?
278  
279  If you have questions about contributing:
280  - Check the [documentation](https://defnlnotme.github.io/Planar.jl/)
281  - Open a GitHub Discussion
282  - Join our Discord server
283  - Review existing issues and PRs
284  
285  Thank you for contributing to Planar.jl!