How to contribute?

How to contribute?#

The first step to a contribution is to set up a local development environment. Below are the steps and additional information that will get you from your idea to a code contribution, adding tests, and finally opening a pull request to the main stable code branch.

Local Development Setup#

Fork the snowexsql repo on to your GitHub account.

Here the official GitHub docs on how to do this
Clone your fork locally

Attention

Make sure to replace your_name_here with your GitHub user name
```
$ git clone git@github.com:your_name_here/snowexsql.git
$ cd snowexsql/
```
Install your local copy into a virtualenv.

Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:
```
$ mkvirtualenv snowexsql
```
Important

Below command should be executed inside the cloned repository from the step above.
```
$ python setup.py develop
```
If you are planning on running the tests or building the docs below also run:
```
$ pip install -e ".[docs]"
```
Create a branch for local development

We recommend using the GitHub flow workflow that is used in many open-source projects for editing an existing code base.
```
$ git checkout -b name-of-your-bugfix-or-feature
```
Start editing the code and implement your idea.
You completed your changes

When you’re done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox. Also note the setup steps below to set up a test database .
```
$ pytest
```

Commit your changes and push your branch to GitHub

$ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature

Submit a pull request through the GitHub website.

If you haven’t done this before - have a look at the official GitHub documentation on how to do this.

Tests#

Running the test suite requires a locally running database and providing the credentials to connect to it. Setting up an instance can be done via the supplied Docker compose file (see steps below).

Setting up DB credentials#

Copy the supplied sample file locally in a terminal

mv tests/credentials.json.sample tests/credentials.json

The file contains the username and password for connecting to the DB within the Docker container.

Docker commands#

After installing Docker, you can start up a ready to go database instance.

Start a database#

$ docker-compose up -d

Stop a database#

When you are finished testing, make sure to turn the docker off

$ docker-compose down

Running the test suite#

Quickly test your installation by running:

$ python3 -m pytest tests/

Testing the code coverage#

The goal of this project is to have high fidelity in data interpretation/submission to the database. To see the current test coverage run:

$ make coverage

Tips#

To run a subset of tests:

$ pytest tests.test_snowexsql

Pull Request Guidelines#

Before you submit a pull request, check that it meets these guidelines:

The pull request should include tests.
If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring.
The pull request should work for Python 3.5, 3.6, 3.7 and 3.8, and for PyPy. Check .. SnowEx/snowexsql and make sure that the tests pass for all supported Python versions.

Deploying#

A reminder for the maintainers on how to deploy. Make sure all your changes are committed. Then, in Github,

Draft a new release SnowEx/snowexsql
Create a new tag in the style of v0.x.x
Set release title to snowexsql v<version>
Enter release notes
Check that the action has released successfully

$ bump2version patch # possible: major / minor / patch $ git push $ git push –tags

Once the tag is merged, a release can be published with .. SnowEx/snowexsql The release name should follow the convention snowexsql-v0.4.1