# Updates

> How ZeroDirs versions its releases, what an update touches in a copy you have already customised, and where the changelog lives.

You are reading one page of the ZeroDirs documentation. ZeroDirs is a paid Astro + Cloudflare Workers starter for directory sites: every page is rendered to static HTML at build time, the site ships no client JavaScript outside `/search/`, and one file — `site.config.ts` — carries roughly 80% of the customisation.

Two things to hold on to before you act on anything below:

- `site.config.ts` is validated by a zod schema with ten cross-field rules. After any edit to it, run `pnpm check:config`; every problem is reported as `site.config.ts › <path>: <message>` and the whole file is checked at once.
- The repository ships its own `AGENTS.md` with twenty hard rules, and a machine-checked test suite behind them. If you are working inside a ZeroDirs project, read that file first — it overrides anything general you infer from this page.

Source: https://zerodirs.com/docs/about/updates/

---

You own the source, so an update is something you pull rather than something that happens to you.
This page is about what that costs.

## Versioning

The changelog lives in `CHANGELOG.md` inside the starter and follows
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/). The version is also in `package.json`,
which is where to read it from when you file a support request.

Semantic versioning, read as it applies to a codebase you own rather than to a library you
install:

| | Means |
| --- | --- |
| **Major** | a change that will not merge cleanly into a customised copy, or that changes the shape of `site.config.ts` |
| **Minor** | new features and new config fields, with defaults that keep an existing site building |
| **Patch** | fixes and documentation |

A minor release adding a config field will not break your build, because every optional block in
`site.config.ts` has a default and a fresh clone parses with every optional block missing. That
property is what makes updates cheap.

## What an update touches, and what it never does

Three things are yours, and no release edits them:

- `site.config.ts`
- `src/content/`
- `public/`

Everything else — templates, library modules, integrations, tests — is ours to change, and that is
where an update lands. If you have edited a template, that is where you will resolve a conflict;
the changelog names structural changes explicitly so you know before you pull.

## Applying one

The starter is a normal git repository, so an update is a normal pull. Your access to
`zerodirs/zerodirs` is read-only; commit your own work in your own repository and pull ours into it.

1. **Read the entry first.** `CHANGELOG.md` names every structural change under **Changed** and
   **Removed** — those are the only places a merge conflict can come from.

2. **Pull.** If your copy still has the starter as `origin`:

   ```sh
   git pull origin main
   ```

   If you pushed your copy to a repository of your own, add the starter once as a second remote
   and merge from it:

   ```sh
   git remote add upstream git@github.com:zerodirs/zerodirs.git   # once
   git fetch upstream
   git merge upstream/main
   ```

   A conflict can only appear in a file you edited that the release also edited. `site.config.ts`,
   `src/content/` and `public/` are never touched by a release, so a conflict there means the
   merge is wrong, not the release.

3. **Install and migrate.**

   ```sh
   pnpm install
   pnpm db:migrate:local         # only when the entry says the release ships a migration
   ```

   Migrations are expand-only — they add tables, columns and indexes — so an older Worker keeps
   working against a newer database, and `pnpm db:migrate:remote` can run before the deploy.

4. **Verify, then deploy.**

   ```sh
   pnpm check
   pnpm test
   pnpm build
   ```

   The build is the one that matters: only a full build exercises the route table, the file
   budget, the sitemap and the orphan check together, and those are what a structural change
   moves. Then push to `main`, or `pnpm deploy` — see [Deploy on git push](https://zerodirs.com/docs/deploy/git-push/).

## Support

Quote the version from `CHANGELOG.md` and paste the **full output** of the failing command,
including the lines above the error. Most build failures in this project name a field path or a
file, and that line is usually the whole diagnosis.