How to contribute to the DEA
Thank you for considering contributing to the DEA!
Support questions
Please don’t use the issue tracker for this. The issue tracker is a tool to address bugs and feature requests. Please just contact me directly:
Via Mail: rpolzin@ukaachen.de
On Keybase: https://keybase.io/deastiny
Ask on our GitHub Discussions for long term discussion or larger questions.
Reporting issues
Include the following information in your post:
Describe what you expected to happen.
If possible, include a minimal reproducible example to help us identify the issue. This also helps check that the issue is not with your own code.
Describe what actually happened. Include the full traceback if there was an exception.
List your Python and Package versions. If possible, check if this issue is already fixed in the latest releases or the latest code in the repository.
Submitting patches
If there is not an open issue for what you want to submit, prefer opening one for discussion before working on a PR. You can work on any issue that doesn’t have an open PR linked to it or a maintainer assigned to it. These show up in the sidebar. No need to ask if you can work on an issue that interests you.
Include the following in your patch:
Use Black to format your code.
Include tests if your patch adds or changes code. Make sure the test fails without your patch.
Update any relevant docs pages and docstrings.
Add an entry in
CHANGES.rst
. Use the same style as other entries. Also include.. versionchanged::
inline changelogs in relevant docstrings.
First time setup in your local environment
Make sure you have a GitHub account.
Download and install the latest version of git.
Configure git with your username and email.
$ git config --global user.name 'your name' $ git config --global user.email 'your email'
Fork DEA to your GitHub account by clicking the Fork button.
Clone your fork locally, replacing
your-username
in the command below with your actual username.$ git clone https://github.com/your-username/dea $ cd flask
Create a conda environment and activate it.
$ conda create --name dea --file requirements.txt $ conda activate dea
Start coding
Create a branch to identify the issue you would like to work on. If you’re submitting a bug or documentation fix, branch off of the latest “.x” branch.
$ git fetch origin $ git checkout -b your-branch-name origin/2.0.x
If you’re submitting a feature addition or change, branch off of the “main” branch.
$ git fetch origin $ git checkout -b your-branch-name origin/main
Using your favorite editor, make your changes, committing as you go.
Include tests that cover any code changes you make. Make sure the test fails without your patch. Run the tests as described below.
Push your commits to your fork on GitHub and create a pull request. Link to the issue being addressed with
fixes #123
in the pull request description.$ git push --set-upstream origin your-branch-name
Running the tests
Run the basic test suite with pytest.
$ pytest
This runs the tests for the current environment, which is usually sufficient. CI will run the full suite when you submit your pull request.
Running test coverage
Generating a report of lines that do not have test coverage can indicate
where to start contributing. Run pytest
using coverage
and
generate a report.
$ pip install coverage
$ coverage run -m pytest
$ coverage html
Open htmlcov/index.html
in your browser to explore the report.
Read more about coverage.
Building the docs
Build the docs in the docs
directory using Sphinx.
$ cd docs
$ make html
Open _build/html/index.html
in your browser to view the docs.
Read more about Sphinx.