66 lines
2.0 KiB
Markdown
66 lines
2.0 KiB
Markdown
# Contributing
|
|
|
|
## Project structure
|
|
```
|
|
foreignthon/
|
|
├── packages/
|
|
│ ├── foreignthon/ # core engine + fpy CLI
|
|
│ │ ├── src/foreignthon/
|
|
│ │ │ ├── cli.py # fpy commands
|
|
│ │ │ ├── transpiler.py # tokenizer-based transpiler + @@ pre-pass
|
|
│ │ │ ├── pack.py # language pack loader + entry point discovery
|
|
│ │ │ └── errors.py # bilingual error hook
|
|
│ │ └── tests/
|
|
│ └── langs/
|
|
│ ├── es/ # foreignthon-es (Spanish)
|
|
│ └── ta/ # foreignthon-ta (Tamil)
|
|
| |__ zh/ # foreignthon-zh (Chinese)
|
|
├── docs/
|
|
└── .gitea/workflows/
|
|
├── ci.yml # runs tests + lint on every push
|
|
└── publish.yml # builds + publishes to PyPI on git tag
|
|
```
|
|
|
|
## How the transpiler works
|
|
|
|
1. **Pre-pass** — scans for `@@keyword` postfix syntax and rewrites lines to prefix form
|
|
2. **Tokenizer** — uses Python's `tokenize` module to swap `NAME` tokens. Strings and comments are never touched.
|
|
3. **Runner** — compiles with the original filename so tracebacks point to your `.es.py` file, not a temp file
|
|
|
|
## Setup
|
|
|
|
```bash
|
|
python -m venv .venv && source .venv/bin/activate
|
|
pip install -e "packages/foreignthon[dev]"
|
|
pip install -e packages/langs/es
|
|
pip install -e packages/langs/ta
|
|
pip install -e packages/langs/zh
|
|
```
|
|
|
|
## Running tests
|
|
|
|
```bash
|
|
pytest packages/foreignthon/tests/ -v
|
|
```
|
|
|
|
## Linting
|
|
|
|
```bash
|
|
ruff check packages/foreignthon/src
|
|
```
|
|
|
|
## Adding a language pack
|
|
|
|
See [language-packs.md](language-packs.md) for the full guide.
|
|
|
|
## CI
|
|
|
|
Every push to `main` runs tests and lint (non-blocking). Releases are triggered by pushing a git tag — see [releasing.md](releasing.md).
|
|
|
|
## Submitting changes
|
|
|
|
1. Fork the repo
|
|
2. Create a branch
|
|
3. Make your changes + add tests if relevant
|
|
4. Open a pull request against `main`
|