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

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

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

```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!