Prepare for 0.3.0 release by updating documentation and versioning

OMouta · OMouta · commit 76c4e1505bc4 · 2025-11-01T15:38:50.000Z
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -9,15 +9,15 @@ body:
         Thanks for reporting a bug in **PyLua v0.3**.
 
         Please include a minimal repro and exact environment so we can reproduce. PyLua targets Python 3.12 and below.
-        Docs: https://github.com/OMouta/PyLua/blob/master/docs/README.md • Roadmap: https://github.com/OMouta/PyLua/blob/master/internalDocs/REWRITE_PLAN.md
+  Docs: https://github.com/OMouta/PyLua/blob/master/docs/README.md • Roadmap: https://github.com/OMouta/PyLua/blob/master/internalDocs/ROADMAP.md
 
   - type: dropdown
     id: version
     attributes:
       label: "PyLua Version"
       description: "Which version/build are you on?"
       options:
-        - "v0.3.x (current rewrite in src/PyLua)"
+        - "v0.3.x (current; src/PyLua)"
         - "v0.2 (legacy; see docs/0.2)"
         - "Custom build/fork"
         - "Not sure"
@@ -109,8 +109,8 @@ body:
     id: commit
     attributes:
       label: "PyLua Commit or Version"
-      description: "Example: 0.3.0-dev2 or commit SHA"
-      placeholder: "0.3.0-dev2 / a1b2c3d"
+      description: "Example: 0.3.0 or commit SHA"
+      placeholder: "0.3.0 / a1b2c3d"
     validations:
       required: false
 
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
@@ -3,9 +3,9 @@ contact_links:
   - name: Documentation (public)
     url: https://github.com/OMouta/PyLua/blob/master/docs/README.md
     about: Read the docs for usage, architecture, and examples
-  - name: Development Plan
-    url: https://github.com/OMouta/PyLua/blob/master/internalDocs/REWRITE_PLAN.md
-    about: Check the current development phase and roadmap
+  - name: Roadmap
+    url: https://github.com/OMouta/PyLua/blob/master/internalDocs/ROADMAP.md
+    about: Check planned milestones and future work
   - name: Contributing Guide
     url: https://github.com/OMouta/PyLua/blob/master/CONTRIBUTING.md
     about: Learn how to contribute to PyLua v0.3
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -9,7 +9,7 @@ body:
         Thanks for proposing a feature for **PyLua v0.3**.
 
         Please check the docs/roadmap to ensure fit with Python 3.12 compliance and current phases.
-        Docs: https://github.com/OMouta/PyLua/blob/master/docs/README.md • Roadmap: https://github.com/OMouta/PyLua/blob/master/internalDocs/REWRITE_PLAN.md
+        Docs: https://github.com/OMouta/PyLua/blob/master/docs/README.md • Roadmap: https://github.com/OMouta/PyLua/blob/master/internalDocs/ROADMAP.md
 
   - type: dropdown
     id: feature-type
@@ -30,7 +30,7 @@ body:
   - type: dropdown
     id: development-phase
     attributes:
-      label: "Phase Alignment (from REWRITE_PLAN)"
+  label: "Phase Alignment (from ROADMAP)"
       options:
         - "Phase 1: Foundation (lexer, tokens, AST)"
         - "Phase 2: Parser (expressions, statements, postfix)"
@@ -139,7 +139,7 @@ body:
       options:
         - label: "Searched existing issues"
           required: true
-        - label: "Reviewed REWRITE_PLAN.md for phase fit"
+  - label: "Reviewed ROADMAP.md for phase fit"
           required: true
         - label: "Provided motivation and (if possible) example"
           required: true
diff --git a/.github/ISSUE_TEMPLATE/question.yml b/.github/ISSUE_TEMPLATE/question.yml
@@ -11,7 +11,7 @@ body:
         **Before asking**: Please check the documentation first:
         - [docs/README.md](https://github.com/OMouta/PyLua/blob/master/docs/README.md) - Documentation index
         - [internalDocs/README.md](https://github.com/OMouta/PyLua/blob/master/internalDocs/README.md) - Internal docs overview
-        - [internalDocs/REWRITE_PLAN.md](https://github.com/OMouta/PyLua/blob/master/internalDocs/REWRITE_PLAN.md) - Current development status
+        - [internalDocs/ROADMAP.md](https://github.com/OMouta/PyLua/blob/master/internalDocs/ROADMAP.md) - Planned future work
         - [CONTRIBUTING.md](https://github.com/OMouta/PyLua/blob/master/CONTRIBUTING.md) - Development guidelines
         
         We're here to help! Please provide as much context as possible.
@@ -112,7 +112,7 @@ body:
       placeholder: |
         - OS: Windows 11 / macOS 14 / Ubuntu 22.04
         - Roblox Studio Version: 
-        - PyLua Version: v0.3 rewrite / v0.2 legacy
+  - PyLua Version: v0.3.x / v0.2 legacy
         - Luau Version (if applicable): 
       value: |
         - OS: 
diff --git a/.github/instructions/pylua0.3.instructions.md b/.github/instructions/pylua0.3.instructions.md
@@ -181,7 +181,7 @@ See `docs/INTEROP.md` for planned full two-way binding features.
 - **`docs/OBJECTS.md`**: Python object model implementation details
 - **`docs/BYTECODE.md`**: Instruction set reference
 - **`docs/examples/`**: Working code samples
-- **`internalDocs/REWRITE_PLAN.md`**: Implementation checklist and phase tracking
+- **`internalDocs/ROADMAP.md`**: Planned milestones and future work
 
 ## Quick Reference: Key Files
 
diff --git a/.vscode/extensions.json b/.vscode/extensions.json
@@ -1,7 +1,6 @@
 {
 	"recommendations": [
 		"johnnymorganz.luau-lsp",
-		"JohnnyMorganz.stylua",
 		"tamasfe.even-better-toml",
 		"github.copilot"
 	]
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,12 +1,12 @@
 # Contributing to PyLua
 
-Thank you for your interest in contributing to PyLua! This document provides guidelines and information for contributors to the PyLua v0.3 rewrite project.
+Thank you for your interest in contributing to PyLua! This document provides guidelines and information for contributors to the PyLua v0.3 project.
 
 ## Project Overview
 
-PyLua v0.3 is a complete rewrite of the Python interpreter for Luau/Roblox. We're building a production-quality Python 3.12-compliant interpreter following CPython's design principles with a Lupa-inspired API.
+PyLua v0.3 is a production-quality Python interpreter for Luau/Roblox. We follow CPython's design principles with a Lupa-inspired API.
 
-**Important**: We are currently in a major rewrite phase. Please read the [internalDocs/REWRITE_PLAN.md](./internalDocs/REWRITE_PLAN.md) to understand the current development phase and architecture goals.
+Please read the [internalDocs/ROADMAP.md](./internalDocs/ROADMAP.md) to understand planned milestones and longer-term goals.
 
 ## Getting Started
 
@@ -41,7 +41,7 @@ PyLua v0.3 is a complete rewrite of the Python interpreter for Luau/Roblox. We'r
 
 3. **Understand the Architecture**
    - Read [internalDocs/README.md](./internalDocs/README.md) for documentation overview
-   - Review [internalDocs/REWRITE_PLAN.md](./internalDocs/REWRITE_PLAN.md) for current phase
+   - Review [internalDocs/ROADMAP.md](./internalDocs/ROADMAP.md) for upcoming work
    - Study [internalDocs/LANGUAGE_IMPLEMENTATION.md](./internalDocs/LANGUAGE_IMPLEMENTATION.md) for technical background
 
 4. **Set Up Development Environment**
@@ -62,7 +62,7 @@ PyLua v0.3 is a complete rewrite of the Python interpreter for Luau/Roblox. We'r
 
 #### Feature Requests
 
-- Review the rewrite plan to ensure alignment with project goals
+- Review the roadmap to ensure alignment with project goals
 - Use the feature request template
 - Consider Python 3.12 compliance requirements
 - Discuss major features in issues before implementation
@@ -198,7 +198,7 @@ end
 
 ### What to Focus On
 
-- **Current phase priorities** from the rewrite plan
+- **Roadmap priorities** for upcoming work
 - **Python 3.12 compliance** and below
 - **Clean, maintainable code** with proper separation of concerns
 - **Comprehensive testing** for reliability
diff --git a/README.md b/README.md
@@ -1,57 +1,55 @@
-# PyLua - Embedded Python Interpreter for Luau
+# PyLua - Embedded Python for Luau
 
-> Notice: For v0.2 docs, see [docs/0.2/README.md](docs/0.2/README.md).
+> For v0.2 docs, see [docs/0.2/README.md](docs/0.2/README.md).
 
-PyLua lets you run Python inside Luau (e.g., Roblox). The v0.3 rewrite is a proper interpreter built in Luau with a CPython-inspired design.
+Run Python inside Luau (e.g., Roblox). PyLua 0.3 is a compact, CPython‑inspired interpreter you can embed in Luau projects.
 
-## What is it?
+## Highlights
 
-- A Python 3.12-and-below interpreter implemented in Luau
-- Runs on [Lute] and other Luau-compatible runtimes
-- Embeddable API for executing/evaluating Python and sharing values via `globals()`
+- Python 3.12 (and below) semantics where practical
+- Works with [Lute] and Luau runtimes (Roblox Studio, etc.)
+- Simple API: execute/eval and share values via `globals()`
+- CPython‑style pipeline (lexer → parser → AST → bytecode → VM)
 
-## Use cases
+## Quick start
 
-- Author gameplay logic in Python while running on Luau
-- Build modding hooks: expose Luau callbacks to Python scripts
-- Teach/prototype Python inside Roblox-like environments
-- Explore interpreter architecture (tokens → AST → bytecode → VM)
+Run an example from the repo root (requires Lute in PATH):
 
-## How it’s built
-
-Interpreter pipeline:
+```powershell
+lute examples/hello_world.luau
+```
 
-- Lexer → Parser → AST → Compiler → Bytecode → VM
+Embed and run a bit of Python:
 
-Key modules (see `src/PyLua/`):
+```lua
+local PyLua = require("./src/PyLua")
+local py = PyLua.new()
 
-- `lexer.luau`, `parser/` – Python-compliant tokenization and parsing
-- `compiler.luau` – compile AST to bytecode
-- `vm/` – stack-based virtual machine
-- `objects/` – Python object model
-- `builtins/` – core built-in functions and types
+py:execute([[x = 2 + 3]])
+print(py:getGlobal("x")) -- 5
 
-## Status
+local result = py:eval("sum([1, 2, 3])")
+print(result) -- 6
+```
 
-- Version: `0.3.0-dev3`
-- Target: Python 3.12 syntax and below (3.13+ out of scope)
-- Roadmap: `internalDocs/REWRITE_PLAN.md`
+## Docs and examples
 
-## Get started
+- Docs index: `docs/README.md`
+- Architecture overview: `docs/ARCHITECTURE.md`
+- Examples: `examples/`
 
-See docs and examples for usage and API details:
+## Status
 
-- Docs home: `docs/README.md`
-- Examples: `docs/examples/`
+- Version: `0.3.0`
+- Target: Python 3.12 and below (3.13+ out of scope)
+- Roadmap: `internalDocs/ROADMAP.md`
 
-You can also quickly try an example with Lute from the repo root:
+## Contributing
 
-```bash
-lute examples/hello_world.luau
-```
+Issues and PRs welcome. See `CONTRIBUTING.md` for guidelines.
 
 ## License
 
-MIT - see [`LICENSE`](./LICENSE).
+MIT — see [`LICENSE`](./LICENSE).
 
 [Lute]: https://github.com/luau-lang/lute
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
@@ -35,4 +35,4 @@ Python Source → Lexer → Parser → AST → Compiler → Bytecode → VM →
 
 ---
 
-See also: [REWRITE_PLAN.md](../internalDocs/REWRITE_PLAN.md) for detailed milestones and checklists.
+See also: [ROADMAP.md](../internalDocs/ROADMAP.md) for planned milestones and future work.
diff --git a/docs/LIMITATIONS.md b/docs/LIMITATIONS.md
@@ -1,7 +1,7 @@
-# Current Limitations (0.3.0-dev3)
+# Current Limitations (0.3.0)
 
 A practical subset is implemented; some features are deferred or partial:
 
 - Interop: `PyLua.registerClassBinding` now exposes richer Luau ↔ Python object mapping; automatic discovery for complex userdata/metatable hierarchies remains pending
 
-Track progress in [REWRITE_PLAN.md](../internalDocs/REWRITE_PLAN.md).
+See planned improvements in the [ROADMAP](../internalDocs/ROADMAP.md).
diff --git a/docs/README.md b/docs/README.md
@@ -1,6 +1,6 @@
-# PyLua Documentation (v0.3 dev)
+# PyLua Documentation (v0.3)
 
-Welcome to the living docs for the PyLua 0.3 rewrite. This version is a ground-up interpreter for running Python 3.12- on Luau. It’s in active development; see [internalDocs/REWRITE_PLAN.md](../internalDocs/REWRITE_PLAN.md) for the roadmap and supported features.
+Welcome to the PyLua 0.3 docs. This version is a ground-up interpreter for running Python 3.12- on Luau. For planned post-0.3 work, see the [Roadmap](../internalDocs/ROADMAP.md).
 
 If you’re just looking to try things, the examples below are the best starting point.
 
@@ -57,17 +57,17 @@ Useful methods:
 
 Deep dives and references:
 
-- [Architecture](docs/ARCHITECTURE.md)
-- [Lexer](docs/LEXER.md)
-- [Parser](docs/PARSER.md) & [AST](docs/AST.md)
-- [Compiler](docs/COMPILER.md)
-- [Bytecode](docs/BYTECODE.md)
-- [Virtual Machine](docs/VM.md)
-- [Object Model](`docs/OBJECTS.md)
-- [Built-ins](docs/BUILTINS.md)
-- [Interop](docs/INTEROP.md)
-- [Testing](docs/TESTING.md)
-- [Limitations](docs/LIMITATIONS.md)
+- [Architecture](./ARCHITECTURE.md)
+- [Lexer](./LEXER.md)
+- [Parser](./PARSER.md) & [AST](./AST.md)
+- [Compiler](./COMPILER.md)
+- [Bytecode](./BYTECODE.md)
+- [Virtual Machine](./VM.md)
+- [Object Model](./OBJECTS.md)
+- [Built-ins](./BUILTINS.md)
+- [Interop](./INTEROP.md)
+- [Testing](./TESTING.md)
+- [Limitations](./LIMITATIONS.md)
 
 ## Running tests
 
diff --git a/internalDocs/README.md b/internalDocs/README.md
@@ -4,21 +4,17 @@ This directory contains internal documentation for PyLua v0.3 development. These
 
 ## Documents Overview
 
-### [REWRITE_PLAN.md](./REWRITE_PLAN.md)
+### [ROADMAP.md](./ROADMAP.md)
 
-#### Complete development roadmap and architecture specification
+#### Post-0.3 roadmap and milestones
 
-This is the master planning document for PyLua v0.3. It outlines:
+This is the planning document for work after the 0.3 release. It outlines:
 
-- Current issues with v0.2 and motivation for the rewrite
-- Target architecture following CPython's design principles
-- Detailed implementation phases (Foundation → Parser → Object System → VM → Built-ins)
-- Python 3.12 compliance goals and version limitations
-- API design inspired by Lupa (inverse Python-in-Luau)
-- Testing strategy and success criteria
-- Future roadmap for v3.1+ features
+- Planned milestones and future features
+- High-level priorities for v3.1+ (classes/modules, decorators, context managers, async, etc.)
+- Performance and footprint goals
 
-**Start here** if you want to understand the overall project direction and implementation plan.
+**Start here** if you want to understand what's next.
 
 ### [LANGUAGE_IMPLEMENTATION.md](./LANGUAGE_IMPLEMENTATION.md)
 
@@ -39,14 +35,14 @@ This document provides background on how programming language interpreters work,
 
 ### For Contributors
 
-- **New contributors**: Start with `REWRITE_PLAN.md` to understand the project scope and current phase
+- **New contributors**: Start with `ROADMAP.md` to understand upcoming work and priorities
 - **Core developers**: Use both documents as reference for implementation decisions
 - **Language experts**: `LANGUAGE_IMPLEMENTATION.md` provides the theoretical foundation
 
 ### For Maintainers
 
 - Architecture decisions should align with the principles outlined in these documents
-- Use the phase breakdown in `REWRITE_PLAN.md` for milestone planning
+- Use the sections in `ROADMAP.md` for milestone planning
 - Reference the compliance goals when evaluating feature requests
 
 ## Key Design Principles
@@ -73,11 +69,10 @@ When contributing to PyLua v0.3:
 
 | Need to... | Reference |
 |------------|-----------|
-| Understand project scope and goals | `REWRITE_PLAN.md` - Overview & Design Principles |
+| See upcoming features and priorities | `ROADMAP.md` - Post-0.3 milestones |
 | Implement lexer/tokenizer | `LANGUAGE_IMPLEMENTATION.md` - Lexical Analysis |
 | Design AST nodes | `LANGUAGE_IMPLEMENTATION.md` - Parsing and AST |
 | Build the virtual machine | `LANGUAGE_IMPLEMENTATION.md` - CPython Execution Model |
-| Check implementation phases | `REWRITE_PLAN.md` - Implementation Phases |
 | Understand Python 3.12 features | `LANGUAGE_IMPLEMENTATION.md` - Python 3.12 Syntax Updates |
 
 ## External References
diff --git a/internalDocs/REWRITE_PLAN.md b/internalDocs/REWRITE_PLAN.md
diff --git a/internalDocs/ROADMAP.md b/internalDocs/ROADMAP.md
diff --git a/src/PyLua/init.luau b/src/PyLua/init.luau

Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"recommendations": [`
`3`	`3`	`"johnnymorganz.luau-lsp",`
`4`		`- "JohnnyMorganz.stylua",`
`5`	`4`	`"tamasfe.even-better-toml",`
`6`	`5`	`"github.copilot"`
`7`	`6`	`]`
Original file line number	Diff line number	Diff line change
`@@ -35,4 +35,4 @@ Python Source → Lexer → Parser → AST → Compiler → Bytecode → VM →`
`35`	`35`
`36`	`36`	`---`
`37`	`37`
`38`		`-See also: [REWRITE_PLAN.md](../internalDocs/REWRITE_PLAN.md) for detailed milestones and checklists.`
	`38`	`+See also: [ROADMAP.md](../internalDocs/ROADMAP.md) for planned milestones and future work.`