Contributing¶

We welcome all contributions to doex both large and small. We encourage you to join our community.

Our Community Values¶

We are an open and friendly community. Everybody is welcome.

We encourage friendly discussions and respect for all. There are no exceptions.

All contributions are equally important. Documentation, answering questions, and fixing bugs are equally as valuable as adding new features.

Please read our entire code of conduct here. Also, check out the for the Python code of conduct.

Setting up Your Development Environment¶

Following these instructions should give you an efficient path to opening your first pull-request.

Cloning the doex Repository¶

Fork the repository to your local Github account. Clone this repository to your local development machine.

git clone https://github.com/<your_account>/doex
cd doex

Install an Editable Version¶

Use you favorite editor environment, here’s an example for venv:

python3 -m venv dev
source dev/bin/activate

Install doex using:

pip install -e '.[dev]'

Note: When you are finished you can use source deactivate to go back to your base environment.

Running Tests Locally¶

If you are contributing with documentation please jump to building documentation.

We need to install the development package before we can run the tests. If anything is confusing below, always resort to the relevant documentation.

For the most basic test runs against python 3.6 use this tox subset (callable after pip install tox):

tox -e py36

This will just execute the unittests against python 3.6 in a new virtual env. The first run will take longer to setup the virtualenv, but will be fast after that point.

For a full test suite of all envs and linting checks simply run tox without any arguments

tox

This will require python3.5, python3.6, python3.7, and python 3.8 to be installed.

Alternavitely pytest can be used if you have an environment already setup which works or has custom packages not present in the tox build.

pytest

Now there should be a working and editable installation of doex to start making your own contributions.

Building Documentation¶

The documentation is built using the Sphinx engine. To contribute, edit the RestructuredText (.rst) files in the docs directory to make changes and additions.

Once you are done editing, to generate the documentation, use tox and the following command from the root directory of the repository:

tox -e docs

This will generate .html files in the /.tox/docs_out/ directory. Once you are satisfied, feel free to jump to the next section.

Raise a pull request¶

The general workflow for this will be:

Run local tests
Pushed changes to your forked repository
Open pull request to main repository

Run Tests Locally¶

tox

Note that the manifest test reads the MANIFEST.in file and explicitly specify the files to include in the source distribution. You can read more about how this works here.

Push Changes to Forked Repo¶

Your commits should be pushed to the forked repository. To verify this type

git remote -v

and ensure the remotes point to your GitHub. Don’t work on the master branch!

Commit changes to local repository:

git checkout -b my-feature
git add <updated_files>
git commit

Push changes to your remote repository:
```
git push -u origin my-feature
```

Create Pull Request¶

Follow these instrucutions to create a pull request from a forked repository. If you are submitting a bug-fix for a specific issue make sure to reference the issue in the pull request.

There are good references to the Git documentation and Git workflows for more information if any of this is unfamiliar.

Note: You might want to set a reference to the main repository to fetch/merge from there instead of your forked repository. You can do that using:

git remote add upstream https://github.com/rohitsanj/doex

It’s possible you will have conflicts between your repository and master. Here, master is meant to be synchronized with the upstream repository. GitHub has some good documentation on merging pull requests from the command line.

Happy hacking on doex!