Contributing

Contributions are welcome. The project is small and single-maintainer, so the process is light.

The authoritative version of this document is CONTRIBUTING.md in the repository.

Before you start

Everyone participating is bound by the Code of Conduct.

Reporting a bug

Open a bug report and include:

• what you expected and what happened instead
• exact steps to reproduce
• the startup log — docker compose logs brandkit or the console output
• Python version, or Docker and Compose versions
• your operating system
• the source image, if it is not confidential and the bug depends on it

Never report a security issue as a public issue

Email fabrizio.salmi@gmail.com instead. See the security policy.

Proposing a feature

Open a feature request. Describe the problem before the solution — what are you trying to do that BrandKit makes hard?

Two things that are almost always accepted:

• New formats. They are pure data in config.json. If a platform changed its recommended image size, that is a one-line PR and a genuinely useful one.
• Documentation fixes. Every page on this site has an "Edit this page on GitHub" link at the bottom.

Development setup

git clone https://github.com/fabriziosalmi/brandkit.git
cd brandkit

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

FLASK_ENV=development python app.py

FLASK_ENV=development gives you auto-reload and the Werkzeug debugger on http://127.0.0.1:8000. Never set it anywhere anyone else can reach.

Where things live

File	What it is
app.py	the entire backend — routes, image pipeline, caching, cleanup
templates/index.html	the entire frontend — one Jinja template with inline Alpine.js
config.json	the format catalogue and preprocessing defaults
static/vendor/	vendored Tailwind and Alpine — do not replace with CDN links
docs/	this documentation site (VitePress)

The project is deliberately two files. If a change would split them, say so in the issue first.

Pull requests

1. Fork and branch — git checkout -b feat/short-description
2. Make the change
3. Test it (see below)
4. Commit with a Conventional Commits prefix — feat:, fix:, docs:, ci:, build(deps):
5. Open the PR against main, describing what changed and how you verified it

Keep pull requests focused. A formatting sweep mixed into a behaviour change is very hard to review.

CI

Every push and pull request runs the CI workflow: install requirements.txt on Python 3.11 and 3.12, then python -c "import app".

That is genuinely all it does — there is no test suite yet. A pull request that adds one would be very welcome, and pytest with Flask's test client is the obvious starting point.

Manual test checklist

Until there are automated tests, verify by hand:

• the page loads and the format catalogue renders
• an upload generates the expected files with the expected dimensions
• PNG output keeps transparency; JPG flattens it
• ICO is produced when favicon is selected, and only then
• background removal works, or degrades cleanly when rembg is absent
• the ZIP contains everything shown in the results grid
• POST /upload without a CSRF token still returns 400
• the sixth upload in a minute returns 429

Documentation

If your change alters behaviour, update the docs in the same pull request.

npm install
npm run docs:dev      # http://localhost:5173
npm run docs:build    # production build, catches dead links

docs:build fails on broken internal links, so run it before pushing.

Why package.json has an overrides block

VitePress 1.6.4 pins Vite 5, which is no longer receiving fixes for a set of dev-server advisories (a server.fs.deny bypass, a path traversal in optimized-deps .map handling, and the esbuild CORS issue). VitePress 2 is still alpha, so the toolchain is pulled forward with npm overrides instead:

"overrides": {
  "esbuild": "^0.25.12",
  "vite": "^6.4.3"
}

The combination is verified — the site builds and renders correctly — but it is ahead of what VitePress 1.6 declares. If a build breaks after a dependency bump, this block is the first thing to look at. Drop it once VitePress 2 is stable.

None of this reaches the published site: GitHub Pages serves static output, so Vite exists only at build time and in npm run docs:dev.

Style

Python — PEP 8, four spaces, snake_case. Docstrings on any function that is not obvious. Prefer clarity over cleverness; this codebase is read far more often than it is written.

Commits — imperative mood, Conventional Commits prefix, one logical change each.

Getting help

• Issues for bugs and features
• Troubleshooting for problems running it
• fabrizio.salmi@gmail.com for security reports

Licence

Contributions are licensed under the MIT License, the same as the project.