Development
Hopefully you have landed here because you would like to help out with the development of Beanie. Whether through adding new features, fixing bugs, or extending documentation, your help is really appreciated! Please read this page carefully. If you have any questions, drop by on the discord.
Also please read the Code of conduct.
Setting up the development environment
We assume you are familiar with the general forking and pull request workflow for submitting to open-source projects. If not, don't worry, there are plenty of good guides available, maybe check out this one.
Beanie uses poetry to manage dependencies and packaging. If you are not familiar with poetry, it might be usefully to read up on it before working on Beanie, but here is a quick guide to get you started.
Ensure poetry is installed globally:
pip install --user poetry
To install all required dependencies in a virtual informant, run the following command in the root of the Beanie project
poetry install
To add a dependency you can use
poetry add <package name>
-D flag for development only dependencies.
To run commands like pytest or black you have to run them using the virtual environment which contains the dependencies and Beanie. You can do this in two ways, you may run poetry shell to activate the environment for the current shell, or you can run them in a one-off fashion as such poetry run pytest.
Database connection
To run tests, and use Beanie in general, you will need an accessible MongoDB database. To use migrations you will need a connection to a Replica Set or Mongos instance. All tests assume that the database is hosted localy on port 27017 and does not require authentication.
Testing
Beanie uses pytest for unit testing. To ensure the stability of Beanie, each added feature must be tested in a separate unit test. Even if it looks like other tests are covering it now. This strategy guarantees that:
- All the features will be covered and stay covered.
- Independence from other features and test cases.
To run the test suit, make sure that you have mongodb running and run poetry run pytest.
Submitting new code
You can submit your changes through a pull request on github. Please take into account the following secitons.
Use pre-commit
To ensure code consistency Beanie uses Black and Flake8 through pre-commit. To set it up, run:
poetry install
poetry run pre-commit install
This will add the pre-commit command to your git's pre-commit hooks and makes sure you can never forget to run these.
Single commit
To make the pull request reviewing easier and keep the version tree clean your pull request should consist of a single commit. It is natural that your branch might contain multiple commits, so you will need to squash these into a single commit. Instructions can be found here or here
Add documentation
Please write clear documentation for any new functionallity you add. Docstrings will be converted to the API documentation, but more human friendly documentation might also be needed! See the section below.
Working on the documentation
The documentation is generated using pydoc-markdown. To see a preview of any edits you make you can run
poetry run pydoc-markdown --server
localhost:8000) in your browser. Beware, the autorecompiling might not work for everyone.
This will automatically generate the API documentation from source. All other documentation should be written by hand. The documentation is compiled using mkdocs behind the scenes. To change the table of contents or other options, check out pydoc-markdown.yml.