From e00eaa31a7ef924db6db0ed4af82555f61c9b595 Mon Sep 17 00:00:00 2001 From: Ashhar Hasan Date: Thu, 22 Sep 2022 23:40:48 +0530 Subject: [PATCH 1/6] Extract development notes to DEVELOPMENT.md --- .github/DEVELOPMENT.md | 88 ++++++++++++++++++++++++++++++++++++++ README.md | 97 +++--------------------------------------- 2 files changed, 94 insertions(+), 91 deletions(-) create mode 100644 .github/DEVELOPMENT.md diff --git a/.github/DEVELOPMENT.md b/.github/DEVELOPMENT.md new file mode 100644 index 00000000..6d848f8d --- /dev/null +++ b/.github/DEVELOPMENT.md @@ -0,0 +1,88 @@ +# Development + +## Getting started with development + +Start by forking the repository and then modify the code in your fork. + +We recommend that you use Python3's `venv` for development: + +``` +python3 -m venv .venv +. .venv/bin/activate +pip install -e '.[tests]' +``` + +With `-e` passed to `pip install` above pip can reference the code you are +modifying in the *virtual env*. That way, you do not need to run `pip install` +again to make your changes applied to the *virtual env*. + +When the code is ready, submit a Pull Request. + +### Code style + +- For Python code, adhere to PEP 8. +- Prefer code that is readable over one that is "clever". +- When writing a Git commit message, follow these [guidelines](https://chris.beams.io/posts/git-commit/). + +See also Trino's [guidelines](https://github.com/trinodb/trino/blob/master/.github/DEVELOPMENT.md). +Most of them also apply to code in trino-python-client. + +### Running tests + +`trino-python-client` uses [pytest](https://pytest.org/) for its tests. To run +only unit tests, type: + +``` +pytest tests/unit +``` + +Then you can pass options like `--pdb` or anything supported by `pytest --help`. + +To run integration tests: + +``` +pytest tests/integration +``` + +They pull a Docker image and then run a container with a Trino server: +- the image is named `trinodb/trino:${TRINO_VERSION}` +- the container is named `trino-python-client-tests-{uuid4()[:7]}` + +To run the tests with different versions of Python in managed *virtual envs*, +use `tox` (see the configuration in `tox.ini`): + +``` +tox +``` + +## Releasing + +- [Set up your development environment](#Getting-Started-With-Development). +- Check the local workspace is up to date and has no uncommitted changes + ```bash + git fetch -a && git status + ``` +- Change version in `trino/__init__.py` to a new version, e.g. `0.123.0`. +- Commit + ```bash + git commit -a -m "Bump version to 0.123.0" + ``` +- Create an annotated tag + ```bash + git tag -m "" 0.123.0 + ``` +- Create release package and upload it to PyPI + ```bash + . .venv/bin/activate && \ + pip install twine wheel setuptools && \ + rm -rf dist/ && \ + ./setup.py sdist bdist_wheel && \ + twine upload dist/* && \ + open https://pypi.org/project/trino/ && \ + echo "Released!" + ``` +- Push the branch and the tag + ```bash + git push upstream master 0.123.0 + ``` +- Send release announcement on the *#python-client* channel on [Trino Slack](https://trino.io/slack.html). diff --git a/README.md b/README.md index c6502885..ee990f78 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,11 @@ It supports Python>=3.7 and pypy. [![Trino Slack](https://img.shields.io/static/v1?logo=slack&logoColor=959DA5&label=Slack&labelColor=333a41&message=join%20conversation&color=3AC358)](https://trino.io/slack.html) [![Trino: The Definitive Guide book download](https://img.shields.io/badge/Trino%3A%20The%20Definitive%20Guide-download-brightgreen)](https://www.starburst.io/info/oreilly-trino-guide/) +## Development + +See [DEVELOPMENT](.github/DEVELOPMENT.md) for information about code style, +development process, and guidelines. + ## Usage ### The Python Database API (DBAPI) @@ -412,101 +417,11 @@ assert rows[0][0] == params assert cur.description[0][1] == "timestamp with time zone" ``` -# Development - -## Getting started with development - -Start by forking the repository and then modify the code in your fork. - -We recommend that you use Python3's `venv` for development: - -``` -$ python3 -m venv .venv -$ . .venv/bin/activate -$ pip install -e '.[tests]' -``` - -With `-e` passed to `pip install` above pip can reference the code you are -modifying in the *virtual env*. That way, you do not need to run `pip install` -again to make your changes applied to the *virtual env*. - -When the code is ready, submit a Pull Request. - -### Code style - -- For Python code, adhere to PEP 8. -- Prefer code that is readable over one that is "clever". -- When writing a Git commit message, follow these [guidelines](https://chris.beams.io/posts/git-commit/). - -See also Trino's [guidelines](https://github.com/trinodb/trino/blob/master/.github/DEVELOPMENT.md). -Most of them also apply to code in trino-python-client. - -### Running tests - -`trino-python-client` uses [pytest](https://pytest.org/) for its tests. To run -only unit tests, type: - -``` -$ pytest tests/unit -``` - -Then you can pass options like `--pdb` or anything supported by `pytest --help`. - -To run integration tests: - -``` -$ pytest tests/integration -``` - -They pull a Docker image and then run a container with a Trino server: -- the image is named `trinodb/trino:${TRINO_VERSION}` -- the container is named `trino-python-client-tests-{uuid4()[:7]}` - -To run the tests with different versions of Python in managed *virtual envs*, -use `tox` (see the configuration in `tox.ini`): - -``` -$ tox -``` - -## Releasing - -- [Set up your development environment](#Getting-Started-With-Development). -- Check the local workspace is up to date and has no uncommitted changes - ```bash - git fetch -a && git status - ``` -- Change version in `trino/__init__.py` to a new version, e.g. `0.123.0`. -- Commit - ```bash - git commit -a -m "Bump version to 0.123.0" - ``` -- Create an annotated tag - ```bash - git tag -m "" 0.123.0 - ``` -- Create release package and upload it to PyPI - ```bash - . .venv/bin/activate && \ - pip install twine wheel setuptools && \ - rm -rf dist/ && \ - ./setup.py sdist bdist_wheel && \ - twine upload dist/* && \ - open https://pypi.org/project/trino/ && \ - echo "Released!" - ``` -- Push the branch and the tag - ```bash - git push upstream master 0.123.0 - ``` -- Send release announcement on the *#python-client* channel on [Trino Slack][trino-slack]. - # Need help? Feel free to create an issue as it makes your request visible to other users and contributors. If an interactive discussion would be better or if you just want to hangout and chat about the Trino Python client, you can join us on the *#python-client* channel on -[Trino Slack][trino-slack]. +[Trino Slack](https://trino.io/slack.html). -[trino-slack]: https://trino.io/slack.html From f5f65ba161ef28f72bee2b26e73d61839084eea7 Mon Sep 17 00:00:00 2001 From: Ashhar Hasan Date: Thu, 22 Sep 2022 23:49:18 +0530 Subject: [PATCH 2/6] Inline relevant information from Trino's DEVELOPMENT.md Most of the information on Trino's DEVELOPMENT.md doesn't apply to Python and leads to confusion. --- .github/DEVELOPMENT.md | 74 ++++++++++++++++++++++++++++++++++-------- 1 file changed, 60 insertions(+), 14 deletions(-) diff --git a/.github/DEVELOPMENT.md b/.github/DEVELOPMENT.md index 6d848f8d..acd934b9 100644 --- a/.github/DEVELOPMENT.md +++ b/.github/DEVELOPMENT.md @@ -1,6 +1,15 @@ # Development -## Getting started with development +Developers should read [the development section of the website](https://trino.io/development), +which covers things like development philosophy and contribution process. + +* [Getting started](#getting-started) +* [Running tests](#running-tests) +* [Commits and pull requests](#commits-and-pull-requests) +* [Code style](#code-style) +* [Releasing](#releasing) + +## Getting started Start by forking the repository and then modify the code in your fork. @@ -16,18 +25,7 @@ With `-e` passed to `pip install` above pip can reference the code you are modifying in the *virtual env*. That way, you do not need to run `pip install` again to make your changes applied to the *virtual env*. -When the code is ready, submit a Pull Request. - -### Code style - -- For Python code, adhere to PEP 8. -- Prefer code that is readable over one that is "clever". -- When writing a Git commit message, follow these [guidelines](https://chris.beams.io/posts/git-commit/). - -See also Trino's [guidelines](https://github.com/trinodb/trino/blob/master/.github/DEVELOPMENT.md). -Most of them also apply to code in trino-python-client. - -### Running tests +## Running tests `trino-python-client` uses [pytest](https://pytest.org/) for its tests. To run only unit tests, type: @@ -55,9 +53,57 @@ use `tox` (see the configuration in `tox.ini`): tox ``` +When the code is ready, submit a Pull Request. + +## Commits and pull requests + +See [Commits and pull requests](https://github.com/trinodb/trino/blob/master/.github/DEVELOPMENT.md#commits-and-pull-requests) section from Trino. + +## Code style + +To run linting and formatting checks before opening a PR: `pip install pre-commit && pre-commit run --all-files` + +In addition to that you should also adhere to the following: + +### Readability + +Prefer code that is readable over one that is "clever". The purpose of code +style rules is to maintain code readability and developer efficiency when +working with the code. All the code style rules explained below are good +guidelines to follow but there may be exceptional situations where we +purposefully depart from them. When readability and code style rule are at +odds, the readability is more important. + +### Consistency + +Keep code consistent with surrounding code where possible. + +### Avoid mocks where possible + +Do not use mocking libraries. These libraries encourage testing specific call +sequences, interactions, and other internal behavior, which we believe leads to +fragile tests. They also make it possible to mock complex interfaces or +classes, which hides the fact that these classes are not (easily) testable. We +prefer to write mocks by hand, which forces code to be written in a certain +testable style. + +We also acknowledge that there is existing code which uses mocks but that +should not be taken as a reason increase reliance on mocks. + +### Maintain production quality for test code + +Maintain the same quality for production and test code. + +### Avoid abbreviations + +Please avoid abbreviations, slang or inside jokes as this makes harder for +non-native english speaker to understand the code. Very well known +abbreviations like `max` or `min` and ones already very commonly used across +the code base like `ttl` are allowed and encouraged. + ## Releasing -- [Set up your development environment](#Getting-Started-With-Development). +- [Set up your development environment](#getting-started). - Check the local workspace is up to date and has no uncommitted changes ```bash git fetch -a && git status From f80d3d9976d390692e84a2a490f0ac1ec8ff52b7 Mon Sep 17 00:00:00 2001 From: Ashhar Hasan Date: Thu, 22 Sep 2022 23:51:30 +0530 Subject: [PATCH 3/6] Add CONTRIBUTING.md --- .github/CONTRIBUTING.md | 9 +++++++++ README.md | 2 ++ 2 files changed, 11 insertions(+) create mode 100644 .github/CONTRIBUTING.md diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 00000000..ffa18048 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,9 @@ +# Contributing to Trino Python Client + +## Contributor License Agreement ("CLA") + +In order to accept your pull request, we need you to [submit a CLA](https://github.com/trinodb/cla). + +## License + +By contributing to Trino Python Client, you agree that your contributions will be licensed under the [Apache License Version 2.0 (APLv2)](../LICENSE). diff --git a/README.md b/README.md index ee990f78..05553467 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,8 @@ It supports Python>=3.7 and pypy. See [DEVELOPMENT](.github/DEVELOPMENT.md) for information about code style, development process, and guidelines. +See [CONTRIBUTING](.github/CONTRIBUTING.md) for contribution requirements. + ## Usage ### The Python Database API (DBAPI) From 7ad91bfee469fa6234c0a654419c77e81ffd15fe Mon Sep 17 00:00:00 2001 From: Ashhar Hasan Date: Thu, 22 Sep 2022 23:53:51 +0530 Subject: [PATCH 4/6] Clarify that docs-only changes don't need release notes --- .github/pull_request_template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 7be33de0..cbbb1694 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -12,7 +12,7 @@ ## Release notes -( ) This is not user-visible and no release notes are required. +( ) This is not user-visible or docs only and no release notes are required. ( ) Release notes are required, please propose a release note for me. ( ) Release notes are required, with the following suggested text: From 1b12fd6d35aa612bdfce0195fed7388fc14bdc39 Mon Sep 17 00:00:00 2001 From: Ashhar Hasan Date: Thu, 22 Sep 2022 23:58:25 +0530 Subject: [PATCH 5/6] Do not run CI for changes to markdown files --- .github/workflows/ci.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 33bca82b..09c24a69 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -5,6 +5,8 @@ on: branches: - "master" pull_request: + paths-ignore: + - '**.md' # Cancel previous PR builds. concurrency: From 4513be6ab97dc88f5f86da9489f5ffb727e7f6dc Mon Sep 17 00:00:00 2001 From: Ashhar Hasan Date: Mon, 3 Oct 2022 20:17:24 +0530 Subject: [PATCH 6/6] empty for ci