strata-compile/CONTRIBUTING.md

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
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
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:

## 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 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
<template>
  { s-for item in items }
    <div>{ item.name }</div>
  { /s-for }
</template>
\`\`\`

**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:

## 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:

## 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

# Required
go version    # 1.21+
node --version # 18+
make --version

# Optional
code --version # VSCode for development

Clone and Build

# 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
• Use gofmt for formatting
• Add comments for exported functions
• Write tests for new functionality

// 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

// 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:

<type>(<scope>): <description>

[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

# All tests
make test

# Specific package
go test ./compiler/internal/parser/...

# With coverage
go test -cover ./...

Writing Tests

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

---

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!