Code of conduct

We warmly welcome contributions from the community!

To ensure a welcoming experience for our entire community, this project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to opensource@chanzuckerberg.com.

If you have any questions about any of this stuff, just ask! :)

Contributing ideas and issues

We’d love to hear from you! Please submit any bug reports and feature requests through Github issues.

Direct contributions

Getting started

If you are interested in working on cellxgene development, you’ll need to use git to make a copy of the project repository and share your changes.

We have several “rules” (strong suggestions really) for contributions:

1. If your contribution is complex, adds new features, new UI design or otherwise warrants discussion, we highly recommend that you submit a github issue, and engage other contributors in a discussion about the details of your proposed PR. This will save you time in the long run, as many details and decisions can be hashed out ahead-of-time.

2. Please submit any direct contributions by forking the repository, creating a feature branch, and submitting a Pull Request.

First, you’ll need the following installed on your machine

• python 3.6+
• node and npm (we recommend using nvm if this is your first time with node)

Then clone the project

git clone https://github.com/chanzuckerberg/cellxgene.git

This is enough to get you started with editing documentation. If you’d like to contribute code:

Build the client web assets from inside the cellxgene folder

make build-for-server-dev

Install all requirements (we recommend doing this inside a virtual environment)

pip install -e .

You can start the app while developing either by calling cellxgene or by calling python -m server. We recommend using the --debug flag to see more output, which you can include when reporting bugs.

If you have any questions about developing or contributing, come hang out with us by joining the CZI Science Slack and posting in the #cellxgene-dev channel.

Contributing code

This project has made a few key design choices:

• The front-end is built with regl (a webgl library), react, redux, d3, and blueprint to handle rendering large numbers of cells with lots of complex interactivity
• The app is designed with a client-server model that can support a range of existing analysis packages for Python-based backend computational tasks (currently built for scanpy)
• The client uses fast cross-filtering to handle selections and comparisons across subsets of data

Depending on your background and interests, you might want to contribute to the frontend, or backend, or both!

Please submit any direct contributions via a Pull Request. It’d be great for PRs to include test cases and documentation updates where relevant, though we know the core test suite is itself still a work in progress.

Contributing documentation

The documentation is written in markdown, and lives in the directory cellxgene/docs/posts. You can directly edit or add to these files and submit a Pull Request as described above.

To preview your changes on your local machine, you’ll need to install Jekyll and Ruby using these instructions (you don’t have to know how to program in Ruby, just install it).

You can then preview your changes by running cellxgene/docs$ bundle exec jekyll serve and navigating to the url indicated in the terminal.