Skip to content

Commit 48b28b5

Browse files
WarforgeTechclaude
WarforgeTech
and
claude
committed
docs: Add open source files, CI workflow, and beginner tutorial
- Add CODE_OF_CONDUCT.md (Contributor Covenant based) - Add SECURITY.md with security policy and reporting guidelines - Add CONTRIBUTING.md with development setup and guidelines - Add LICENSE (MIT) - Add GitHub issue templates (bug report, feature request) - Add pull request template - Add CI workflow for build, lint, and example validation - Add comprehensive beginner tutorial (docs/TUTORIAL.md) - Builds a complete task manager step by step - Teaches Canon fundamentals through real examples - Follows causal-integrity teaching approach - Update .gitignore to exclude .claude/ directory - Update README with tutorial link 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 5801990 commit 48b28b5

File tree

11 files changed

+1608
-0
lines changed

11 files changed

+1608
-0
lines changed

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
name: Bug Report
3+
about: Report something that isn't working correctly
4+
title: '[BUG] '
5+
labels: bug
6+
assignees: ''
7+
---
8+
9+
## Description
10+
11+
A clear description of what the bug is.
12+
13+
## Steps to Reproduce
14+
15+
1. Run command '...'
16+
2. With input file '...'
17+
3. See error
18+
19+
## Expected Behavior
20+
21+
What you expected to happen.
22+
23+
## Actual Behavior
24+
25+
What actually happened.
26+
27+
## Environment
28+
29+
- OS: [e.g., macOS 14, Ubuntu 22.04]
30+
- Go version: [e.g., 1.22]
31+
- Canon version: [e.g., 1.0.0]
32+
33+
## Canon File (if applicable)
34+
35+
```json
36+
{
37+
"paste": "relevant canon.json here"
38+
}
39+
```
40+
41+
## Error Output
42+
43+
```
44+
paste error output here
45+
```
46+
47+
## Additional Context
48+
49+
Any other context about the problem.

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
---
2+
name: Feature Request
3+
about: Suggest an idea for Canon
4+
title: '[FEATURE] '
5+
labels: enhancement
6+
assignees: ''
7+
---
8+
9+
## Problem Statement
10+
11+
Describe the problem this feature would solve.
12+
13+
Example: "I'm always frustrated when..."
14+
15+
## Proposed Solution
16+
17+
Describe what you'd like to happen.
18+
19+
## Example Usage
20+
21+
Show how this feature would be used:
22+
23+
```json
24+
{
25+
"example": "canon.json showing the feature"
26+
}
27+
```
28+
29+
Or CLI usage:
30+
31+
```bash
32+
canon new-command --with-flag
33+
```
34+
35+
## Alternatives Considered
36+
37+
Describe any alternative solutions you've considered.
38+
39+
## Additional Context
40+
41+
Any other context, mockups, or examples.
42+
43+
## Checklist
44+
45+
- [ ] I've searched existing issues to ensure this isn't a duplicate
46+
- [ ] This aligns with Canon's goals (AI-native, capability-based, policy-enforced)

‎.github/pull_request_template.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
## Summary
2+
3+
Brief description of what this PR does.
4+
5+
## Changes
6+
7+
- Change 1
8+
- Change 2
9+
- Change 3
10+
11+
## Type of Change
12+
13+
- [ ] Bug fix (non-breaking change that fixes an issue)
14+
- [ ] New feature (non-breaking change that adds functionality)
15+
- [ ] Breaking change (fix or feature that would break existing functionality)
16+
- [ ] Documentation update
17+
- [ ] Refactoring (no functional changes)
18+
19+
## Testing
20+
21+
Describe how you tested these changes:
22+
23+
- [ ] Unit tests pass (`make test`)
24+
- [ ] Build succeeds (`make build`)
25+
- [ ] Manual testing performed
26+
27+
## Checklist
28+
29+
- [ ] My code follows the project's style guidelines
30+
- [ ] I have added tests that prove my fix/feature works
31+
- [ ] New and existing unit tests pass locally
32+
- [ ] I have updated documentation as needed
33+
- [ ] My changes generate no new warnings
34+
35+
## Related Issues
36+
37+
Fixes #(issue number)
38+
39+
## Additional Notes
40+
41+
Any additional information reviewers should know.

‎.github/workflows/ci.yml‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
build:
11+
runs-on: ubuntu-latest
12+
13+
steps:
14+
- uses: actions/checkout@v4
15+
16+
- name: Set up Go
17+
uses: actions/setup-go@v5
18+
with:
19+
go-version: '1.22'
20+
21+
- name: Install dependencies
22+
run: go mod download
23+
24+
- name: Build
25+
run: make build
26+
27+
- name: Run tests
28+
run: make test
29+
30+
lint:
31+
runs-on: ubuntu-latest
32+
33+
steps:
34+
- uses: actions/checkout@v4
35+
36+
- name: Set up Go
37+
uses: actions/setup-go@v5
38+
with:
39+
go-version: '1.22'
40+
41+
- name: Run go vet
42+
run: go vet ./...
43+
44+
- name: Check formatting
45+
run: |
46+
if [ -n "$(gofmt -l .)" ]; then
47+
echo "Code is not formatted. Run 'gofmt -w .'"
48+
gofmt -l .
49+
exit 1
50+
fi
51+
52+
examples:
53+
runs-on: ubuntu-latest
54+
needs: build
55+
56+
steps:
57+
- uses: actions/checkout@v4
58+
59+
- name: Set up Go
60+
uses: actions/setup-go@v5
61+
with:
62+
go-version: '1.22'
63+
64+
- name: Build Canon
65+
run: make build
66+
67+
- name: Validate examples
68+
run: |
69+
for f in examples/*//*.canon.json; do
70+
echo "Validating $f"
71+
./bin/canon validate "$f"
72+
done
73+
74+
- name: Build examples
75+
run: |
76+
./bin/canon build examples/hello/hello.canon.json
77+
./bin/canon build examples/http-service/service.canon.json
78+
./bin/canon build examples/enum-demo/status.canon.json
79+
./bin/canon build examples/data-pipeline/pipeline.canon.json

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,9 @@ go.work
3434
.DS_Store
3535
Thumbs.db
3636

37+
# Claude Code
38+
.claude/
39+
3740
# Node (for generated TypeScript)
3841
node_modules/
3942
package-lock.json

‎CODE_OF_CONDUCT.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Code of Conduct
2+
3+
## Our Pledge
4+
5+
We as members, contributors, and leaders pledge to make participation in our community a positive experience for everyone.
6+
7+
## Our Standards
8+
9+
Examples of behavior that contributes to a positive environment:
10+
11+
- Using welcoming and inclusive language
12+
- Being respectful of differing viewpoints and experiences
13+
- Gracefully accepting constructive feedback
14+
- Focusing on what is best for the community
15+
- Showing empathy towards other community members
16+
17+
Examples of unacceptable behavior:
18+
19+
- Trolling, insulting/derogatory comments, and personal attacks
20+
- Public or private communication that others find unwelcoming
21+
- Publishing others' private information without explicit permission
22+
- Other conduct which could reasonably be considered inappropriate
23+
24+
## Enforcement Responsibilities
25+
26+
Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, or harmful.
27+
28+
## Scope
29+
30+
This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces.
31+
32+
## Enforcement
33+
34+
Instances of unacceptable behavior may be reported to the community leaders responsible for enforcement at: **conduct@warforge.tech**
35+
36+
All complaints will be reviewed and investigated promptly and fairly.
37+
38+
## Attribution
39+
40+
This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

‎CONTRIBUTING.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# Contributing to Canon
2+
3+
Thank you for your interest in contributing to Canon! This document provides guidelines and instructions for contributing.
4+
5+
## Development Setup
6+
7+
### Prerequisites
8+
9+
- Go 1.22 or later
10+
- Node.js 18+ (for running generated TypeScript)
11+
- npm (for TypeScript dependencies)
12+
13+
### Getting Started
14+
15+
```bash
16+
# Clone the repository
17+
git clone https://github.com/WarforgeTech/canon.git
18+
cd canon
19+
20+
# Build the CLI
21+
make build
22+
23+
# Run tests
24+
make test
25+
26+
# Verify everything works
27+
./bin/canon build examples/hello/hello.canon.json
28+
```
29+
30+
## How to Contribute
31+
32+
### Reporting Bugs
33+
34+
1. Check if the bug has already been reported in [Issues](https://github.com/WarforgeTech/canon/issues)
35+
2. If not, create a new issue using the bug report template
36+
3. Include steps to reproduce, expected behavior, and actual behavior
37+
38+
### Suggesting Features
39+
40+
1. Check existing issues and discussions for similar ideas
41+
2. Create a new issue using the feature request template
42+
3. Describe the use case and why this feature would be valuable
43+
44+
### Submitting Code
45+
46+
1. Fork the repository
47+
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
48+
3. Make your changes
49+
4. Run tests (`make test`)
50+
5. Commit your changes with a clear message
51+
6. Push to your fork
52+
7. Open a Pull Request
53+
54+
## Code Style
55+
56+
### Go Code
57+
58+
- Follow standard Go conventions
59+
- Run `go fmt` before committing
60+
- Add tests for new functionality
61+
- Keep functions focused and well-documented
62+
63+
### TypeScript (runtime-ts/)
64+
65+
- Use TypeScript strict mode
66+
- Document public APIs with JSDoc comments
67+
68+
## Testing
69+
70+
### Running Tests
71+
72+
```bash
73+
# Run all Go tests
74+
make test
75+
76+
# Run tests with verbose output
77+
go test -v ./...
78+
79+
# Run a specific test
80+
go test -v ./pkg/validate -run TestTypechecking
81+
```
82+
83+
### Writing Tests
84+
85+
- Add unit tests for new functions in `*_test.go` files
86+
- Add integration tests for CLI commands in `cmd/canon/integration_test.go`
87+
- For Canon programs, add golden tests in the `.canon.json` file
88+
89+
## Pull Request Guidelines
90+
91+
- Keep PRs focused on a single change
92+
- Update documentation if needed
93+
- Ensure all tests pass
94+
- Add tests for new functionality
95+
- Reference related issues in the PR description
96+
97+
## Project Structure
98+
99+
```
100+
canon/
101+
├── cmd/canon/ # CLI commands
102+
├── pkg/
103+
│ ├── ir/ # Intermediate representation types
104+
│ ├── validate/ # Validation (schema, types, effects)
105+
│ ├── codegen/ # Code generation (TypeScript)
106+
│ ├── policy/ # OPA/Rego policy engine
107+
│ └── testing/ # Test runner
108+
├── runtime-ts/ # TypeScript runtime library
109+
├── schemas/ # JSON Schema definitions
110+
├── policies/ # Default Rego policies
111+
└── examples/ # Example Canon programs
112+
```
113+
114+
## Questions?
115+
116+
- Open a [Discussion](https://github.com/WarforgeTech/canon/discussions) for questions
117+
- Check the [documentation](docs/) for detailed specifications
118+
119+
## License
120+
121+
By contributing, you agree that your contributions will be licensed under the MIT License.

0 commit comments

Comments
 (0)