Skip to content

scpviz Contribution Guidelines

Thank you for your interest in contributing to scpviz, an open-source Python package for visualizing and analyzing single-cell and bulk proteomics data.
We welcome contributions from the community to help improve, expand, and document the functionality of scpviz.

Code of Conduct

By participating in this project, you agree to abide by the Contributor Covenant.
Please be respectful and considerate in your interactions with others.

How to Contribute

To get an overview of the project, read the README file.

There are several ways you can contribute to scpviz, including but not limited to:

  • asking and answering questions in Discussions,
  • reporting bugs and requesting features by submitting new issues,
  • adding new features and fixing bugs by creating pull requests (PRs),
  • improving and maintaining consistency in the documentation (including docstrings and tutorials), and
  • providing reproducible examples and workflows in Jupyter notebooks.

Getting Started

Issues

Open a New Issue

Before reporting a bug or requesting a feature, search to see if a related issue already exists.
If not, you can submit a new issue — make sure to include:

  • a clear and descriptive title,
  • relevant environment or dataset information (if applicable), and
  • a minimal, reproducible example (if possible).

Solve an Issue

Browse through the existing issues to find one that interests you.
You can filter by labels (e.g., feature, bug, enhancement).
If you find an issue you’d like to work on, comment to let maintainers know and open a PR when ready.

Make Changes

To contribute to scpviz, use the fork and pull request workflow described below.

  1. Fork the repository.

  2. Clone your fork locally and navigate to it:

    git clone https://github.com/gnaprs/scpviz.git cd scpviz

  3. Create a new branch for your feature or fix:

    git checkout -b

  4. Install scpviz and its development dependencies:

    pip install -e .[dev]

You may also want to create and activate a virtual environment before installing dependencies:

   python3 -m venv .venv
   source .venv/bin/activate

  1. Run tests to confirm everything works before editing:

    pytest tests/ -v

Development Guidelines

Please follow these best practices when contributing code:

  • Follow the PEP 8 style guide.
  • Write clear, consistent docstrings in the Google style.
  • Add pytest unit tests for new functions and features.
  • Use meaningful variable names and comments where appropriate.
  • Keep imports organized and minimal.
  • When modifying documentation, ensure that mkdocs build --strict completes successfully.

Commit Your Update

When your changes are ready:

  1. Ensure that all unit tests pass:

    pytest tests/ -v

  2. Stage and commit your changes:

    git add . git commit -m ""

  3. Push your branch to your fork:

    git push origin

Pull Request

To contribute your changes to the main scpviz repository, create a pull request.
The project maintainers will review your PR and provide feedback.
If your changes align with the project goals and pass all tests, they will be merged into the main branch.

Documentation Contributions

The documentation for scpviz is built with MkDocs Material.

To build and preview locally:

mkdocs serve

Your changes will automatically rebuild the site in your browser.

When merged to main, the documentation is automatically deployed to
https://gnaprs.github.io/scpviz/
via GitHub Actions (ci.yml).

Release Process (Maintainers)

When ready to publish a new version:

  1. Update the version number in pyproject.toml.
  2. Commit, tag, and push: 
    git commit -am "Bump version to v0.X.Y"
git tag -a v0.X.Y -m "Release v0.X.Y"
git push origin main --tags
  3. Build and upload to PyPI: 
    python -m build
twine upload dist/*
  4. Verify:
  5. PyPI: https://pypi.org/project/scpviz/
  6. Docs: https://gnaprs.github.io/scpviz/
  7. Coverage: https://codecov.io/gh/gnaprs/scpviz

Additional Resources

Thank you for helping make scpviz a reliable, open, and community-driven platform for single-cell and spatial proteomics research.