- Screenshots: a capture that exits with an error or writes nothing fails the job (the pictures it wrote are still published); the new "Screenshot diff" step compares them with tests/visual/baselines, fails beyond the tolerance, warns once for screens without a baseline and uploads the diff images. - installer (windows-latest): publishes App, Uploader and Setup (self-contained single file, no ReadyToRun), packs Titano 1.0.0 (with an extra legacy.txt), Titano 1.0.1 and the Uploader installer, and runs .github/scripts/installer-test.ps1: argument and not-installed exit codes, silent install into a folder with a space, Add/Remove Programs, shortcuts and the .titano file type, the installed programs drawing their screens, upgrade in place removing legacy.txt, uninstall removing itself, user data kept, the Uploader installer; the setup logs are printed whatever happens. The script now resolves its paths from the PowerShell location. - PostgreSQL 16/17: postgres-ci-setup.sh prepares the service container and the job exports the MD5, cleartext, trust, TLS and root-certificate variables. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
126 lines
8.3 KiB
Markdown
126 lines
8.3 KiB
Markdown
# Titano (development repository)
|
||
|
||
Time-lapse ecosystem: **Titano** (Windows desktop client), **Titano Server** (Linux/Docker and Windows) and
|
||
**Titano Uploader** (Windows), sharing one C#/.NET 10 engine with zero third-party packages. This repository is
|
||
private; users get releases, the Docker image and the Unraid template from the public releases repository.
|
||
|
||
- Specification: [`docs/BRIEF.md`](docs/BRIEF.md) · working rules: [`CLAUDE.md`](CLAUDE.md)
|
||
- Architecture and conventions: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) · decisions:
|
||
[`docs/DECISIONS.md`](docs/DECISIONS.md) · status: [`docs/STATUS.md`](docs/STATUS.md) · changes:
|
||
[`docs/CHANGELOG.md`](docs/CHANGELOG.md)
|
||
- Visual design: [`docs/ui/DESIGN.md`](docs/ui/DESIGN.md) and `docs/ui/mockups/`
|
||
|
||
## Build, test, run
|
||
|
||
Requirements: the .NET SDK pinned in `global.json`. Windows builds and runs everything; Linux builds everything
|
||
(the Windows projects for compile checking) and runs Core, Data, Protocol, Server and Tools.
|
||
|
||
```sh
|
||
dotnet build Titano.slnx -c Release
|
||
|
||
# Tests (one program per area; --filter text|category:name, --junit file, --verbose)
|
||
dotnet run --project tests/Titano.Core.Tests -c Release -- --junit out/core.xml
|
||
dotnet run --project tests/Titano.Data.Tests -c Release
|
||
dotnet run --project tests/Titano.Server.Tests -c Release
|
||
dotnet run --project tests/Titano.Tools.Tests -c Release
|
||
dotnet run --project tests/Titano.Core.Windows.Tests -c Release # Windows
|
||
dotnet run --project tests/Titano.App.Tests -c Release # Windows
|
||
|
||
# PostgreSQL integration tests (16 or 17); the MD5, cleartext, trust and TLS tests also read TITANO_TEST_PG_MD5,
|
||
# _CLEARTEXT, _TRUST, _TLS=1 and _ROOT_CERT (.github/scripts/postgres-ci-setup.sh prepares a server for them)
|
||
TITANO_TEST_PG="Host=127.0.0.1;Port=5432;Database=titano_test;Username=titano;Password=…;SslMode=disable" \
|
||
dotnet run --project tests/Titano.Data.Tests -c Release
|
||
|
||
# Performance gates (500,000-photo library, 100,000-frame rebuild; minutes)
|
||
TITANO_PERF=1 dotnet run --project tests/Titano.Data.Tests -c Release -- --filter category:perf --verbose
|
||
|
||
# Checks run by CI
|
||
dotnet run --project src/Titano.Tools -- package-guard
|
||
dotnet run --project src/Titano.Tools -- i18n check
|
||
dotnet run --project src/Titano.Tools -- xaml-lint
|
||
dotnet format whitespace Titano.slnx --verify-no-changes
|
||
dotnet run --project src/Titano.Tools -- screenshots diff out/screenshots # Windows, after --capture (tests/visual/baselines/README.md)
|
||
|
||
# CC0 RAW samples for the decoder tests (tests/fixtures/manifest.json explains how to fill in URLs)
|
||
dotnet run --project src/Titano.Tools -- fixtures
|
||
```
|
||
|
||
Run:
|
||
|
||
```sh
|
||
dotnet run --project src/Titano.Server # admin panel https://localhost:8443/admin
|
||
src/Titano.App/bin/Release/net10.0-windows/Titano.exe [--capture <folder>]
|
||
src/Titano.Uploader/bin/Release/net10.0-windows/Titano.Uploader.exe
|
||
docker compose -f deploy/docker/docker-compose.yml up -d
|
||
```
|
||
|
||
The server reads `/data/server.json` (`TITANO_DATA_PATH`) and `TITANO_*` environment variables;
|
||
`Titano.Server --help` lists them. On Linux it needs PostgreSQL; on Windows it defaults to SQLite.
|
||
|
||
## CI
|
||
|
||
| Workflow | When | What |
|
||
|---|---|---|
|
||
| `.github/workflows/ci.yml` | push to `main`, pull requests | Windows + Linux build (warnings are errors), all tests, package guard, i18n check, XAML lint, format check, YAML check of workflows and public issue forms, CC0 fixtures (a warning per missing sample), screenshots (`--capture`, also pushed to the `ci-screenshots` branch for same-repository PRs) and their pixel diff against `tests/visual/baselines`, Windows program artifacts, installer test (install, run, upgrade in place, uninstall), PostgreSQL 16/17 integration (SCRAM, MD5, cleartext, trust, TLS), Docker image smoke test |
|
||
| `.github/workflows/docker.yml` | nightly | `ghcr.io/<owner>/titano-server:nightly` (multi-arch) |
|
||
| `.github/workflows/perf.yml` | weekly, manual | Performance gates on SQLite and PostgreSQL 17; timings in the job summary |
|
||
| `.github/workflows/release.yml` | tag `v*`, manual re-publish | The release (below) |
|
||
|
||
## Release process
|
||
|
||
1. Make sure `main` is green and `docs/CHANGELOG.md` / `docs/STATUS.md` are up to date.
|
||
2. Tag and push: `git tag v0.2.0 && git push origin v0.2.0` (pre-releases: `v0.2.0-rc.1`; they are published as
|
||
GitHub pre-releases, get no `:latest` image and are ignored by the in-app update check).
|
||
3. `release.yml` then:
|
||
- validates the tag, builds with `TitanoVersion` from the tag and runs every test on Windows;
|
||
- publishes self-contained single-file programs, signs them when signing secrets exist, packs
|
||
`Titano-Setup-<v>.exe` and `Titano-Uploader-Setup-<v>.exe` (`Titano.Tools pack-installer`), signs the setups,
|
||
zips `Titano-Server-win-x64-<v>.zip` and `Titano-win-x64-portable-<v>.zip`;
|
||
- writes release notes from the Conventional Commits since the previous tag (`Titano.Tools changelog`); a stable
|
||
tag starts from the previous stable tag, so its notes include what its release candidates brought;
|
||
- once the Windows tests passed, builds and pushes `ghcr.io/<owner>/titano-server:<v>` for amd64 and arm64;
|
||
- computes `SHA256SUMS`, checks the public issue forms, creates (or updates) the GitHub release in the public
|
||
repository, then moves the image's `:latest` tag and updates the public repository content (README, EULA,
|
||
`i18n/`, `SHA256SUMS`). `:latest`, *Latest* and the content follow the newest stable release: a pre-release, or
|
||
an older tag published again, only gets its release and its `:<v>` image. Until the first stable release exists,
|
||
every tag updates the content.
|
||
4. To publish an existing tag again (for example after adding a secret), run *Release* manually with the tag.
|
||
|
||
### Secrets and variables
|
||
|
||
| Name | Kind | Purpose |
|
||
|---|---|---|
|
||
| `RELEASES_TOKEN` | secret | Fine-grained PAT with *Contents: read and write* on the public releases repository. Without it the release is created in this (private) repository, which clients cannot see. |
|
||
| `RELEASES_REPO` | variable (optional) | `owner/name` of the public repository; default `<owner>/titano-releases`. `release.yml` passes it to every build as the `TitanoReleasesRepo` MSBuild property, so the update check, licence and issue links of the binaries read the repository the release goes to (local builds default to `alby96/titano-releases`). |
|
||
| `SIGN_PFX_BASE64` | secret (optional) | Base64 of the Authenticode code-signing certificate (`.pfx`). Without it builds are unsigned. |
|
||
| `SIGN_PASSWORD` | secret (optional) | Password of that `.pfx`. |
|
||
|
||
`GITHUB_TOKEN` pushes the image to GHCR and moves its `:latest` tag; no other secret is used.
|
||
|
||
### Bootstrapping the public releases repository
|
||
|
||
1. Create a **public** repository named `titano-releases` under the same owner (or set `RELEASES_REPO`), with a
|
||
README so it has a default branch. Enable *Issues* and *Private vulnerability reporting* (Settings › Security).
|
||
2. Create the fine-grained PAT (repository access: only that repository; permissions: Contents read/write) and store
|
||
it as the `RELEASES_TOKEN` secret of this repository.
|
||
3. Push a pre-release tag (`v0.1.0-rc.1`). The release job copies `deploy/releases-repo/` (README, EULA draft,
|
||
SECURITY policy, issue forms), the Unraid template and its icon, the compose file and `.env.example`, the dark
|
||
screenshots, `i18n/` and the latest `SHA256SUMS` into the public repository after creating the release with the
|
||
installers, rewriting links to its name and default branch.
|
||
4. After the first image push, open the `titano-server` package on GHCR › *Package settings* and set its
|
||
visibility to **Public** (GitHub offers no API for this; the release summary reminds you).
|
||
5. Have the EULA draft (`deploy/releases-repo/EULA.md`) reviewed before the first stable release.
|
||
6. In Unraid, add `https://github.com/<owner>/titano-releases` under Docker › Template repositories to validate the
|
||
template.
|
||
|
||
## Repository layout
|
||
|
||
```
|
||
src/ Titano.Core, Core.Windows, Data, Protocol, Server, Ui, App, Uploader, Setup, Tools
|
||
tests/ Titano.Testing and one test program per area; fixtures/ (manifest of CC0 samples)
|
||
i18n/ <culture>/<Area>.resx string catalogs, GLOSSARY.md
|
||
deploy/ docker/ (Dockerfile, compose), unraid/ (template), releases-repo/ (public repository content)
|
||
branding/ SVG masters of the icons
|
||
docs/ BRIEF, ARCHITECTURE, DECISIONS, STATUS, CHANGELOG, ui/
|
||
```
|