贡献

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

您可以通过多种方式做出贡献:

Types of Contributions

报告错误

Report bugs at https://github.com/fantix/gino/issues.

如果您要报告错误，请包括：

  • 您的操作系统名称和版本。

  • 有关本地设置的任何详细信息都可能有助于排除故障。

  • 重现错误的详细步骤。

修复错误

在GitHub issues 查找错误。任何人都可以将标记为“bug”和“help wanted”并且是打开状态的问题修复。

实现功能

在GitHub issues 查找功能。任何人都可以将标记为“增强”和“需要帮助”的打开状态的需求实现。

写文档

GINO需要更多的使用文档，无论是作为官方GINO文档的一部分，还是文档字符串，甚至是博客，文章等等。

提交反馈

发送反馈的最佳方式是在https://github.com/fantix/gino/issues提交问题。

如果您要提出一项功能：

  • 详细解释它是如何工作的。

  • 为了更容易实现，请保持范围尽可能窄。

  • Remember that this is a volunteer-driven project, and that contributions are welcome :)

Get Started!

Ready to contribute? Here’s how to set up gino for local development.

  1. Fork the gino repo on GitHub.

  2. Clone your fork locally:

    1. $ git clone git@github.com:your_name_here/gino.git

  3. Create a branch for local development:

    1. $ cd gino/
    2. $ git checkout -b name-of-your-bugfix-or-feature

Now you can make your changes locally.

  1. Create virtual environment. Example for virtualenvwrapper:

    1. $ mkvirtualenv gino

  2. Activate the environment and install requirements:

    1. $ pip install -r requirements_dev.txt

  3. When you’re done making changes, check that your changes pass syntax checks:

    1. $ flake8 gino tests

7. And tests (including other Python versions with tox). For tests you you will need running database server (see “Tips” section below for configuration details):

  1. $ pytest tests
  2. $ tox

  1. For docs run:

    1. $ make docs

It will build and open up docs in your browser.

  1. Commit your changes and push your branch to GitHub:

    1. $ git add .
    2. $ git commit -m "Your detailed description of your changes."
    3. $ git push origin name-of-your-bugfix-or-feature

  2. Submit a pull request through the GitHub website.

Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:

  1. The pull request should include tests.

  2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.

  3. The pull request should work for Python 3.6. Check https://travis-ci.org/fantix/gino/pull_requests and make sure that the tests pass for all supported Python versions.

Tips

To run a subset of tests:

  1. $ py.test -svx tests.test_gino

By default the tests run against a default installed postgres database. If you wish to run against a separate database for the tests you can do this by first creating a new database and user using ‘psql’ or similar:

  1. CREATE ROLE gino WITH LOGIN ENCRYPTED PASSWORD 'gino';
  2. CREATE DATABASE gino WITH OWNER = gino;

Then run the tests like so:

  1. $ export DB_USER=gino DB_PASS=gino DB_NAME=gino
  2. $ py.test

Here is an example for db server in docker. Some tests require ssl so you will need to run postgres with ssl enabled. Terminal 1 (server):

  1. $ openssl req -new -text -passout pass:abcd -subj /CN=localhost -out server.req -keyout privkey.pem
  2. $ openssl rsa -in privkey.pem -passin pass:abcd -out server.key
  3. $ openssl req -x509 -in server.req -text -key server.key -out server.crt
  4. $ chmod 600 server.key
  5. $ docker run --name gino_db --rm -it -p 5433:5432 -v "$(pwd)/server.crt:/var/lib/postgresql/server.crt:ro" -v "$(pwd)/server.key:/var/lib/postgresql/server.key:ro" postgres:12-alpine -c ssl=on -c ssl_cert_file=/var/lib/postgresql/server.crt -c ssl_key_file=/var/lib/postgresql/server.key

Terminal 2 (client):

  1. $ export DB_USER=gino DB_PASS=gino DB_NAME=gino DB_PORT=5433
  2. $ docker exec gino_db psql -U postgres -c "CREATE ROLE $DB_USER WITH LOGIN ENCRYPTED PASSWORD '$DB_PASS'"
  3. $ docker exec gino_db psql -U postgres -c "CREATE DATABASE $DB_NAME WITH OWNER = $DB_USER;"
  4. $ pytest tests/test_aiohttp.py