2026-03-13 13:00:19 +01:00
|
|
|
# Contributing to Immich Folio
|
|
|
|
|
|
|
|
|
|
Thanks for your interest in contributing! 🎉
|
|
|
|
|
|
|
|
|
|
## Ways to contribute
|
|
|
|
|
|
|
|
|
|
- **Bug reports** — [Open a bug report issue](https://github.com/ralksta/immich-folio/issues/new?template=bug_report.md)
|
|
|
|
|
- **Feature requests** — [Open a feature request](https://github.com/ralksta/immich-folio/issues/new?template=feature_request.md)
|
|
|
|
|
- **Pull requests** — see below
|
|
|
|
|
- **Discussions** — [Ask questions or share ideas](https://github.com/ralksta/immich-folio/discussions)
|
|
|
|
|
|
docs(contributing): tell contributors to target dev (#412)
* fix(screenshots): sharp-Typen fuer 0.34 und 0.35 gleichzeitig (#410)
sharp 0.35 ist von `export =` auf ESM umgestellt: der Modul-Namespace
ist nicht mehr aufrufbar, die Factory sitzt unter .default. Der
Type-Check brach damit in scripts/screenshots.ts weg, sobald der
Next-Bump (#402) sharp von 0.34.5 auf 0.35.3 mitzieht -- sharp ist hier
keine deklarierte Dependency, sondern kommt ueber Next mit.
Die Form wird jetzt aus dem installierten Paket abgeleitet statt
festgeschrieben, zur Laufzeit wie im Typ. Geprueft mit beiden
Versionen: tsc laeuft mit 0.34.5 und mit 0.35.3 fehlerfrei durch.
Co-authored-by: ralksta <ralksta@users.noreply.github.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
* chore(deps): bump the nextjs group across 1 directory with 2 updates (#402)
Bumps the nextjs group with 2 updates in the / directory: [next](https://github.com/vercel/next.js) and [eslint-config-next](https://github.com/vercel/next.js/tree/HEAD/packages/eslint-config-next).
Updates `next` from 16.2.12 to 16.3.0
- [Release notes](https://github.com/vercel/next.js/releases)
- [Commits](https://github.com/vercel/next.js/compare/v16.2.12...v16.3.0)
Updates `eslint-config-next` from 16.2.12 to 16.3.0
- [Release notes](https://github.com/vercel/next.js/releases)
- [Commits](https://github.com/vercel/next.js/commits/v16.3.0/packages/eslint-config-next)
---
updated-dependencies:
- dependency-name: eslint-config-next
dependency-version: 16.3.0
dependency-type: direct:development
update-type: version-update:semver-minor
dependency-group: nextjs
- dependency-name: next
dependency-version: 16.3.0
dependency-type: direct:production
update-type: version-update:semver-minor
dependency-group: nextjs
...
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
* chore(deps-dev): bump prettier from 3.8.3 to 3.9.6 (#405)
Bumps [prettier](https://github.com/prettier/prettier) from 3.8.3 to 3.9.6.
- [Release notes](https://github.com/prettier/prettier/releases)
- [Changelog](https://github.com/prettier/prettier/blob/main/CHANGELOG.md)
- [Commits](https://github.com/prettier/prettier/compare/3.8.3...3.9.6)
---
updated-dependencies:
- dependency-name: prettier
dependency-version: 3.9.6
dependency-type: direct:development
update-type: version-update:semver-minor
...
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
* docs(contributing): PRs gehen gegen dev
Nirgends stand, welcher Branch das Ziel ist -- die offene PR #398 zeigt
folgerichtig auf main. main bewegt sich aber nur ueber Releases: es wird
von dev fast-forwarded, getaggt, und der Tag stoesst den Image-Publish
an. Eine PR dagegen legt unveroeffentlichten Code in genau den Branch,
der dem publizierten Image entsprechen soll.
Steht jetzt als eigener Abschnitt in CONTRIBUTING.md, im Setup-Snippet
und in beiden Checklisten. Mit Hinweis, dass ein falsches Ziel ueber
"Edit" an der PR umgestellt werden kann, statt die Arbeit neu zu machen.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---------
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: ralksta <ralksta@users.noreply.github.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
2026-08-10 10:41:01 +02:00
|
|
|
## Branches
|
|
|
|
|
|
|
|
|
|
**Open pull requests against `dev`, not `main`.**
|
|
|
|
|
|
|
|
|
|
`dev` is where everything is integrated. `main` only ever moves through a
|
|
|
|
|
release: it is fast-forwarded from `dev`, tagged, and the tag triggers the
|
|
|
|
|
Docker image publish. A PR against `main` would put unreleased code into the
|
|
|
|
|
branch that is supposed to match the published image — so please branch off
|
|
|
|
|
`dev` and target it.
|
|
|
|
|
|
|
|
|
|
CI runs on pull requests to either branch, so a PR against `dev` is checked
|
|
|
|
|
exactly the same way.
|
|
|
|
|
|
|
|
|
|
If you opened a PR against `main` by accident, no need to redo the work — you
|
|
|
|
|
can change the target branch on the PR page under **Edit** next to the title.
|
|
|
|
|
|
2026-03-13 13:00:19 +01:00
|
|
|
## Development setup
|
|
|
|
|
|
|
|
|
|
```bash
|
docs(contributing): tell contributors to target dev (#412)
* fix(screenshots): sharp-Typen fuer 0.34 und 0.35 gleichzeitig (#410)
sharp 0.35 ist von `export =` auf ESM umgestellt: der Modul-Namespace
ist nicht mehr aufrufbar, die Factory sitzt unter .default. Der
Type-Check brach damit in scripts/screenshots.ts weg, sobald der
Next-Bump (#402) sharp von 0.34.5 auf 0.35.3 mitzieht -- sharp ist hier
keine deklarierte Dependency, sondern kommt ueber Next mit.
Die Form wird jetzt aus dem installierten Paket abgeleitet statt
festgeschrieben, zur Laufzeit wie im Typ. Geprueft mit beiden
Versionen: tsc laeuft mit 0.34.5 und mit 0.35.3 fehlerfrei durch.
Co-authored-by: ralksta <ralksta@users.noreply.github.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
* chore(deps): bump the nextjs group across 1 directory with 2 updates (#402)
Bumps the nextjs group with 2 updates in the / directory: [next](https://github.com/vercel/next.js) and [eslint-config-next](https://github.com/vercel/next.js/tree/HEAD/packages/eslint-config-next).
Updates `next` from 16.2.12 to 16.3.0
- [Release notes](https://github.com/vercel/next.js/releases)
- [Commits](https://github.com/vercel/next.js/compare/v16.2.12...v16.3.0)
Updates `eslint-config-next` from 16.2.12 to 16.3.0
- [Release notes](https://github.com/vercel/next.js/releases)
- [Commits](https://github.com/vercel/next.js/commits/v16.3.0/packages/eslint-config-next)
---
updated-dependencies:
- dependency-name: eslint-config-next
dependency-version: 16.3.0
dependency-type: direct:development
update-type: version-update:semver-minor
dependency-group: nextjs
- dependency-name: next
dependency-version: 16.3.0
dependency-type: direct:production
update-type: version-update:semver-minor
dependency-group: nextjs
...
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
* chore(deps-dev): bump prettier from 3.8.3 to 3.9.6 (#405)
Bumps [prettier](https://github.com/prettier/prettier) from 3.8.3 to 3.9.6.
- [Release notes](https://github.com/prettier/prettier/releases)
- [Changelog](https://github.com/prettier/prettier/blob/main/CHANGELOG.md)
- [Commits](https://github.com/prettier/prettier/compare/3.8.3...3.9.6)
---
updated-dependencies:
- dependency-name: prettier
dependency-version: 3.9.6
dependency-type: direct:development
update-type: version-update:semver-minor
...
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
* docs(contributing): PRs gehen gegen dev
Nirgends stand, welcher Branch das Ziel ist -- die offene PR #398 zeigt
folgerichtig auf main. main bewegt sich aber nur ueber Releases: es wird
von dev fast-forwarded, getaggt, und der Tag stoesst den Image-Publish
an. Eine PR dagegen legt unveroeffentlichten Code in genau den Branch,
der dem publizierten Image entsprechen soll.
Steht jetzt als eigener Abschnitt in CONTRIBUTING.md, im Setup-Snippet
und in beiden Checklisten. Mit Hinweis, dass ein falsches Ziel ueber
"Edit" an der PR umgestellt werden kann, statt die Arbeit neu zu machen.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---------
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: ralksta <ralksta@users.noreply.github.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
2026-08-10 10:41:01 +02:00
|
|
|
# 1. Clone and switch to the integration branch
|
2026-03-13 13:00:19 +01:00
|
|
|
git clone https://github.com/ralksta/immich-folio.git
|
|
|
|
|
cd immich-folio
|
docs(contributing): tell contributors to target dev (#412)
* fix(screenshots): sharp-Typen fuer 0.34 und 0.35 gleichzeitig (#410)
sharp 0.35 ist von `export =` auf ESM umgestellt: der Modul-Namespace
ist nicht mehr aufrufbar, die Factory sitzt unter .default. Der
Type-Check brach damit in scripts/screenshots.ts weg, sobald der
Next-Bump (#402) sharp von 0.34.5 auf 0.35.3 mitzieht -- sharp ist hier
keine deklarierte Dependency, sondern kommt ueber Next mit.
Die Form wird jetzt aus dem installierten Paket abgeleitet statt
festgeschrieben, zur Laufzeit wie im Typ. Geprueft mit beiden
Versionen: tsc laeuft mit 0.34.5 und mit 0.35.3 fehlerfrei durch.
Co-authored-by: ralksta <ralksta@users.noreply.github.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
* chore(deps): bump the nextjs group across 1 directory with 2 updates (#402)
Bumps the nextjs group with 2 updates in the / directory: [next](https://github.com/vercel/next.js) and [eslint-config-next](https://github.com/vercel/next.js/tree/HEAD/packages/eslint-config-next).
Updates `next` from 16.2.12 to 16.3.0
- [Release notes](https://github.com/vercel/next.js/releases)
- [Commits](https://github.com/vercel/next.js/compare/v16.2.12...v16.3.0)
Updates `eslint-config-next` from 16.2.12 to 16.3.0
- [Release notes](https://github.com/vercel/next.js/releases)
- [Commits](https://github.com/vercel/next.js/commits/v16.3.0/packages/eslint-config-next)
---
updated-dependencies:
- dependency-name: eslint-config-next
dependency-version: 16.3.0
dependency-type: direct:development
update-type: version-update:semver-minor
dependency-group: nextjs
- dependency-name: next
dependency-version: 16.3.0
dependency-type: direct:production
update-type: version-update:semver-minor
dependency-group: nextjs
...
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
* chore(deps-dev): bump prettier from 3.8.3 to 3.9.6 (#405)
Bumps [prettier](https://github.com/prettier/prettier) from 3.8.3 to 3.9.6.
- [Release notes](https://github.com/prettier/prettier/releases)
- [Changelog](https://github.com/prettier/prettier/blob/main/CHANGELOG.md)
- [Commits](https://github.com/prettier/prettier/compare/3.8.3...3.9.6)
---
updated-dependencies:
- dependency-name: prettier
dependency-version: 3.9.6
dependency-type: direct:development
update-type: version-update:semver-minor
...
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
* docs(contributing): PRs gehen gegen dev
Nirgends stand, welcher Branch das Ziel ist -- die offene PR #398 zeigt
folgerichtig auf main. main bewegt sich aber nur ueber Releases: es wird
von dev fast-forwarded, getaggt, und der Tag stoesst den Image-Publish
an. Eine PR dagegen legt unveroeffentlichten Code in genau den Branch,
der dem publizierten Image entsprechen soll.
Steht jetzt als eigener Abschnitt in CONTRIBUTING.md, im Setup-Snippet
und in beiden Checklisten. Mit Hinweis, dass ein falsches Ziel ueber
"Edit" an der PR umgestellt werden kann, statt die Arbeit neu zu machen.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---------
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: ralksta <ralksta@users.noreply.github.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
2026-08-10 10:41:01 +02:00
|
|
|
git checkout dev
|
2026-03-13 13:00:19 +01:00
|
|
|
|
|
|
|
|
# 2. Install
|
|
|
|
|
npm install
|
|
|
|
|
|
|
|
|
|
# 3. Configure
|
2026-05-31 10:13:53 +02:00
|
|
|
cp .env.local.example .env.local
|
|
|
|
|
cp content/gallery.yaml.example content/gallery.yaml
|
|
|
|
|
# Edit .env.local or set IMMICH_API_URL + IMMICH_API_KEY
|
2026-03-13 13:00:19 +01:00
|
|
|
|
|
|
|
|
# 4. Run
|
|
|
|
|
npm run dev # http://localhost:3000
|
|
|
|
|
npm run build # production build check
|
2026-08-30 15:11:25 +02:00
|
|
|
npm run doctor # check the configuration if something looks wrong
|
2026-03-13 13:00:19 +01:00
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Before submitting a PR
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
npx tsc --noEmit # must be 0 errors
|
|
|
|
|
npx vitest run # all tests must pass
|
|
|
|
|
npm run build # build must succeed
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Code style
|
|
|
|
|
|
|
|
|
|
- **TypeScript** — strict mode, no `any` without justification
|
|
|
|
|
- **Components** — Server Components by default; use `'use client'` only when necessary
|
|
|
|
|
- **CSS** — vanilla CSS variables, no Tailwind, no CSS-in-JS
|
|
|
|
|
- **Naming** — descriptive names, no abbreviations in public APIs
|
|
|
|
|
|
|
|
|
|
## Commit messages
|
|
|
|
|
|
|
|
|
|
Use [Conventional Commits](https://www.conventionalcommits.org/):
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
feat: add new hero style
|
|
|
|
|
fix: correct image aspect ratio on mobile
|
|
|
|
|
security: escape HTML in map popups
|
|
|
|
|
docs: update theming guide
|
|
|
|
|
chore: bump next to 15.x
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Pull Request checklist
|
|
|
|
|
|
docs(contributing): tell contributors to target dev (#412)
* fix(screenshots): sharp-Typen fuer 0.34 und 0.35 gleichzeitig (#410)
sharp 0.35 ist von `export =` auf ESM umgestellt: der Modul-Namespace
ist nicht mehr aufrufbar, die Factory sitzt unter .default. Der
Type-Check brach damit in scripts/screenshots.ts weg, sobald der
Next-Bump (#402) sharp von 0.34.5 auf 0.35.3 mitzieht -- sharp ist hier
keine deklarierte Dependency, sondern kommt ueber Next mit.
Die Form wird jetzt aus dem installierten Paket abgeleitet statt
festgeschrieben, zur Laufzeit wie im Typ. Geprueft mit beiden
Versionen: tsc laeuft mit 0.34.5 und mit 0.35.3 fehlerfrei durch.
Co-authored-by: ralksta <ralksta@users.noreply.github.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
* chore(deps): bump the nextjs group across 1 directory with 2 updates (#402)
Bumps the nextjs group with 2 updates in the / directory: [next](https://github.com/vercel/next.js) and [eslint-config-next](https://github.com/vercel/next.js/tree/HEAD/packages/eslint-config-next).
Updates `next` from 16.2.12 to 16.3.0
- [Release notes](https://github.com/vercel/next.js/releases)
- [Commits](https://github.com/vercel/next.js/compare/v16.2.12...v16.3.0)
Updates `eslint-config-next` from 16.2.12 to 16.3.0
- [Release notes](https://github.com/vercel/next.js/releases)
- [Commits](https://github.com/vercel/next.js/commits/v16.3.0/packages/eslint-config-next)
---
updated-dependencies:
- dependency-name: eslint-config-next
dependency-version: 16.3.0
dependency-type: direct:development
update-type: version-update:semver-minor
dependency-group: nextjs
- dependency-name: next
dependency-version: 16.3.0
dependency-type: direct:production
update-type: version-update:semver-minor
dependency-group: nextjs
...
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
* chore(deps-dev): bump prettier from 3.8.3 to 3.9.6 (#405)
Bumps [prettier](https://github.com/prettier/prettier) from 3.8.3 to 3.9.6.
- [Release notes](https://github.com/prettier/prettier/releases)
- [Changelog](https://github.com/prettier/prettier/blob/main/CHANGELOG.md)
- [Commits](https://github.com/prettier/prettier/compare/3.8.3...3.9.6)
---
updated-dependencies:
- dependency-name: prettier
dependency-version: 3.9.6
dependency-type: direct:development
update-type: version-update:semver-minor
...
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
* docs(contributing): PRs gehen gegen dev
Nirgends stand, welcher Branch das Ziel ist -- die offene PR #398 zeigt
folgerichtig auf main. main bewegt sich aber nur ueber Releases: es wird
von dev fast-forwarded, getaggt, und der Tag stoesst den Image-Publish
an. Eine PR dagegen legt unveroeffentlichten Code in genau den Branch,
der dem publizierten Image entsprechen soll.
Steht jetzt als eigener Abschnitt in CONTRIBUTING.md, im Setup-Snippet
und in beiden Checklisten. Mit Hinweis, dass ein falsches Ziel ueber
"Edit" an der PR umgestellt werden kann, statt die Arbeit neu zu machen.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---------
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: ralksta <ralksta@users.noreply.github.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
2026-08-10 10:41:01 +02:00
|
|
|
- [ ] Targets `dev`
|
2026-03-13 13:00:19 +01:00
|
|
|
- [ ] `npx tsc --noEmit` passes
|
|
|
|
|
- [ ] `npx vitest run` passes
|
|
|
|
|
- [ ] `npm run build` passes
|
|
|
|
|
- [ ] No secrets in the diff
|
|
|
|
|
- [ ] Documentation updated if needed
|
|
|
|
|
|
|
|
|
|
## License
|
|
|
|
|
|
|
|
|
|
By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).
|