Contributing¶

First of all, thank you for contributing to CytoTable! 🎉 💯

This document contains guidelines on how to most effectively contribute to the codebase.

If you are stuck, please feel free to ask any questions or ask for help.

Code of conduct¶

This project is governed by our code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to cytodata.info@gmail.com.

Security¶

Please see our SECURITY.md file for more information on security practices and recommendations associated with this project.

Quick links¶

Documentation: https://cytomining.github.io/CytoTable/
Issue tracker: https://github.com/cytomining/CytoTable/issues
Package Dependencies (via Poetry configuration): https://github.com/cytomining/CytoTable/blob/main/pyproject.toml

Process¶

Bug reporting¶

We love hearing about use-cases when our software does not work. This provides us an opportunity to improve. However, in order for us to fix a bug, you need to tell us exactly what went wrong.

When you report a bug, please tell us as much pertinent information as possible. This information includes:

The CytoTable version you’re using
The format of input data
Copy and paste two pieces of information: 1) your command and 2) the specific error message
What you’ve tried to overcome the bug
What environment you’re running CytoTable in (for example, OS, hardware, etc.)

Please provide this information as an issue in the repository: https://github.com/cytomining/CytoTable/issues

Please also search the issues (and documentation) for an existing solution. It’s possible we solved the bug already! If you find an issue already describing the bug, please add a comment to the issue instead of opening a new one.

Suggesting enhancements¶

We’re deeply committed to a simple, intuitive user experience, and to support core profiling pipeline data processing. This commitment requires a good relationship, and open communication, with our users.

We encourage you to propose enhancements to improve the CytoTable package as an issue in the repository.

First, figure out if your proposal is already implemented by reading the documentation! Next, check the issues (https://github.com/cytomining/CytoTable/issues) to see if someone else has already proposed the enhancement you have in mind. If you do find the suggestion, please comment on the existing issue noting that you are also interested in this functionality. If you do not find the suggestion, please open a new issue and clearly document the specific enhancement and why it would be helpful for your particular use case.

Your first code contribution¶

Contributing code for the first time can be a daunting task. However, in our community, we strive to be as welcoming as possible to newcomers, while ensuring rigorous software development practices.

The first thing to figure out is exactly what you’re going to contribute! We describe all future work as individual github issues. For first time contributors we have specifically tagged beginner issues.

If you want to contribute code that we haven’t already outlined, please start a discussion in a new issue before writing any code. A discussion will clarify the new code and reduce merge time. Plus, it’s possible your contribution belongs in a different code base, and we do not want to waste your time (or ours)!

Pull requests¶

After you’ve decided to contribute code and have written it up, please file a pull request. We specifically follow a forked pull request model. Please create a fork of the CytoTable repository, clone the fork, and then create a new, feature-specific branch. Once you make the necessary changes on this branch, you should file a pull request to incorporate your changes into the main CytoTable repository.

The content and description of your pull request are directly related to the speed at which we are able to review, approve, and merge your contribution into CytoTable. To ensure an efficient review process please perform the following steps:

Follow all instructions in the pull request template
Triple check that your pull request is adding one specific feature. Small, bite-sized pull requests move so much faster than large pull requests.
After submitting your pull request, ensure that your contribution passes all status checks (e.g. passes all tests)

Pull request review and approval is required by at least one project maintainer to merge. We will do our best to review the code addition in a timely fashion. Ensuring that you follow all steps above will increase our speed and ability to review. We will check for accuracy, style, code coverage, and scope.

Git commit messages¶

For all commit messages, please use a short phrase that describes the specific change. For example, “Add feature to check normalization method string” is much preferred to “change code”. When appropriate, reference issues (via # plus number) .

Development¶

Overview¶

CytoTable is primarily written in Python with related environments managed by Python Poetry. We use pytest for local testing and GitHub actions for automated tests via containers.

Getting started¶

To enable local development, perform the following steps.

Install Python
Install Poetry
Install Poetry Environment: poetry install

Code style¶

For general Python code style, we use black. For Python import order, we use isort. Please use black and isort before committing any code. We will not accept code contributions that do not use black and isort. We use the Google Style Python Docstrings.

Linting¶

Work added to this repo is automatically checked using pre-commit via GitHub Actions. Pre-commit can work alongside your local git with hooks After installing pre-commit within your development environment, the following command also can perform the same checks:

% pre-commit run --all-files

Testing¶

Manual testing for this project may be performed using the following tools. Automated testing is performed using GitHub Actions and follows the same checks.

pytest provides unit, functional, or integration testing. Example test command: % poetry run pytest
sphinx-build provides documentation website build checks via -W (which turns warnings into errors). Example command: % poetry run sphinx-build docs/source docs/build -W
pre-commit provides various checks which are treated as failures in automated testing. Example command % pre-commit run -all-files

Test Coverage¶

Test coverage is provided via coverage and pytest-cov. Use the following command to generate HTML coverage reports (reports made available at ./htmlcov/index.html):

% poetry run pytest --cov=cytotable tests/

Documentation¶

Documentation is generally provided through MyST (or Markedly Structured Text) markdown documents. Markdown content is transformed into docsite content using Sphinx. Documentation content assumes a “one sentence per line” style. Diagrams may be added using the Sphinx extension for Mermaid.

Documentation Linting¶

Documentation content is tested using the sphinx-build ... -W command to avoid missing autodoc members, etc. To check your documentation updates before pushing, use the following to trigger a related sphinx-build (content made available at ./docs/build/index.html):

% poetry run sphinx-build docs/source doctest -W

Documentation Builds¶

Documentation builds presume HTML as the primary export, e.g. sphinx-build -b html .... Documentation is automatically published to a docsite via GitHub Actions.

Attribution¶

Portions of this contribution guide were sourced from pyctyominer. Many thanks go to the developers and contributors of that repository.

Publishing Releases¶

Release Locations¶

We utilize semantic versioning (“semver”) in order to distinguish between major, minor, and patch releases. We publish source code by using GitHub Releases available here. We publish Python packages through the Python Packaging Index (PyPI) available here.

Release Publishing Process¶

There are several manual and automated steps involved with publishing CytoTable releases. See below for an overview of how this works.

Notes about semantic version (semver) specifications: CytoTable semvers are controlled through poetry-dynamic-versioning which leverages dunamai to create version data based on git tags and and commits. CytoTable release git tags are automatically applied through GitHub Releases and related inferred changes from release-drafter.

Open a pull request and use a repository label for release-<semver release type> to label the pull request for visibility with release-drafter (for example, see CytoTable#108 as a reference of a semver patch update).
On merging the pull request for the release, a GitHub Actions workflow defined in draft-release.yml leveraging release-drafter will draft a release for maintainers. The draft GitHub release will include a version tag based on the GitHub PR label applied and release-drafter. The draft release does not normally need additional modifications but may be changed as needed.
Make modifications as necessary to the draft GitHub release, then publish the release.
On publishing the release, another GitHub Actions workflow defined in publish-pypi.yml will run to build and deploy the Python package to PyPI (utilizing the earlier modified pyproject.toml semantic version reference for labeling the release).