added architeceutre and releasing guides

2026-05-21 14:39:13 +00:00
parent e763c9fbc6
commit 943791cb07
2 changed files with 294 additions and 0 deletions
--- a/docs/dev/releasing.md
+++ b/docs/dev/releasing.md
@@ -1 +1,136 @@
 # Releasing
+
+This page covers how to release `foreignthon-core` and how language pack maintainers should respond to a new core release.
+
+---
+
+## Core release (`foreignthon`)
+
+### 1. Update the version
+
+Version is set in `pyproject.toml`:
+
+```toml
+[project]
+name = "foreignthon"
+version = "0.5.4"   # bump this
+```
+
+ForeignThon follows [Semantic Versioning](https://semver.org/):
+
+| Change | Version bump |
+|---|---|
+| Bug fix, no API change | Patch (`0.5.3` → `0.5.4`) |
+| New feature, backward compatible | Minor (`0.5.x` → `0.6.0`) |
+| Breaking change (removes a key, changes CLI contract) | Major (`0.x.y` → `1.0.0`) |
+
+### 2. Update `template.json` if needed
+
+If the release adds new keywords, builtins, or sections, update `template.json` to include them. This is the canonical list all language packs are expected to cover. Document what changed in your commit message and PR so pack maintainers know what to add.
+
+### 3. Run CI locally
+
+```bash
+pytest
+ruff check src/
+ruff format --check src/
+```
+
+All must pass.
+
+### 4. Tag and push
+
+The Gitea CI publishes to PyPI on any tag matching `v*`:
+
+```bash
+git tag v0.5.4
+git push origin v0.5.4
+```
+
+The `publish.yml` workflow builds the wheel and uploads it using the `PYPI_TOKEN` secret configured in Gitea.
+
+### 5. Verify
+
+```bash
+pip install --upgrade foreignthon
+fpy --version
+```
+
+---
+
+## Language pack release (`foreignthon-xx`)
+
+Each language pack is independently versioned and released.
+
+### Responding to a core release
+
+When `foreignthon-core` adds new entries to `template.json`:
+
+1. Add the new keys to your `xx.json` with translations.
+2. Run `fpy pack src/foreignthon_xx/xx.json` to validate.
+3. Run `pytest tests/` to confirm all checks pass.
+4. Bump your pack's version in `pyproject.toml`.
+5. Tag and push — the `publish.yml` workflow handles PyPI upload.
+
+Update the `foreignthon` dependency lower bound in `pyproject.toml` if your pack requires the new core version:
+
+```toml
+dependencies = ["foreignthon>=0.5.4"]
+```
+
+### Releasing independently
+
+You can release a pack at any time — to fix a translation, add missing entries, or extend coverage. The process is the same:
+
+```bash
+# bump version in pyproject.toml
+git add pyproject.toml src/foreignthon_xx/xx.json
+git commit -m "v0.3.3: fix translation for 'return'"
+git tag v0.3.3
+git push origin v0.3.3
+```
+
+---
+
+## Docs release (`foreignthon-docs`)
+
+The docs site rebuilds automatically when a language pack fires its `trigger-docs.yml` workflow after a successful publish. No manual step is needed for routine pack releases.
+
+To manually trigger a docs rebuild (e.g. after editing `foreignthon-docs` directly):
+
+```bash
+git push origin main
+```
+
+The `deploy.yml` workflow builds the MkDocs site and deploys it to [foreignthon.keshavanand.net](https://foreignthon.keshavanand.net).
+
+---
+
+## Gitea secrets
+
+| Secret | Used by |
+|---|---|
+| `PYPI_TOKEN` | `publish.yml` in core and all packs |
+| `DOCS_WEBHOOK` | `trigger-docs.yml` in language packs |
+
+Secrets are set per-repository in **Gitea → Settings → Actions → Secrets**.
+
+---
+
+## Checklist
+
+### Core
+- [ ] Version bumped in `pyproject.toml`
+- [ ] `template.json` updated if new keys added
+- [ ] `pytest` passes
+- [ ] `ruff check` passes
+- [ ] Tagged `v*` and pushed
+- [ ] PyPI upload confirmed
+
+### Language pack
+- [ ] New `template.json` entries translated in `xx.json`
+- [ ] `fpy pack xx.json` passes
+- [ ] `pytest tests/` passes
+- [ ] Version bumped
+- [ ] `foreignthon` dependency lower bound updated if required
+- [ ] Tagged and pushed