Development Contributing

Contributing

Before you start

Platemaker is open source and the licence lets you do what open source licences let you do — fork it, change it, build it, ship your own version.

What it is not, right now, is a project looking for collaborators. There is no roadmap seeking hands, no triage of incoming work, and no undertaking that a pull request will be read promptly or at all. That is a statement of capacity rather than of principle, and it may change.

So: if something here is useful to you, take it. If you want to send a change back, the rest of this page tells you how to make it easy to accept — but please open an issue first and ask whether it is wanted before doing significant work.

To extend the strip editor (a tool, a balloon shape, a kind of object), start with Extending the strip editor in the repository's specification outline: it lists the files each one touches and the tests that tell you what you missed.

By opening a pull request you agree to the Contributor License Agreement.

Branching

Fork from main, and branch with a feature/ or fix/ prefix:

main            development; every release is a tag on it
feature/<name>  short-lived, merged into main
fix/<name>

No build/test CI

Nothing builds or tests your change automatically — there is no compile-or-test gate on a push or pull request, so build it and run it yourself before proposing it. (There are workflows for release automation and for submitting the dependency graph, and the library has a "third-party coverage" check, but none of them compiles or exercises the app.)

The library has GoogleTest and pytest suites. The GUI has a small GoogleTest target for its property model (tests/gui-unit-tests/, configure with PLATEMAKER_GUI_BUILD_TESTS=ON), with no window involved; everything with a window is verified manually.

Editing .ui files

.ui files are edited in Qt Designer, never by hand.

Two separate hazards, and the second catches people who know about the first:

1. Qt Creator regenerates ui_*.h from the .ui at build time, so hand-edited XML is overwritten by the build.
2. A .ui file open in Qt Designer will write its own in-memory version over your on-disk changes when it saves — so editing a file that is open elsewhere silently loses the edit.

Adding a widget:

1. Open the .ui in Qt Designer inside Qt Creator
2. Drag the widget in
3. Set its object name and properties
4. Build — the header is regenerated
5. Reference it as ui->objectName from the .cpp

Object names follow the widget type, then the role: pushButtonRender, comboBoxOutputProfile, listInputImageTile.

Commit messages

<type>(<component|scope>): brief message

- 1st detail
- 2nd detail
- Nth detail

Type is one of feat, fix, docs, chore, style, refactor.

Component or scope is either something concrete — a class, file or namespace — or a broader abstract area such as the build system.

Details describe the significant changes, one or two lines each. Leave out anything obvious from the diff: a typo fix does not need a bullet explaining that documentation was touched.

Coding style

Shared conventions live in docs/CODING_STYLE.md in the library repository, and apply to both projects.

Doxygen: short members are documented with //!< on the declaration line; anything with parameters or a return value gets a /** @brief … @param … @return … */ block. Public API is documented in the header, not the .cpp.

Updating this wiki

The wiki is its own git repository — clone Platemaker-qt.wiki.git, edit, push to master.

Conventions to keep:

• Pages are flat files in the repository root, prefixed Manual-, Comic-Production- or Development-. No subdirectories — they change the page URL depth, and pages created from the browser land in the root anyway
• Links in prose and in _Sidebar.md use [[Display text|Page-Name]]
• Links inside a table use [Display text](Page-Name) instead. The | in a wiki link collides with the table's own column separator, so table cells take ordinary Markdown links
• Images live under images/, grouped by page slug as a default, not a rule — one screenshot that serves several pages (a window shot reused across Main window and Menu reference, say) stays in one place and is referenced from each page. Do not duplicate a file just to satisfy the folder layout
• Images are referenced by their full raw.githubusercontent.com/wiki/… URL, not a relative path, which is why a cross-folder reference works fine
• Image filenames have no spaces, so no URL needs %20
• Every new page is added to _Sidebar.md, otherwise nothing links to it
• Every page ends with a See also line, so readers arriving from a search engine can still navigate
• Document current behaviour by default. Anything not yet working, or due to change, is marked as such and points at the relevant TODO.md rather than being quietly omitted
• Facts that originate outside Platemaker — a publishing platform's size caps or upload behaviour, for instance — carry the date they were last verified ("Figures last checked: July 2026"). They go stale without anyone editing the wiki, and an undated claim gives a reader no way to judge how much to trust it
• Second person for the Manual and Comic production pages ("press Render"); impersonal for Development
• British spelling, matching the codebase — colour, organised, licence

---

See also: Development · Architecture · Releasing