Merge pull request #258 from iivanou/update_contribution

Update contribution guidelines

Author: Dmitriy Gumeniuk

CONTRIBUTING.rst

@@ -1,90 +1,146 @@
 ============
-Contributing
+Contribution
 ============
 
-Contributions are welcome, and they are greatly appreciated! Every
-little bit helps, and credit will always be given.
+Contributions are highly welcomed and appreciated.
 
-You can contribute in many ways:
+.. contents::
+   :depth: 2
+   :backlinks: none
 
-Types of Contributions
-----------------------
+Feature requests
+----------------
 
-Report Bugs
-~~~~~~~~~~~
+We'd also like to hear about your thoughts and suggestions.  Feel free to
+`submit them as issues <hhttps://github.com/reportportal/agent-python-pytest/issues>`_ and:
 
-Report bugs at https://github.com/reportportal/agent-python-pytest/issues.
+* Explain in detail how they should work.
+* Keep the scope as narrow as possible. It will make it easier to implement.
 
-If you are reporting a bug, please include:
+Bug reports
+-----------
+
+Report bugs for the agent in the `issue tracker <https://github.com/reportportal/agent-python-pytest/issues>`_.
+
+If you are reporting a new bug, please include:
 
 * Your operating system name and version.
-* Any details about your local setup that might be helpful in troubleshooting.
+* Python interpreter version, installed libraries, reportportal-client, and agent-python-pytest
+  version.
 * Detailed steps to reproduce the bug.
 
-Fix Bugs
-~~~~~~~~
+Bug fixes
+---------
+
+Look through the `GitHub issues for bugs <https://github.com/reportportal/agent-python-pytest/labels/bug>`_.
+
+If you are gonna fix any of existing bugs, assign that bug to yourself and specify preliminary milestones.
+Talk to `contributors <https://github.com/reportportal/agent-python-pytest/graphs/contributors>`_ in case you need a
+consultancy regarding implementation.
+
+Implement features
+------------------
+
+Look through the `GitHub issues for enhancements <https://github.com/reportportal/agent-python-pytest/labels/enhancement>`_.
+
+Talk to `contributors <https://github.com/reportportal/agent-python-pytest/graphs/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 <https://github.com/reportportal/agent-python-pytest/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:
+
+#. Fork the
+   `agent-python-pytest GitHub repository <https://github.com/reportportal/agent-python-pytest>`_.
+
+#. Clone your fork locally using `git <https://git-scm.com/>`_ and create a branch::
+
+    $ git clone [email protected]:YOUR_GITHUB_USERNAME/agent-python-pytest.git
+    $ cd agent-python-pytest
+    # 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 <https://pre-commit.com>`_ and its hook on the agent-python-pytest 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
 
-Look through the GitHub issues for bugs. Anything tagged with "bug"
-and "help wanted" is open to whoever wants to implement it.
+   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/)::
 
-Implement Features
-~~~~~~~~~~~~~~~~~~
+    $ pip install tox
 
-Look through the GitHub issues for features. Anything tagged with "enhancement"
-and "help wanted" is open to whoever wants to implement it.
+#. Run all the tests
 
-Write Documentation
-~~~~~~~~~~~~~~~~~~~
+   You need to have Python 3.6 available in your system.  Now
+   running tests is as simple as issuing this command::
 
-agent-python-pytest could always use more documentation, whether as part of the
-official agent-python-pytest docs, in docstrings, or even on the web in blog posts,
-articles, and such.
+    $ tox -e pep,py36
 
-Submit Feedback
-~~~~~~~~~~~~~~~
+   This command will run tests via the "tox" tool against Python 3.6
+   and also perform code style checks.
 
-The best way to send feedback is to file an issue at https://github.com/reportportal/agent-python-pytest/issues.
+#. You can now edit your local working copy and run the tests again as necessary. Please follow PEP-8 recommendations.
 
-If you are proposing a feature:
+   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::
 
-* Explain in detail how it would work.
-* Keep the scope as narrow as possible, to make it easier to implement.
-* Remember that this is a volunteer-driven project, and that contributions
-  are welcome :)
+    $ tox -e py36 -- --pdb
 
-Get Started!
-------------
+   Or to only run tests in a particular test module on Python 3.6::
 
-Ready to contribute? Here's how to set up `agent-python-pytest` for local development.
+    $ tox -e py36 -- tests/test_service.py
 
-1. Fork the `agent-python-pytest` repo on GitHub.
-2. Clone your fork locally::
 
-    $ git clone [email protected]:your_name_here/agent-python-pytest
+   When committing, ``pre-commit`` will re-format the files if necessary.
 
-3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development::
+#. 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::
 
-    $ mkvirtualenv agent_python_pytest
-    $ cd agent_python_pytest/
-    $ python setup.py develop
+       $ python3 -m venv .venv
+       $ source .venv/bin/activate  # Linux
+       $ .venv/Scripts/activate.bat  # Windows
+       $ pip install -e ".[testing]"
 
-4. Create a branch for local development::
+   Afterwards, you can edit the files and run pytest normally::
 
-    $ git checkout -b name-of-your-bugfix-or-feature
+       $ pytest tests/test_service.py
 
-   Now you can make your changes locally.
 
-5. When you're done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox::
+#. Commit and push once your tests pass and you are happy with your change(s)::
 
-    $ flake8 agent_python_pytest tests
-    $ tox
+    $ git commit -m "<commit message>"
+    $ git push -u
 
-   To get flake8 and tox, just pip install them into your virtualenv.
 
-6. Commit your changes and push your branch to GitHub::
+#. Finally, submit a pull request through the GitHub website using this data::
 
-    $ git add .
-    $ git commit -m "Your detailed description of your changes."
-    $ git push origin name-of-your-bugfix-or-feature
+    head-fork: YOUR_GITHUB_USERNAME/agent-python-pytest
+    compare: your-branch-name
 
-7. Submit a pull request through the GitHub website.
+    base-fork: reportportal/agent-python-pytest
+    base: master

README.rst

@@ -43,6 +43,7 @@ Contribution
 All the fixes for the agent that supports Report Portal versions below 5.0.0 should go into the v1 branch.
 The master branch will store the code base for the agent for Report Portal versions 5 and above.
 
+Look through the CONTRIBUTING.rst for contribution guidelines.
 
 Configuration
 ~~~~~~~~~~~~~

pyproject.toml

@@ -0,0 +1,8 @@
+[build-system]
+requires = [
+  # sync with setup.py until we discard non-pep-517/518
+  "setuptools>=40.0",
+  "setuptools-scm",
+  "wheel",
+]
+build-backend = "setuptools.build_meta"

setup.py

@@ -9,11 +9,10 @@
 
 
 def read_file(fname):
-    """
-    Read file.
+    """Read the given file.
 
-    :param fname: string of filename
-    :return: File descriptor
+    :param fname: Filename to be read
+    :return:      File content
     """
     with open(os.path.join(os.path.dirname(__file__), fname)) as f:
         return f.read()
@@ -43,10 +42,5 @@ def read_file(fname):
         'pytest11': [
             'pytest_reportportal = pytest_reportportal.plugin',
         ]
-    },
-    setup_requires=['pytest-runner'],
-    tests_require=[
-        'pytest',
-        'delayed-assert'
-    ]
+    }
 )

tox.ini

@@ -0,0 +1,36 @@
+[tox]
+isolated_build = True
+envlist =
+    pep
+    py27
+    py35
+    py36
+    py37
+    py38
+
+[testenv]
+deps =
+    pytest
+    pytest-cov
+    delayed-assert
+commands = pytest --cov=pytest_reportportal --cov-report=xml tests/ -s -vv
+
+[testenv:pep]
+skip_install = True
+deps = pre-commit>=1.11.0
+commands = pre-commit run --all-files --show-diff-on-failure
+
+[testenv:py27]
+deps =
+    mock
+    pytest
+    pytest-cov
+    delayed-assert
+
+[gh-actions]
+python =
+    2.7: py27
+    3.5: py35
+    3.6: pep, py36
+    3.7: py37
+    3.8: py38