diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index aa1d825f..3ad7faf8 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -20,7 +20,7 @@ on: - '.github/**' - CHANGELOG.md - README.md - - CONTRIBUTING.rst + - CONTRIBUTING.md env: VERSION_FILE: setup.py diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 6afccd5f..869a042a 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -2,24 +2,20 @@ # See https://pre-commit.com/hooks.html for more hooks repos: - repo: https://github.com/pre-commit/pre-commit-hooks - rev: v3.4.0 + rev: v5.0.0 hooks: - id: trailing-whitespace - id: end-of-file-fixer - id: check-yaml - id: check-added-large-files - repo: https://github.com/PyCQA/pydocstyle - rev: 6.0.0 + rev: 6.3.0 hooks: - id: pydocstyle exclude: | (?x)^( tests/.* ) -- repo: https://github.com/Lucas-C/pre-commit-hooks-markup - rev: v1.0.1 - hooks: - - id: rst-linter - repo: https://github.com/pycqa/isort rev: 5.13.2 hooks: @@ -31,6 +27,6 @@ repos: - id: black args: ['reportportal_client', 'tests'] - repo: https://github.com/pycqa/flake8 - rev: 5.0.4 + rev: 7.1.1 hooks: - id: flake8 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..9903b3fc --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,136 @@ +# Contribution + +Contributions are highly welcomed and appreciated. + +## Contents + +- [Feature requests](#feature-requests) +- [Bug reports](#bug-reports) +- [Bug fixes](#bug-fixes) +- [Implement features](#implement-features) +- [Preparing Pull Requests](#preparing-pull-requests) + +## Feature requests + +We'd also like to hear about your thoughts and suggestions. Feel free to [submit them as issues](https://github.com/reportportal/client-Python/issues) and: + +* Explain in detail how they should work. +* Keep the scope as narrow as possible. It will make it easier to implement. + +## Bug reports + +Report bugs for the client in the [issue tracker](https://github.com/reportportal/client-Python/issues). + +If you are reporting a new bug, please include: + +* Your operating system name and version. +* Python interpreter version, installed libraries, and reportportal-client version. +* Detailed steps to reproduce the bug. + +## Bug fixes + +Look through the [GitHub issues for bugs](https://github.com/reportportal/client-Python/labels/bug). + +If you are going to fix any of the existing bugs, assign that bug to yourself and specify preliminary milestones. Talk to [contributors](https://github.com/reportportal/client-Python/graphs/contributors) in case you need consultancy regarding implementation. + +## Implement features + +Look through the [GitHub issues for enhancements](https://github.com/reportportal/client-Python/labels/enhancement). + +Talk to [contributors](https://github.com/reportportal/client-Python/graphs/contributors) in case you need consultancy regarding implementation. + +## Preparing Pull Requests + +What is a "pull request"? It informs the project's core developers about the changes you want to review and merge. Pull requests are stored on [GitHub servers](https://github.com/reportportal/client-Python/pulls). Once you send a pull request, we can discuss its potential modifications and even add more commits to it later on. There's an excellent tutorial on how Pull Requests work in the [GitHub Help Center](https://help.github.com/articles/using-pull-requests/). + +Here is a simple overview below: + +1. Fork the [reportportal-client GitHub repository](https://github.com/reportportal/client-Python). + +2. Clone your fork locally using [git](https://git-scm.com/) and create a branch: + + ```sh + $ git clone git@github.com:YOUR_GITHUB_USERNAME/client-Python.git + $ cd client-Python + # now, create your own branch off the "master": + $ git checkout -b your-bugfix-branch-name + ``` + + If you need some help with Git, follow this quick start guide: [https://git.wiki.kernel.org/index.php/QuickStart](https://git.wiki.kernel.org/index.php/QuickStart) + +3. Install [pre-commit](https://pre-commit.com) and its hook on the client-Python repo: + + **Note: pre-commit must be installed as admin, as it will not function otherwise**: + + ```sh + $ pip install --user pre-commit + $ pre-commit install + ``` + + Afterwards `pre-commit` will run whenever you commit. + + [https://pre-commit.com/](https://pre-commit.com/) is a framework for managing and maintaining multi-language pre-commit hooks to ensure code-style and code formatting is consistent. + +4. Install tox + + Tox is used to run all the tests and will automatically setup virtualenvs to run the tests in. (will implicitly use [http://www.virtualenv.org/en/latest/](http://www.virtualenv.org/en/latest/)): + + ```sh + $ pip install tox + ``` + +5. Run all the tests + + You need to have Python 3.10 available in your system. Now running tests is as simple as issuing this command: + + ```sh + $ tox -e pep,py310 + ``` + + This command will run tests via the "tox" tool against Python 3.10 and also perform code style checks. + +6. You can now edit your local working copy and run the tests again as necessary. Please follow PEP-8 recommendations. + + You can pass different options to `tox`. For example, to run tests on Python 3.10 and pass options to pytest (e.g. enter pdb on failure) to pytest you can do: + + ```sh + $ tox -e py310 -- --pdb + ``` + + Or to only run tests in a particular test module on Python 3.10: + + ```sh + $ tox -e py310 -- tests/test_service.py + ``` + + When committing, `pre-commit` will re-format the files if necessary. + +7. If instead of using `tox` you prefer to run the tests directly, then we suggest to create a virtual environment and use an editable install with the `testing` extra: + + ```sh + $ python3 -m venv .venv + $ source .venv/bin/activate # Linux + $ .venv/Scripts/activate.bat # Windows + $ pip install -e ".[testing]" + ``` + + Afterwards, you can edit the files and run pytest normally: + + ```sh + $ pytest tests/test_service.py + ``` + +8. Commit and push once your tests pass and you are happy with your change(s): + + ```sh + $ git commit -m "" + $ git push -u + ``` + +9. Finally, submit a pull request through the GitHub website using this data: + + head-fork: YOUR_GITHUB_USERNAME/client-Python + compare: your-branch-name + + base-fork: reportportal/client-Python + base: master diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst deleted file mode 100644 index 7c589701..00000000 --- a/CONTRIBUTING.rst +++ /dev/null @@ -1,145 +0,0 @@ -============ -Contribution -============ - -Contributions are highly welcomed and appreciated. - -.. contents:: - :depth: 2 - :backlinks: none - -Feature requests ----------------- - -We'd also like to hear about your thoughts and suggestions. Feel free to -`submit them as issues `_ and: - -* Explain in detail how they should work. -* Keep the scope as narrow as possible. It will make it easier to implement. - -Bug reports ------------ - -Report bugs for the client in the `issue tracker `_. - -If you are reporting a new bug, please include: - -* Your operating system name and version. -* Python interpreter version, installed libraries, and reportportal-client - version. -* Detailed steps to reproduce the bug. - -Bug fixes ---------- - -Look through the `GitHub issues for bugs `_. - -If you are gonna fix any of existing bugs, assign that bug to yourself and specify preliminary milestones. -Talk to `contributors `_ in case you need a -consultancy regarding implementation. - -Implement features ------------------- - -Look through the `GitHub issues for enhancements `_. - -Talk to `contributors `_ in case you need a -consultancy regarding implementation. - -Preparing Pull Requests ------------------------ - -What is a "pull request"? It informs the project's core developers about the -changes you want to review and merge. Pull requests are stored on -`GitHub servers `_. -Once you send a pull request, we can discuss its potential modifications and -even add more commits to it later on. There's an excellent tutorial on how Pull -Requests work in the -`GitHub Help Center `_. - -Here is a simple overview below: - -#. Fork the - `reportportal-client GitHub repository `_. - -#. Clone your fork locally using `git `_ and create a branch:: - - $ git clone git@github.com:YOUR_GITHUB_USERNAME/client-Python.git - $ cd client-Python - # now, create your own branch off the "master": - - $ git checkout -b your-bugfix-branch-name - - If you need some help with Git, follow this quick start - guide: https://git.wiki.kernel.org/index.php/QuickStart - -#. Install `pre-commit `_ and its hook on the client-Python repo: - - **Note: pre-commit must be installed as admin, as it will not function otherwise**:: - - $ pip install --user pre-commit - $ pre-commit install - - Afterwards ``pre-commit`` will run whenever you commit. - - https://pre-commit.com/ is a framework for managing and maintaining multi-language pre-commit hooks - to ensure code-style and code formatting is consistent. - -#. Install tox - - Tox is used to run all the tests and will automatically setup virtualenvs - to run the tests in. - (will implicitly use http://www.virtualenv.org/en/latest/):: - - $ pip install tox - -#. Run all the tests - - You need to have Python 3.6 available in your system. Now - running tests is as simple as issuing this command:: - - $ tox -e pep,py36 - - This command will run tests via the "tox" tool against Python 3.6 - and also perform code style checks. - -#. You can now edit your local working copy and run the tests again as necessary. Please follow PEP-8 recommendations. - - You can pass different options to ``tox``. For example, to run tests on Python 3.6 and pass options to pytest - (e.g. enter pdb on failure) to pytest you can do:: - - $ tox -e py36 -- --pdb - - Or to only run tests in a particular test module on Python 3.6:: - - $ tox -e py36 -- tests/test_service.py - - - When committing, ``pre-commit`` will re-format the files if necessary. - -#. If instead of using ``tox`` you prefer to run the tests directly, then we suggest to create a virtual environment and use - an editable install with the ``testing`` extra:: - - $ python3 -m venv .venv - $ source .venv/bin/activate # Linux - $ .venv/Scripts/activate.bat # Windows - $ pip install -e ".[testing]" - - Afterwards, you can edit the files and run pytest normally:: - - $ pytest tests/test_service.py - - -#. Commit and push once your tests pass and you are happy with your change(s):: - - $ git commit -m "" - $ git push -u - - -#. Finally, submit a pull request through the GitHub website using this data:: - - head-fork: YOUR_GITHUB_USERNAME/client-Python - compare: your-branch-name - - base-fork: reportportal/client-Python - base: master