# Upgrading Quaeriva

Upgrades replace files and then bring the database forward. They never require you to re-import a database, and they never destroy existing content.

---

## 1. Back up first

Always, and before anything else. See `docs/BACKUP.md`. At minimum:

- the database (a full dump),
- `config/database.local.php` — your credentials, which are **not** in the release archive,
- `.env` if you created one,
- `public/themes/` if you added a theme of your own.

---

## 2. Replace the files

1. Download the new release archive.
2. Upload its contents over your installation, overwriting.
3. **Do not overwrite or delete** `config/database.local.php`. The archive does not contain it, so a straightforward upload leaves it alone — but verify it is still there afterwards.
4. Your uploaded themes under `public/themes/` are untouched by a release that does not ship a theme of that name.

---

## 3. Bring the database forward

Open the admin panel. If the schema is behind, it shows a **Upgrade database** action; use it. That runs exactly the same migrations the command line would, so no shell access is needed.

With shell access you can instead run:

```
php bin/migrate.php
php bin/doctor.php
```

`doctor.php` should end with `Pending migrations: none` and `Schema integrity: ok`.

---

## 4. Rules that keep upgrades safe

- **Migrations are forward-only.** Never edit a migration that has already run — its record is in `schema_migrations` and changing the file will not re-run it.
- **Never re-import a demo database over a live one.** Demo data is for evaluation only.
- **A partial migration can be re-run.** Migrations are written to be safe on a second attempt, so if an upgrade is interrupted, run it again rather than restoring from backup.
- If an upgrade fails and the admin panel becomes unreachable, restore the database backup and the previous files together — not one without the other.

---

## 5. After upgrading

1. Open the public site and one question page.
2. Open `/admin` and check the System page.
3. If the release notes mention new settings, review them — new features generally ship disabled.
4. Re-check the file protections from `docs/INSTALL.md` §5 if you are running with the document root at the project root; an upload can overwrite `.htaccess`.

---

## 6. Version-specific notes

Read `CHANGELOG.md` for the versions between yours and the new one. Anything that needs a decision from you — a behaviour change, a new default, a setting that moved — is recorded there under the release that introduced it.

### 0.8.1

- No database migration is required for the site identity, taxonomy presentation, or sitemap-cap changes in this batch.
- Review the configured site name after replacing the files; it is now used in site-facing email subjects, notification text, profile copy, and mail sender-name fallbacks.

### 0.8.2

- Run `php bin/migrate.php` to apply migration `034_seed_primary_navigation_menu_items.sql`, which adds the missing `/d` primary-menu item without changing existing labels or URLs. Breadcrumbs are now shared across public routes, and existing managed primary-menu rows can be reordered from Administration without re-entering their content.

---

Back up files and database. Upload the new release over application files without replacing `.env`, `config/*.local.php`, or runtime storage. Run `php bin/migrate.php`, then `php bin/doctor.php`. Never skip pending migrations. Test the configured admin path such as `/w-admin`, not a hard-coded `/admin` URL.
