# Contributing to Strata Thank you for your interest in contributing to Strata! This document outlines the guidelines and process for contributing. --- ## Development Status **Strata is currently in active development (pre-alpha).** During this phase: - The API may change without notice - Features may be added, modified, or removed - Documentation may be incomplete - Not all edge cases are handled --- ## Contribution Policy ### Current Phase: Closed Development At this time, **external contributions are not being accepted**. This includes: - Pull requests - Feature implementations - Bug fixes (report only) ### What You Can Do 1. **Report Bugs**: Open an issue describing the bug 2. **Request Features**: Open an issue with your suggestion 3. **Ask Questions**: Use GitHub Discussions 4. **Provide Feedback**: Share your experience with the framework --- ## How to Create an Issue ### Step 1: Check Existing Issues Before creating a new issue, search existing issues to avoid duplicates: 1. Go to [github.com/CarGDev/strata/issues](https://github.com/CarGDev/strata/issues) 2. Use the search bar with keywords related to your issue 3. Check both **Open** and **Closed** issues 4. If you find a related issue, add a comment instead of creating a duplicate ### Step 2: Choose the Right Issue Type | Issue Type | When to Use | |------------|-------------| | **Bug Report** | Something isn't working as expected | | **Feature Request** | You want new functionality | | **Question** | Use GitHub Discussions instead | | **Documentation** | Docs are missing, unclear, or incorrect | ### Step 3: Create the Issue 1. Go to [github.com/CarGDev/strata/issues/new/choose](https://github.com/CarGDev/strata/issues/new/choose) 2. Select the appropriate issue template 3. Fill out all required sections 4. Add relevant labels if you have permission 5. Click **Submit new issue** ### Step 4: Follow Up - **Respond to questions** from maintainers promptly - **Provide additional info** if requested - **Test fixes** when a solution is proposed - **Close the issue** if you find the solution yourself --- ## Issue Templates ### Bug Report Template Use this template when reporting bugs: ```markdown ## Bug Report ### Summary A one-line description of the bug. ### Environment - **OS**: macOS 14.0 / Windows 11 / Ubuntu 22.04 - **Go version**: 1.21.0 - **Node version**: 18.0.0 - **Strata version**: 0.1.0 ### Steps to Reproduce 1. Create a new project with `npx create-strata-compile my-app` 2. Add a for loop in `index.strata` 3. Run `npm run dev` 4. Observe the error ### Expected Behavior The for loop should render all items in the array. ### Actual Behavior The page renders empty. Console shows: `[error message here]` ### Code Sample **index.strata** ```html \`\`\` **index.compiler.sts** \`\`\`javascript export const items = [ { name: 'Item 1' }, { name: 'Item 2' }, ]; \`\`\` ### Error Output \`\`\` [Paste full error message or stack trace here] \`\`\` ### Screenshots [If applicable, add screenshots to help explain the problem] ### Additional Context [Any other relevant information] ``` ### Feature Request Template Use this template when requesting features: ```markdown ## Feature Request ### Summary A one-line description of the feature. ### Problem Statement Describe the problem this feature would solve. Example: "Currently, there's no way to import components from other files, which means I have to copy-paste common UI elements across pages." ### Proposed Solution Describe how you envision this feature working. Example: "Add a `{ s-imp }` directive that allows importing components: `{ s-imp Button from '@components/Button' }`" ### Use Cases 1. Reusing header/footer across pages 2. Creating a component library 3. Sharing UI patterns between projects ### Alternatives Considered Other approaches you've thought about and why they don't work. ### Additional Context - Links to similar features in other frameworks - Mockups or diagrams - Priority level (nice-to-have vs. blocking) ``` ### Documentation Issue Template Use this template for documentation problems: ```markdown ## Documentation Issue ### Type - [ ] Missing documentation - [ ] Incorrect documentation - [ ] Unclear documentation - [ ] Typo or formatting issue ### Location [Link to the documentation page or file path] ### Current Content [What the docs currently say, if applicable] ### Suggested Change [What the docs should say] ### Additional Context [Why this change would help] ``` --- ## Issue Labels Understanding issue labels helps you categorize your report: | Label | Description | |-------|-------------| | `bug` | Something isn't working | | `feature` | New feature request | | `docs` | Documentation improvements | | `question` | Further information needed | | `good first issue` | Good for newcomers | | `help wanted` | Extra attention needed | | `priority: high` | Critical issue | | `priority: low` | Nice to have | | `wontfix` | Will not be addressed | | `duplicate` | Already reported | --- ## Tips for Good Issues ### Do - **Be specific**: Include exact error messages, not "it doesn't work" - **Be concise**: Get to the point quickly - **Use code blocks**: Format code with triple backticks - **Include versions**: Always mention OS, Go, Node, and Strata versions - **One issue per report**: Don't combine multiple bugs - **Search first**: Check if it's already reported ### Don't - **Don't be vague**: "The compiler is broken" is not helpful - **Don't include sensitive data**: No API keys, passwords, or personal info - **Don't bump issues**: Adding "+1" doesn't help (use reactions instead) - **Don't demand timelines**: This is open development - **Don't cross-post**: One issue in one place --- ## Code of Conduct ### Our Standards - Be respectful and inclusive - Provide constructive feedback - Focus on the issue, not the person - Accept responsibility for mistakes ### Unacceptable Behavior - Harassment or discrimination - Trolling or insulting comments - Personal or political attacks - Publishing private information --- ## Development Setup (For Authorized Contributors) If you have been authorized to contribute: ### Prerequisites ```bash # Required go version # 1.21+ node --version # 18+ make --version # Optional code --version # VSCode for development ``` ### Clone and Build ```bash # Clone repository git clone https://github.com/CarGDev/strata.git cd strata # Build the compiler make build # Run tests make test # Install locally make install ``` ### Project Structure ``` strata/ ├── cli/ │ └── create-strata/ # Project scaffolding tool ├── compiler/ │ ├── cmd/ │ │ └── strata/ # CLI entry point │ └── internal/ │ ├── ast/ # Abstract Syntax Tree │ ├── compiler/ # Static compiler │ ├── parser/ # Template parser │ ├── server/ # Dev server │ └── watcher/ # File watcher ├── runtime/ # Browser runtime (minimal) ├── templates/ # Project templates ├── examples/ # Example projects └── scripts/ # Build scripts ``` ### Coding Standards #### Go Code - Follow [Effective Go](https://golang.org/doc/effective_go) - Use `gofmt` for formatting - Add comments for exported functions - Write tests for new functionality ```go // Good // CompilePage compiles a page directory to static HTML. // It reads the .strata template and .compiler.sts variables, // resolves all directives, and returns pure HTML. func (c *StaticCompiler) CompilePage(pageDir string) (*CompiledModule, error) { // ... } ``` #### JavaScript/TypeScript - Use ES modules - Prefer `const` over `let` - No semicolons (project style) - Use meaningful variable names ```javascript // Good const formatDate = (date) => { return new Intl.DateTimeFormat('en-US').format(date) } // Bad var f = function(d) { return d.toString(); }; ``` ### Commit Messages Follow [Conventional Commits](https://www.conventionalcommits.org/): ``` (): [optional body] [optional footer] ``` Types: - `feat`: New feature - `fix`: Bug fix - `docs`: Documentation - `style`: Formatting (no code change) - `refactor`: Code restructuring - `test`: Adding tests - `chore`: Maintenance Examples: ``` feat(compiler): add support for nested loops fix(parser): handle escaped quotes in attributes docs(readme): update installation instructions ``` ### Branch Naming ``` feature/description fix/description docs/description refactor/description ``` Examples: ``` feature/add-component-imports fix/parser-nested-loops docs/update-api-reference ``` --- ## Testing ### Running Tests ```bash # All tests make test # Specific package go test ./compiler/internal/parser/... # With coverage go test -cover ./... ``` ### Writing Tests ```go func TestCompilePage_WithForLoop(t *testing.T) { compiler := NewStaticCompiler("/test/project") result, err := compiler.CompilePage("/test/project/src/pages/index") if err != nil { t.Fatalf("unexpected error: %v", err) } if !strings.Contains(result.HTML, "expected content") { t.Errorf("expected HTML to contain 'expected content', got: %s", result.HTML) } } ``` --- ## Review Process For authorized contributors: 1. Create a branch from `main` 2. Make your changes 3. Write/update tests 4. Update documentation 5. Submit a pull request 6. Address review feedback 7. Squash and merge when approved --- ## Questions? - **GitHub Issues**: For bugs and features - **GitHub Discussions**: For questions and ideas - **GitHub**: [@CarGDev](https://github.com/CarGDev) --- ## License Reminder By contributing to Strata, you agree that your contributions will be licensed under the same terms as the project. Currently, Strata is proprietary software under development. --- Thank you for your interest in Strata!