Contributing to the Gene Normalizer#
Bug reports and feature requests#
Bugs and new feature requests can be submitted to the Gene Normalizer issue tracker on GitHub. See this StackOverflow post for tips on how to craft a helpful bug report.
Development prerequisites#
For a development install, we recommend using Pipenv. See the Pipenv docs for direction on installing Pipenv in your environment.
Setup#
Clone the repository:
git clone https://github.com/cancervariants/gene-normalization
cd gene-normalization
Then initialize the Pipenv environment:
pipenv update
pipenv install --dev
pipenv shell
Alternatively, use a virtual environment and install all dependency groups:
python3 -m venv venv
source venv/bin/activate
python3 -m pip install -e ".[pg,etl,test,dev,docs]"
We use pre-commit to run conformance tests before commits. This provides checks for:
Code format and style
Added large files
AWS credentials
Private keys
Before your first commit, run:
pre-commit install
When running the web server, enable hot-reloading on new code changes:
uvicorn gene.main:app --reload
Style#
Code style is managed by Ruff, and should be checked via pre-commit hook before commits. Final QC is applied with GitHub Actions to every pull request.
Tests#
Tests are executed with pytest:
pytest
By default, tests will utilize an existing database, and won’t load any new data. For test environments where this is unavailable (e.g. in CI), the GENE_TEST environment variable can be set to ‘true’ to initialize the connected database instance with miniature versions of input data files before tests are executed:
export GENE_TEST=true
Warning
Tests executed under the GENE_TEST environment will overwrite existing data. It is recommend that a database instance separate from the main working environment is used.
Documentation#
The documentation is built with Sphinx, which is included as part of the Pipenv developer dependencies, or in the docs
dependency group. Navigate to the docs/ subdirectory and use make to build the HTML version:
pipenv shell
cd docs
make html
See the Sphinx documentation for more information.
Figure generation#
We are experimenting with the inclusion of some static HTML figures in the documentation. For now, scripts used to generate these figures should be provided in docs/scripts/
, and any external dependencies should be included in the docs
dependency group.