Contributing to jm-python-template¶

First off, thank you for considering contributing to jm-python-template! 🎉

We welcome contributions of all kinds — code, documentation, testing, translations, and ideas.

This guide will walk you through the process.

📜 Code of Conduct¶

This project follows the Contributor Covenant Code of Conduct v2.1. By participating, you are expected to uphold this code. Please report unacceptable behavior to the maintainers.

🚀 Getting Started¶

1. Fork & Clone¶

Fork the repository via GitHub and clone your fork locally:

git clone https://github.com/your-username/jm-python-template.git
cd jm-python-template

Development Environment¶

We use Hatch for environment and project management.

Enter the development environment with:

hatch shell

Run the tests to verify everything works:

   hatch test

or

   hatch run test:test

Optional: Using `Task`¶

If you have Task installed, you can simplify common commands:

task test
task translate-source

Documentation¶

Documentation is built with MkDocs. Preview locally with:

   hatch run docs:serve

✅ How to Contribute¶

Reporting Bugs 🐛¶

Use the GitHub Issues page.
Include details:
Steps to reproduce
Expected behavior
Actual behavior
Environment (OS, Python version, dependencies)

Suggesting Features 💡¶

Open a Feature Request issue.
Explain the problem, proposed solution, and alternatives considered.

Submitting Changes 📝¶

Fork the repository.
Create a new branch.

Use a clear, descriptive name for your branch.

    git checkout -b feature/your-feature-name

Make your changes.
Ensure all tests pass.

Run the test suite to confirm your changes haven't introduced any bugs.

  hatch test

Run linting and formatting.

This ensures your code meets the project's quality standards.

  hatch lint:check-all

Commit your changes.

This helps maintain a clean and descriptive commit history. Using Conventional Commits:

  feat: add new feature
  fix: fix bug or correct some handling
  docs: update documentation

Push your branch and open a Pull Request.

Push your changes to your fork and then open a pull request against the main repository

📖 Coding Standards¶

Python 3.11+ only
Follow PEP 8 with additional style enforced by Ruff
Use type hints everywhere
Write docstrings in Google style
Keep functions small and focused
Add or update tests for all changes

🧪 Testing¶

We use pytest and pytest-mock. Run tests:

   hatch test

Run a specific test file:

   hatch shell test.py3.13
   hatch run pytest tests/test_my_feature.py

Run with coverage:

   hatch run test:coverage

🌍 Translations¶

jm-python-template supports internationalization (i18n) for both Python and Qt components. If you’d like to contribute translations, please follow the steps below.

Update Babel (.po) Translations (Python)¶

Extract and update translation strings for all languages:

  task extract-translations

Edit the generated .po files under src/jm-python-template/locales/<lang>/LC_MESSAGES/
Compile the translations (optional, usually handled by task):

  task compile-translations

Update Qt Translations (.ts/.qm)¶

Update Qt .ts and .qm files for GUI components:

    task extract-qt-translations

Edit the generated .ts files under src/jm-python-template/gui/translations/.
Compile resources (handled automatically by translate-qt):

    task compile-translations

📦 Releases (Maintainers only)¶

Releases are managed with Hatch.

Update the version:

   hatch version minor

Commit with chore: release vX.Y.Z
Create a GitHub release and tag
Publish with:

hatch build
hatch publish

📄 License¶

Contributions to this project are licensed under the EUPL-1.2.

🙏 Thank You¶

Your contributions make jm-python-template better for everyone. We truly appreciate your time, effort, and ideas 💙