Make sure you have read the FAQ

Thank you for wanting to contribute to making QtPass awesome.

Everyone taking part in QtPass, in issues, pull requests, Weblate or anywhere else, is expected to follow the Code of Conduct. Report problems to help@qtpass.org.

Getting Started

• Build it: see README.md's "From Source" section for dependencies and the one-line qmake6 && make build. Windows.md covers Windows specifically.
• Find your way around: CLAUDE.md's Architecture section has an overview of the two backends (RealPass/ImitatePass), the core classes and how they connect. It is written for AI agents working on this repository, but it is just as useful as a map for a human reading the code for the first time.
• Find something to work on: issues labelled good first issue or help wanted are a good place to start. Not sure where to begin, or have a question before opening an issue? Ask in Discussions or email help@qtpass.org.
• Run the tests: make check builds and runs the Qt Test suite in tests/auto/; see step 2 below for what a pull request is expected to add.

Pull Request Process

1. Sign your commits - All commits must be signed with GPG and signed off under the Developer Certificate of Origin: git commit -s -S -m "description" (-S signs, -s adds the Signed-off-by: line). Translation updates from Weblate arrive as Weblate's own commits without a sign-off; a committer reviews them before merging.
2. Add tests - New features and bugfixes come with tests in tests/auto/, and make check must pass. Format the C++ files you changed with clang-format --style=file -i <file>...; CI runs the linters on Pull Requests that change code, build files, scripts or documentation.
3. Ensure install or build dependencies and artifacts are not committed.
4. When adding big new features or changes to the build tool, update the README.md to reflect those.
5. Make sure you update all the CI configs if needed. These run on every Pull Request.
6. Increase the version numbers in relevant files when applicable. The versioning scheme we use is PrideVer.
7. Committers merge their own Pull Requests once CI and the automated review pass. A Pull Request from outside the team is reviewed by a committer, who merges it.

AI assistance

Using an AI coding assistant is fine. The rules:

• Disclose it. Add a Co-Authored-By: trailer naming the tool or model to each assisted commit (for example Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>), or say so in the pull request description.
• You are the author. Read, understand and test everything you submit; do not open a pull request with output you cannot explain. The DCO sign-off applies to assisted commits exactly as to hand-written ones.
• Keep secrets out. Never paste password-store contents, GPG key material or other private data into an assistant.
• AI review findings are advisory. CodeRabbit and Copilot comment on pull requests; verify each finding against the code, fix what is real, and answer false positives with a short explanation instead of a change.
• Machine-drafted translations stay type="unfinished" in the .ts files so native speakers can finalise them on Weblate.

Agents working on this repository should read AGENTS.md and the skills under .opencode/skills/.

Translations

QtPass uses Weblate for translations.

To add a new language:

• Add your language code to src/src.pro under TRANSLATIONS
• If you have an existing build, run make distclean first (prevents stale generated files like ui_*.h from being included)
• Determine which qmake command your Qt 6 installation provides: run qmake6 -v (or qmake -v if qmake6 is unavailable) and confirm it shows Qt version 6.8 or newer.
• Run that same command (qmake6 or qmake) at the repository root, then make lupdate; the target runs lupdate over both src/ and main/ and updates every .ts file. Do not run lupdate on src/src.pro alone: that misses the strings in main/. A plain qmake6 run leaves localization/ untouched.
• Edit the .ts file with Qt Linguist: linguist localization/qtpass_xx_YY.ts

Qt Linguist has helpful in-context translation options.

Windows Developers: Symlink Setup

This repository contains a symlink (.claude -> .opencode). Windows developers need to enable symlink support:

Option 1: Enable Developer Mode on Windows 10+ (recommended)

• Go to Settings > Update & Security > For developers
• Enable "Developer Mode"

Option 2: Configure Git to use symlinks

git config core.symlinks true

Set this before cloning the repository.

Warning: Without symlink support enabled, .claude will be checked out as a regular text file containing the path ".opencode" instead of a proper symlink.

Troubleshooting: After cloning:

• Run ls -l .claude (Git Bash) or dir .claude (CMD) to verify it shows as a symlink, not a regular file.
• If it appears as a regular file, set core.symlinks=true in your Git config, then re-checkout the file or re-clone the repository to restore the proper symlink.

Getting Help

• Open an issue for bugs or feature requests
• Ask in Discussions for questions that are not a bug or feature request
• Email help@qtpass.org for general questions

License

QtPass is released under the GNU GPL v3.0 license. https://www.gnu.org/licenses/gpl-3.0.html