How to Contribute¶
Overview¶
- Fork the repo.
- Build development environment run tests to ensure a clean, working slate.
- Improve/fix the code.
- Add test cases if new functionality introduced or bug fixed (100% test coverage).
- Ensure tests pass.
- Add yourself to
AUTHORS.rst
. - Push to your fork and submit a pull request to the
develop
branch.
Guidelines¶
Some simple guidelines to follow when contributing code:
- Adhere to PEP8.
- Clean, well documented code.
- All tests must pass.
- 100% test coverage.
Branching¶
There are two main development branches: master
and develop
. master
represents the currently released version while develop
is the latest development work. When submitting a pull request, be sure to submit to develop
. The originating branch you submit from can be any name though.
Continuous Integration¶
Integration testing is provided by Travis-CI at https://travis-ci.org/dgilland/alchy.
Test coverage reporting is provided by Coveralls at https://coveralls.io/r/dgilland/alchy.
Project CLI¶
Some useful CLI commands when working on the project are below. NOTE: All commands are run from the root of the project and require make
.
make clean¶
Remove build/test related temporary files like env/
, .tox
, .coverage
, and __pycache__
.
make clean
make test¶
Run unittests under the virtualenv’s default Python version. Does not test all support Python versions. To test all supported versions, see make test-full.
make test
make test-full¶
Run unittest and linting for all supported Python versions. NOTE: This will fail if you do not have all Python versions installed on your system. If you are on an Ubuntu based system, the Dead Snakes PPA is a good resource for easily installing multiple Python versions. If for whatever reason you’re unable to have all Python versions on your development machine, note that Travis-CI will run full integration tests on all pull requests.
make test-full
Areas of Needed Improvement¶
- Better documentation of functions/modules. Many are missing docstrings. Existing docstrings could be improved. Additional code comments may be needed as well.
- Improve code quality for readability (e.g. eliminate dense code statements like one-liners which do too much).
- Improve testing infrastructure.
- More battle testing. Tests currently cover basic usage, but there may be more complex uses-cases that could draw out some edge-case bugs.
- Potentially improve
Query
loading methods. The current implementation doesn’t handle nested loading options which differ than the base loading method used. For example, emulating thisquery.options(joinedload(Foo).lazyload(Bar))
is not supported while thisquery.options(joinedload(Foo).joinedload(Bar))
is viaquery.joinedload(Foo, Bar)
. Would be nice to have a way to drill down into the nested loading strategies without having to usequery.options
. However, if the solution introduces too much complexity for a feature that isn’t used/needed often, then it may be best to not attempt to support it.