git commit -m "feat: initial release of Strata framework v0.1.0
- Static compiler with STRC pattern (Static Template Resolution with
Compartmentalized Layers)
- Template syntax: { } interpolation, { s-for }, { s-if/s-elif/s-else
}
- File types: .strata, .compiler.sts, .service.sts, .api.sts, .sts,
.scss
- CLI tools: strata dev, strata build, strata g (generators)
- create-strata scaffolding CLI with Pokemon API example
- Dev server with WebSocket HMR (Hot Module Replacement)
- Documentation: README, ARCHITECTURE, CHANGELOG, CONTRIBUTING,
LICENSE
This commit is contained in:
458
CONTRIBUTING.md
Normal file
458
CONTRIBUTING.md
Normal file
@@ -0,0 +1,458 @@
|
||||
# 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 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!
|
||||
Reference in New Issue
Block a user