Add contributing docs (#453)

* add support for local tests in docker

* update docs

* move win support to separate PR

* remove docker file, update contributing docs

* clean scripts

* Update docs/contributing.md

Co-authored-by: Eric Jolibois <[email protected]>

* Update docs/contributing.md

Co-authored-by: Eric Jolibois <[email protected]>

* remove python version from venv, clarify that docs serve the live docs

Co-authored-by: Eric Jolibois <[email protected]>

Author: collerek

.gitignore

@@ -1,4 +1,5 @@
 .vscode/
+.idea/
 *.pyc
 test.db
 .coverage

docs/contributing.md

@@ -0,0 +1,116 @@
+# Contibuting
+
+All contributions to *databases* are welcome!
+
+## Issues
+
+To make it as simple as possible for us to help you, please include the following:
+
+* OS 
+* python version
+* databases version
+* database backend (mysql, sqlite or postgresql)
+* database driver (aiopg, aiomysql etc.)
+
+Please try to always include the above unless you're unable to install *databases* or **know** it's not relevant
+to your question or feature request.
+
+## Pull Requests
+
+It should be quite straight forward to get started and create a Pull Request.
+
+!!! note
+    Unless your change is trivial (typo, docs tweak etc.), please create an issue to discuss the change before
+    creating a pull request.
+
+To make contributing as easy and fast as possible, you'll want to run tests and linting locally. 
+
+You'll need to have **python >= 3.6 (recommended 3.7+)** and **git** installed.
+
+## Getting started
+
+1. Clone your fork and cd into the repo directory
+```bash
+git clone [email protected]:<your username>/databases.git
+cd databases
+```
+
+2. Create and activate virtual env
+```bash
+virtualenv env
+source env/bin/activate
+```
+
+3. Install databases, dependencies and test dependencies
+```bash
+pip install -r requirements.txt
+```
+
+4. Checkout a new branch and make your changes
+```bash
+git checkout -b my-new-feature-branch
+```
+
+## Make your changes...
+
+## Contribute
+
+1. Formatting and linting - databases uses black for formatting, autoflake for linting and mypy for type hints check
+run all of those with lint script
+```bash
+./scripts/lint
+```
+
+2. Prepare tests (basic)
+   1. Set-up `TEST_DATABASE_URLS` env variable where you can comma separate urls for several backends
+   2. The simples one is for sqlite alone: `sqlite:///test.db`
+
+3. Prepare tests (all backends)
+   1. In order to run all backends you need either a docker installation on your system or all supported backends servers installed on your local machine.
+   2. A sample docker configuration that reflects the CI/CD workflow of databases might be:
+   
+   ```dockerfile
+    version: '2.1'
+    services:
+      postgres:
+        image: postgres:10.8
+        environment:
+          POSTGRES_USER: username
+          POSTGRES_PASSWORD: password
+          POSTGRES_DB: testsuite
+        ports:
+          - 5432:5432
+    
+      mysql:
+        image: mysql:5.7
+        environment:
+          MYSQL_USER: username
+          MYSQL_PASSWORD: password
+          MYSQL_ROOT_PASSWORD: password
+          MYSQL_DATABASE: testsuite
+        ports:
+          - 3306:3306
+   ```
+   3. To test all backends, the test urls need to consist of all possible drivers too, so a sample might look like following:
+   ```text
+    sqlite:///test.db,
+    sqlite+aiosqlite:///test.db,
+    mysql+aiomysql://username:password@localhost:3306/testsuite,
+    mysql+asyncmy://username:password@localhost:3306/testsuite,
+    postgresql+aiopg://username:[email protected]:5432/testsuite,
+    postgresql+asyncpg://username:password@localhost:5432/testsuite
+   ```
+
+4. Run tests
+```bash
+./scripts/test
+```
+
+5. Build documentation
+   1. If you have changed the documentation make sure it runs successfully. 
+   You can preview the live documentation by running the following command:
+```bash
+./scripts/docs
+```
+
+6. Commit, push, and create your pull request

mkdocs.yml

@@ -13,6 +13,7 @@ nav:
     - Database Queries: 'database_queries.md'
     - Connections & Transactions: 'connections_and_transactions.md'
     - Tests & Migrations: 'tests_and_migrations.md'
+    - Contributing: 'contributing.md'
 
 markdown_extensions:
   - mkautodoc

scripts/test

@@ -5,19 +5,20 @@ if [ -d 'venv' ] ; then
     export PREFIX="venv/bin/"
 fi
 
-if [ -z "$TEST_DATABASE_URLS" ] ; then
-    echo "Variable TEST_DATABASE_URLS must be set."
-    exit 1
+if [ -z "$TEST_DATABASE_URLS" ]; then
+  echo "Variable TEST_DATABASE_URLS must be set."
+  exit 1
 fi
 
 set -ex
 
 if [ -z $GITHUB_ACTIONS ]; then
-    scripts/check
+  scripts/check
 fi
 
 ${PREFIX}coverage run -m pytest $@
 
 if [ -z $GITHUB_ACTIONS ]; then
-    scripts/coverage
+  scripts/coverage
 fi
+

tests/test_databases.py

@@ -23,7 +23,7 @@ def mysql_versions(wrapped_func):
     """
 
     @functools.wraps(wrapped_func)
-    def check(*args, **kwargs):
+    def check(*args, **kwargs):  # pragma: no cover
         url = DatabaseURL(kwargs["database_url"])
         if url.scheme in ["mysql", "mysql+aiomysql"] and sys.version_info >= (3, 10):
             pytest.skip("aiomysql supports python 3.9 and lower")