5. Contributing

sgRNAble Contribution Guide

Getting Started

Cloning Code

To get a copy of the code, clone directly from this Github repository:

git clone https://github.com/hallamlab/sgRNAble.git

Installing Dependencies

We recommend using a Conda enviornment to manage dependencies and python version, these commands create an enviornment called sgrnable with python version 3.7:

conda create --name sgrnable python=3.7
conda activate sgrnable

To install dependencies, navigate to the repository root, and run the following command:

pip install -r requirements.txt

Directory Structure

The repository root directory contains the project info and setup files. The main source code is located under the optimal_guide_finder directory, and tests are located in a separate tests directory.

The Azimuth_Model directory contains code from the Azimuth project.

Running Tests

To run sgRNAble tests, navigate to the tests directory (this avoids running both sgRNAble and Azimuth tests), and run the tests using pytest

pytest

This will automatically locate and run sgRNAble tests located in the directory.

Adding Changes

GitHub Issues

To add a new change to the code, first open a new GitHub issue for tracking. Add details describing the feature request or bug and add appropriate tags. Assign the issue to the appropriate user and clear up any assumptions in the discussion before contributing any new code.

Branching

To start working on code changes, create a new branch off of the latest master branch:

git checkout master
git pull
git checkout -b <new-branch-name>

Give your branch a descriptive name relating to the feature or bug. Preferably, feature branches should be prefixed with feature- and branches for bug fixes should be prefixed with bugfix-.

Linting

The linter used for code styling and formatting in this project is pylint. We highly recommend installing and activating linting in your development enviornment:

• Guide for VSCode
• Guide for pycharm

Otherwise, you can run pylint as a command line program

Pull Requests

Once code changes are ready to be integrated into master, open a new pull request describing your code changes, and add repository owners as reviewers.

Once code changes are approved, merge changes into master using a squash commit

Release Process

sgRNAble is publicly available to install as a python package from PyPi repository through pip install.

To release a new version of sgRNAble:

1. Update the package version in setup.py file. Versioning scheme followed is [Major].[Minor].[patch] (ex. 1.0.1). Patch version is updated for fixes, minor version is updated for addition of minor features, and major version should only be updated for major changes in the package.
2. Install twine: pip install twine.
3. Create source archive and wheel for package: python setup.py sdist bdist_wheel. This should create two new files under a new dist directory
4. Check archive was created successfully: twine check dist/*. This will check the two new files and should output PASSED for both if the command ran successfully.
5. Upload package to PyPi: twine upload dist/*. This will prompt for a username and password, check with sgRNAble owners for access if required.
6. Check package was uploaded correctly to PyPi by checking version update, and running pip install sgrnable to install the latest version.

Documentation

Documentation is hosted on Github Wiki, and is maintained by repository owners. Ensure any changes to the project that require documentation changes are added to the wiki with the appropriate message.