foreignthon-docs/docs/dev/releasing.md

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:

[project]
name = "foreignthon"
version = "0.5.4"   # bump this

ForeignThon follows Semantic Versioning:

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

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*:

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

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:

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:

# 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):

git push origin main

The deploy.yml workflow builds the MkDocs site and deploys it to 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