First of all, thank you for contributing to pycytominer! 🎉 💯
This document contains guidelines on how to most effectively contribute to the pycytominer codebase.
If you are stuck, please feel free to ask any questions or ask for help.
- Bug reporting
- Suggesting enhancements
- Your first code contribution
- Pull requests
- Documentation
- Poetry
- Dev environments
- Releases
This project and everyone participating in it 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.
- Documentation: https://pycytominer.readthedocs.io/en/latest/
- Issue tracker: https://github.com/cytomining/pycytominer/issues
- Code coverage: https://app.codecov.io/gh/cytomining/pycytominer
- Package requirements (using Poetry): https://github.com/cytomining/pycytominer/blob/main/pyproject.toml
There are two primary roles with regards to developing Pycytominer:
- Contributors: individuals without direct commit access to the
mainbranch who make contributions in the form of communication, issues, or pull requests. We welcome anyone interested in additions to the project to be a contributor. - Maintainers: individuals with direct commit access who make contributions as outlined by the contributors role and also have the ability to make commits on the
mainbranch through the development process (for example, by merging pull requests). Maintainers are also involved with decision-making procedures and the technical roadmap for Pycytominer.
Maintainers are prior contributors who receive extended privileges based on a decision by existing maintainers. To become a Pycytominer maintainer you must be championed by an existing maintainer. The championing maintainer consults with other maintainers about the addition of the new maintainer. After the current maintainers have considered the qualifications of the new maintainer they communicate their preferences internally. If there are no vetos the champion maintainer will grant maintainer access to the new maintainer.
Maintainer access may be removed under the following circumstances:
- Voluntary step-down (when a maintainer no longer wishes to remain in that role)
- In the unfortunate event of a maintainer's passing
- Code of conduct violations (in addition to other procedures specified by the code of conduct itself)
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 be prepared to tell us as much pertinent information as possible. This information includes:
- The pycytominer 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
Please provide this information as an issue in the repository: https://github.com/cytomining/pycytominer/issues
Please also search the issues (and documentation) for an existing solution. It’s possible we solved your bug already! If you find an issue already describing your bug, please add a comment to the issue instead of opening a new one.
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 pycytominer package.
First, figure out if your proposal is already implemented, by reading the documentation! Next, check the issues (https://github.com/cytomining/pycytominer/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.
Please provide your enhancement suggestions as an issue in the repository:
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 have specifically tagged beginner issues, but we describe all future work as individual github issues.
If you want to contribute code that we haven’t already outlined, please start a discussion in a new issue before actually writing any code. A discussion will clarify the new code and reduce merge time. Plus, it’s possible that your contribution belongs in a different code base, and we do not want to waste your time (or ours)!
After you’ve decided to contribute code and have written it up, now it is time to file a pull request. We specifically follow a forked pull request model. Please create a fork of the pycytominer 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 pycytominer 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 pycytominer. 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 only 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)
All pull requests must be reviewed and approved by at least one project maintainer in order to be merged. 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.
We use sphinx for autodocumentation of docstrings, using the napoleon extenstion to parse NumPy style docstrings, implemented with a furo theme. We host our documentation on readthedocs.org at https://pycytominer.readthedocs.io/en/latest/.
To build and test changes to the docs locally, run the following command:
sphinx-build -b html docs buildSee docs/conf.py for full documentation configuration.
We use Poetry to manage dependencies and packaging.
Changes in dependencies are managed by Poetry's pyproject.toml file.
Poetry installs all dependencies in a virtual environment, which is activated automatically when you run poetry shell.
Poetry also provides a poetry run command to run commands in the virtual environment without activating it.
For example, to run the test suite, you can use poetry run pytest.
Instructions for setting up a local development environment using VSCode DevContainers:
- Install VSCode
- Install the Remote - Containers extension
- Open the repository in VSCode
- Click on the green "Reopen in Container" button in the lower left corner of the window
- Wait for the container to build and install the required dependencies
We've set up cloud development configurations with Github Codespaces.
These development environments include the project dependencies pre-installed via Poetry.
Prior to commit, pre-installed git hooks auto-format any changed code.
When you are ready to make a pull request, use the pre-configured test suite in VSCode or run poetry run pytest to ensure that your changes pass all tests.
You can create a codespace by clicking on the following link:
Beginner's Guide to Codespaces
We recommend using either the local devcontainer or cloud dev environment approaches above. However, we also provide general guidance for setting up a dev environment in Linux, MacOS, or Windows (WSL) below.
# Install Poetry (Linux, MacOS, Windows - WSL)
curl -sSL https://install.python-poetry.org | python3 -
# Checkout the repository
git clone https://github.com/cytomining/pycytominer.git
cd pycytominer
# Install pycytominer, dev dependencies, and pre-commit hooks
bash .devcontainer/postCreateCommand.shProject maintainers are responsible for releasing new versions of pycytominer. Creating a new release includes the following steps:
- Create a new branch from
mainfor the release (e.g.release-v1.0.0) - Review the commit history from the last release and check whether it includes commits that don't follow the conventional commit standard. If all changes follow conventional commits, skip to step 5.
- Run the command
poetry run cz bump --files-onlyto update the version number inCITATION.cffandpyproject.toml:tool.commitizenand generate the draft changelog. - Review the changes to
CHANGELOG.md. If necessary, add descriptions of missing changes and modify descriptions to match conventional commits standard. git addany manual changes and runpoetry run cz bumpto create the release commit. Push the changes to the release branch.- Create a pull request for the release branch into
main. - Request a review from another maintainer.
- Once the pull request is approved, merge it into
main. - Create a new release on GitHub using the release draft feature.
- Publish the release.
- The release will be automatically published to PyPI via Github Actions.
- Manually create the release at conda-forge.
We automate image pushes for pycytominer under the cytomining organization on Docker Hub using GitHub Actions workflows.
These pushes are defined within .github/workflows/integration-test.yml.
- Scheduled: We create new Docker image releases on a weekly basis to incorporate the latest updates from external dependencies (such as OS updates, Python versions, etc.).
An image tag published this way may appear as
cytomining/pycytominer:1.1.0.post2.dev0_892dee2_240320, where the dynamic version ofpycytomineris referenced alongside a date in the formatYYMMDD. - Push (to
main): We generate new Docker image releases on pushes or merges to themainbranch. An image tag published this way might appear as eithercytomining/pycytominer:1.1.0(for a release) orcytomining/pycytominer:1.1.0.post2.dev0_892dee2(for a non-release).
Please follow the below quality guides to the best of your abilities. If you have configured your dev environment as described above, the formatting and linting rules will also be enforced automatically using the installed pre-commit hooks.
We use ruff for formatting Python code, and prettier for formatting markdown, json and yaml files.
Ruff includes a python code formatter similar to Black.
We include ruff in the poetry dev dependencies so it can be run manually using ruff format
Prettier (which is not python-based) is not included in the poetry dev dependencies, but can be installed and run manually.
Alternately, both ruff format and prettier will be run automatically at commit time with the pre-commit hooks installed.
For python code linting, we also use ruff, which can perform same linting checks as Flake8.
You can use the command ruff check to check for linting errors.
The list of linting rules and exceptions are defined in the pyproject.toml file under the [tool.ruff.lint] section.
We also include some commented-out rules in that section that we are working towards enabling in the future.
All linting checks will also be run automatically at commit time with the pre-commit hooks as described above.
Pycytominer uses Conventional Commits standard for commit messages to aid in automatic changelog generation. We prepare commit messages that follow this standard using commitizen, which comes with the poetry dev dependencies.
We use the numpy documentation style guide. When writing markdown documentation, please also ensure that each sentence is on a new line.