|
| 1 | +# Contributing to TechScript |
| 2 | + |
| 3 | +Thank you for deciding to contribute to TechScript! As an open-source project aiming to build a human-first programming language, we value your help in expanding the language features, stabilizing the VM, updating documentation, and building developer tools. |
| 4 | + |
| 5 | +--- |
| 6 | + |
| 7 | +## 🛠️ Setting Up Your Development Environment |
| 8 | + |
| 9 | +TechScript is written entirely in **Rust** as a Cargo workspace. To get started, make sure you have the following installed: |
| 10 | + |
| 11 | +1. **Rust Toolchain**: Install via rustup: |
| 12 | + ```bash |
| 13 | + curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh |
| 14 | + ``` |
| 15 | +2. **Git**: For version control. |
| 16 | +3. **Clang/LLVM** (Optional, required for LLVM-backend contributions): |
| 17 | + * **Ubuntu/Debian**: `sudo apt install llvm-dev libclang-dev` |
| 18 | + * **macOS**: Installed via Xcode CLI tools or homebrew (`brew install llvm`). |
| 19 | + * **Windows**: Download the LLVM installer or use `winget install LLVM.LLVM`. |
| 20 | + |
| 21 | +### Fork & Clone |
| 22 | +1. Fork the TechScript repository on GitHub. |
| 23 | +2. Clone your fork locally: |
| 24 | + ```bash |
| 25 | + git clone https://github.com/YOUR_USERNAME/techscript.git |
| 26 | + cd techscript |
| 27 | + ``` |
| 28 | +3. Add the upstream remote: |
| 29 | + ```bash |
| 30 | + git remote add upstream https://github.com/Tcode-Motion/techscript.git |
| 31 | + ``` |
| 32 | + |
| 33 | +--- |
| 34 | + |
| 35 | +## 📂 Repository Structure Overview |
| 36 | + |
| 37 | +The codebase is organized like Rust and Zig to keep compilation, execution, and tools clean: |
| 38 | + |
| 39 | +* `compiler/` - Lexer, parser, semantic analyzer, AST, IR, optimizer, and LLVM backend. |
| 40 | +* `runtime/` - Virtual Machine (VM), Tree-walking interpreter, garbage collector, and native runtime. |
| 41 | +* `stdlib/` - Standard library written in TechScript and Rust. |
| 42 | +* `cli/` - The unified `tech` command-line executable. |
| 43 | +* `tools/` - Formatter, linter, LSP, and package manager. |
| 44 | +* `examples/` - Working demonstration scripts. |
| 45 | +* `tests/` - System integration and language regression tests. |
| 46 | +* `benchmarks/` - Scripts and suites for testing engine performance. |
| 47 | + |
| 48 | +--- |
| 49 | + |
| 50 | +## 🔄 Development & Git Workflow |
| 51 | + |
| 52 | +We use a standard branching model. Always make changes on a descriptive branch, not on the `main` branch. |
| 53 | + |
| 54 | +### 1. Create a Branch |
| 55 | +```bash |
| 56 | +git checkout -b feature/my-cool-feature |
| 57 | +# or |
| 58 | +git checkout -b fix/issue-123 |
| 59 | +``` |
| 60 | + |
| 61 | +### 2. Make Edits & Run Linting |
| 62 | +We enforce strict styling and quality rules. Run these commands locally before committing: |
| 63 | +```bash |
| 64 | +# Verify formatting |
| 65 | +cargo fmt --all -- --check |
| 66 | + |
| 67 | +# Run linter |
| 68 | +cargo clippy --workspace --all-targets -- -D warnings |
| 69 | + |
| 70 | +# Build all workspace targets |
| 71 | +cargo build --workspace |
| 72 | +``` |
| 73 | + |
| 74 | +### 3. Run Tests |
| 75 | +Verify both Rust internal tests and TechScript integration tests pass: |
| 76 | +```bash |
| 77 | +cargo test --workspace |
| 78 | +``` |
| 79 | + |
| 80 | +### 4. Committing Changes |
| 81 | +We follow [Conventional Commits](https://www.conventionalcommits.org/): |
| 82 | +* `feat: ...` for new features or syntax. |
| 83 | +* `fix: ...` for compiler/runtime bug fixes. |
| 84 | +* `docs: ...` for documentation changes. |
| 85 | +* `style: ...` for formatting updates. |
| 86 | +* `refactor: ...` for code restructurings. |
| 87 | +* `test: ...` for adding/updating tests. |
| 88 | + |
| 89 | +Example: |
| 90 | +```bash |
| 91 | +git commit -m "feat: add support for pattern matching default keyword" |
| 92 | +``` |
| 93 | + |
| 94 | +--- |
| 95 | + |
| 96 | +## 📝 Pull Request Checklist |
| 97 | + |
| 98 | +Before submitting a Pull Request: |
| 99 | +- [ ] Ensure all code compiles without warning. |
| 100 | +- [ ] Run `cargo fmt` and `cargo clippy`. |
| 101 | +- [ ] Add corresponding documentation in `docs/` if modifying syntax, CLI flags, or standard libraries. |
| 102 | +- [ ] Add regression tests inside `tests/` or examples in `examples/`. |
| 103 | +- [ ] Link the issue you are fixing in the PR description (e.g., `Fixes #123`). |
| 104 | + |
| 105 | +Once submitted, our CI workflow will run automated checks on Windows, Linux, and macOS. A maintainer will review your code and request adjustments if necessary. |
0 commit comments