# 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