Contributing¶
We'd love to see folks contribute! Below you will find instructions to:
- Set up the environment and pre-commit
- Run type checking and tests
- Develop DbDeclare
- Develop documentation
- Contribute via the Git workflow
Prerequisites¶
Python¶
Make sure you have the right version on your machine. You can install pyenv then use it to install the desired version if needed:
Please refer to the pyenv usage instructions for more information on that tool.
Database¶
You need a functioning database instance/cluster and drivers for the database you choose. DbDeclare currently only supports Postgres.
Postgres¶
An easy way to set up Postgres on your machine is to do so via Docker. Once you have it set up on your machine, you can pull the official Postgres image, run it locally, and port-forward it:
This will spin up a Postgres instance with the following properties:
- host:
127.0.0.1 - port:
5432 - admin username:
postgres - admin password:
postgres - default database name:
postgres
Note that if there is already something running on port 5432, this will fail. You need to stop whatever process is
running there, or change the port-forward statement to a different port (5433:5432 would forward to port 5433, for
example).
To "restart" the instance, you can simply ctrl-C and run the command again.
Setup¶
With prerequisites in place, we can start setting up the project for development.
Environment¶
We use Poetry to build, package, and publish the project. You can find installation instructions for Poetry here.
Once Poetry is installed, you can install the project and dependencies from the root directory:
You might run into an issue with psycopg installation. For development, we use the pure Python installation, which has some requirements. If you have trouble getting it to work, you can always use the binary installation instead.
Pre-commit¶
We use pre-commit for consistent code formatting. Our configuration includes other tools like black, isort, and flake8. Check out this blog post to learn more.
The configuration for pre-commit lives in the .pre-commit-config.yaml file, and the configuration for the other tools
exists in a combination of tox.ini and pyproject.toml.
Pre-commit is installed as a development dependency. To install the configuration in your local environment, run:
This will now run all the configured tools every time you attempt to commit your code. If there is a repeated failure, you will need to adjust your changes; the error messages are specific and helpful, they should guide you to the issue.
To run the tools manually, you can:
Develop DbDeclare¶
Type checks¶
We use mypy for type checking. We configure it in the pyproject.toml file.
You can run it on the default setting (which checks all files) by simply running mypy from the root of the project.
Running mypy is also the first step of the continuous integration (CI) process, so when you make a pull request, it
will be automatically type-checked. The type checking must succeed for the pull request to be accepted.
Tests¶
We use pytest for running tests. Some tests (most integration tests and some documentation tests) require a running Postgres instance with the following characteristics:
- host:
127.0.0.1 - port:
5432 - username:
postgres - password:
postgres - database name:
postgres
As mentioned earlier, an easy way to do this is via Docker:
Once that is running, in a seperate shell window, you can run:
You can use all the standard pytest syntax to specify tests. Some common specifications might be to only run
unit tests, integration tests, or documentation tests. These are split up by path, so you can run pytest tests/unit
to run all unit tests.
Running tests is also part of the CI process. When you make a pull request, all tests will run, and they must pass in order to be accepted.
Develop documentation¶
We use mkdocs specifically with the
material theme to build our documentation. The configuration for it
lives in mkdocs.yml, and the dependencies are specified in the docs group in the pyproject.toml
file. The markdown all resides in the docs directory, and the larger code examples used throughout are in docs_src.
Refer to the mkdocs documentation for more detail if needed, but to serve it
locally at localhost:8000, you can simply run:
Git flow¶
We follow a fairly standard git workflow that has been documented plenty of times elsewhere. Here is a great explanation of it.
Once a change is reviewed, approved, and merged, the maintainers will create a release and publish a new version of the package.