Contributing to QEM

We welcome contributions to QEM! This guide explains how to contribute effectively.

Types of Contributions

Bug Reports

Report bugs using GitHub issues with detailed information about the problem.

Feature Requests

Suggest new features or improvements via GitHub issues.

Code Contributions

Submit pull requests for bug fixes, new features, or improvements.

Documentation

Help improve documentation, tutorials, and examples.

Testing

Add tests for existing functionality or help improve test coverage.

Development Workflow

  1. Fork and Clone

git clone https://github.com/yourusername/qem.git
cd qem

  1. Set Up Environment

conda create -n qem-dev python=3.11
conda activate qem-dev
pip install -e ".[dev]"

  1. Create Feature Branch

git checkout -b feature/your-feature-name

  1. Make Changes - Write clean, documented code - Add tests for new functionality - Update documentation as needed

  2. Run Tests

pytest
ruff check qem/
ruff format qem/

  1. Submit Pull Request - Push to your fork - Create pull request on GitHub - Describe your changes clearly

Code Standards

Style Guide

  • Follow PEP 8

  • Use Ruff for formatting and linting

  • Maximum line length: 160 characters

Type Hints

  • Add type hints to all public functions

  • Use numpy.typing.NDArray for arrays

Documentation

  • Write NumPy-style docstrings

  • Include examples in docstrings

  • Update user guides for new features

Testing

  • Write tests for all new functionality

  • Maintain >80% test coverage

  • Use pytest fixtures for setup

Example Contribution

Here’s an example of a well-structured contribution:

def new_analysis_function(
    image: NDArray[np.floating],
    threshold: float = 0.5
) -> NDArray[np.floating]:
    """
    Perform new type of analysis on STEM image.

    Parameters
    ----------
    image : NDArray[np.floating]
        Input STEM image
    threshold : float, default=0.5
        Analysis threshold value

    Returns
    -------
    NDArray[np.floating]
        Analysis result

    Examples
    --------
    >>> import numpy as np
    >>> image = np.random.random((100, 100))
    >>> result = new_analysis_function(image)
    >>> result.shape
    (100, 100)
    """
    # Implementation here
    return processed_image

Pull Request Guidelines

Before Submitting

  • Ensure all tests pass

  • Update documentation

  • Add entry to changelog

  • Rebase on latest main branch

PR Description

  • Clear title describing the change

  • Detailed description of what was changed

  • Link to related issues

  • Screenshots for UI changes

Review Process

  • Maintainers will review your PR

  • Address feedback promptly

  • Keep discussion focused and constructive

Reporting Issues

When reporting bugs, please include:

  • QEM version

  • Python version

  • Operating system

  • Backend being used (JAX/TensorFlow/PyTorch)

  • Minimal code example reproducing the issue

  • Error message and traceback

Community Guidelines

  • Be respectful and inclusive

  • Focus on constructive feedback

  • Help others learn and improve

  • Follow the code of conduct

Getting Help

If you need help contributing:

  • Ask questions in GitHub discussions

  • Check existing issues and PRs

  • Contact maintainers: zhangzz@aisi.ac.cn

Recognition

All contributors are recognized in:

  • AUTHORS file

  • GitHub contributors list

  • Release notes for significant contributions

Thank you for contributing to QEM!