Contributing

Stashix is free software under the GNU AGPL v3 or later, and help of any size is welcome. You don’t need to write code: at this early stage, using Stashix and telling us where it falls short helps the most. For a short overview, read how you can help.

Ways to help

Report a bug

Search the existing issues first; if your problem is already there, add what you know to it. Otherwise open a bug report and include:

• Your Stashix version and how you installed it (Docker Compose, from source).
• What you did, step by step, so someone else can do the same.
• What you expected, and what happened instead.
• The server log around the time of the problem: docker compose logs stashix. Remove anything private, such as hostnames or file paths you don’t want to share.
• For a problem with one file, its format (.cbz, .cbr, .pdf …) and, if you can, how its folder is laid out. See file structure.

Files that won’t open, series that group wrongly and metadata that matches the wrong issue are all worth reporting, even if you’re not sure it’s a bug.

Suggest a feature

Open a feature request. Start with the problem you want solved and why it matters to you, then describe what you’d like to happen. A use case is more useful than a finished design.

Check the roadmap first: it lists what’s already planned, such as more formats, more metadata sources, reading lists, and translation and localization of the interface. If your idea is on it, a comment on why you need it helps decide what comes first.

Improve the documentation

This site lives in its own repository. Every docs page has an Edit this page link that opens its source on GitHub, where you can propose a change as a pull request. That’s enough for most fixes.

For bigger changes, run the site locally. You need Go and Hugo Extended; the site README lists the exact versions.

git clone https://github.com/Aroy-Art/Stashix-Site.git
cd Stashix-Site
make serve   # http://localhost:1313/

Pages are Markdown under content/docs/. Keep sentences short, write for someone running Stashix for the first time, and test any command you add.

Work on the code

Stashix is written in Elixir with Phoenix LiveView, on PostgreSQL. To run it from source, follow the development instructions in the README. You need Elixir, Erlang/OTP, PostgreSQL and a few system tools (vips, p7zip, unrar, pdfinfo, pdftoppm).

For anything bigger than a small fix, open an issue first and describe what you plan to do, so nobody spends time on a change that won’t fit.

Before you open a pull request

CI checks formatting, compiler warnings and tests on every code change. Run the same checks in stashix_web/ first:

mix format --check-formatted
mix compile --warnings-as-errors
mix test

• Add or update tests for the behaviour you change.
• Update the changelog. Add a line under ## [Unreleased] in CHANGELOG.md for anything a user would notice. It follows Keep a Changelog.
• Keep pull requests focused: one fix or feature each.

Commits

Write commit messages in the Conventional Commits style, with a scope when it helps, for example fix(parser): … or docs(readme): ….

Sign off each commit to certify you wrote it or have the right to submit it under the project’s licence (the Developer Certificate of Origin):

git commit -s

By contributing, you agree that your work is released under the AGPL v3 or later.

Spread the word

Star the repository and tell people who keep a comic or manga collection about Stashix.

• Reporting security issues: how to report a vulnerability privately.