From cc28398a5d370137b91ed02b9d7dd18a90f37de1 Mon Sep 17 00:00:00 2001 From: Nicco Kunzmann Date: Thu, 23 Jun 2022 11:21:57 +0000 Subject: [PATCH 1/6] link the Installation Section where people look for contributing --- CONTRIBUTING.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 66e28eb9..37e0bc63 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -21,3 +21,11 @@ For pull requests, keep this in mind - Describe your change in CHANGES.rst - Add yourself to the docs/credits.rst + +Development Setup +----------------- + +If you would like to setup icalendar to +contribute changes, the `Installation Section +`_ +should help you further. From 87ef213ffb7dbed34e4836ee01c3de2b3dd98b18 Mon Sep 17 00:00:00 2001 From: Nicco Kunzmann Date: Thu, 23 Jun 2022 11:51:37 +0000 Subject: [PATCH 2/6] add documentation on development setup --- docs/install.rst | 68 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) diff --git a/docs/install.rst b/docs/install.rst index 8556b05e..bf3517d5 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -10,6 +10,74 @@ package, like this:: >>> import icalendar +Development Setup +----------------- + +To start contributing changes to icalendar, +you can clone the project to your file system +using Git. +You can `fork `_ +the project first and clone your fork, too. + +.. code-block:: bash + + git clone https://github.com/collective/icalendar.git + cd icalendar + +Installing Python +----------------- + +You will need a version of Python installed to run the tests +and execute the code. +The latest version of Python 3 should work and will be enough +to get you started. +If you like to run the tests with different Python versions, +the following setup proecess should work the same. + +Install Virtualenv +------------------ + +First, install ``virtualenv`` and create a virtual Python +environment. + +.. code-block:: bash + + pip install virtualenv + virtualenv -p python3 virtualenv-3 + +Now, you need to execute the following each time you +open a new command line to activate this specific environment. + +.. code-block:: bash + + source virtualenv-3/bin/activate + +If for some reason you cannot install ``vitualenv``, you can +go ahead with the following section using your +installed version of Python and ``pip``. + +Install Dependencies +-------------------- + +You can install the local copy of ``icalendar`` with ``pip``. + +.. code-block:: bash + + cd icalendar + python -m pip install -e . + +This installs the module and dependencies in your +Python environment so that you can access local changes. + +Try it out: + +.. code-block:: python + + Python 3.9.5 (default, Nov 23 2021, 15:27:38) + Type "help", "copyright", "credits" or "license" for more information. + >>> import icalendar + >>> icalendar.__version__ + '4.0.10.dev0' Building the documentation locally ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 10ebdbcd76e139387e326a0c3443104f51216eaf Mon Sep 17 00:00:00 2001 From: Nicco Kunzmann Date: Thu, 23 Jun 2022 12:00:08 +0000 Subject: [PATCH 3/6] describe doumentation changes in the changelog --- CHANGES.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CHANGES.rst b/CHANGES.rst index 00ad5176..3eb3b2cb 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -17,7 +17,9 @@ Breaking changes: New features: -- *add item here* +- Document development setup + Ref: #358 + [niccokunzmann] Bug fixes: From 5ca1f152460925c42d2f8bac48a519690424097d Mon Sep 17 00:00:00 2001 From: Nicco Kunzmann Date: Thu, 23 Jun 2022 12:00:22 +0000 Subject: [PATCH 4/6] link niccokunzmann in credits --- docs/credits.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/credits.rst b/docs/credits.rst index 420af8d4..3086e6e9 100644 --- a/docs/credits.rst +++ b/docs/credits.rst @@ -56,6 +56,7 @@ icalendar contributors - Clive Stevens - Dalton Durst - Kamil Mańkowski +- `Nicco Kunzmann `_ Find out who contributed:: From 3b66cb45e1a8c979bd6a1cc5359af8f5766965af Mon Sep 17 00:00:00 2001 From: Nicco Kunzmann Date: Sun, 7 Aug 2022 22:57:35 +0100 Subject: [PATCH 5/6] merge master into tox this also removes the unsupported/untested Python versions --- tox.ini | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/tox.ini b/tox.ini index 5ca22932..688d2c5f 100644 --- a/tox.ini +++ b/tox.ini @@ -1,16 +1,15 @@ # to run for a specific environment, use ``tox -e ENVNAME`` [tox] -envlist = py27,py36,py37,py38,py39,py310,pypy3 +envlist = py27,py37,py38,py39,py310,pypy3 [testenv] +usedevelop=True deps = pytest coverage - py{27,36}: hypothesis>=3.0 -extras = - test + py{27}: hypothesis>=3.0 commands = coverage run --source=src/icalendar --omit=*/tests/* --module pytest [] - py{27,36}: coverage run --append --source=src/icalendar --omit=*/tests/* --module pytest [] src/icalendar/tests/hypothesis/ + py{27}: coverage run --append --source=src/icalendar --omit=*/tests/* --module pytest [] src/icalendar/tests/hypothesis/ coverage report coverage html From 4a0998281005f3311e6ce8ff99ce605a05577423 Mon Sep 17 00:00:00 2001 From: Nicco Kunzmann Date: Thu, 23 Jun 2022 16:29:33 +0000 Subject: [PATCH 6/6] describe how to use tox instead of virtualenv --- docs/install.rst | 66 +++++++++++++++++++++++++++++++++++------------- 1 file changed, 49 insertions(+), 17 deletions(-) diff --git a/docs/install.rst b/docs/install.rst index bf3517d5..8c8b1c7a 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -34,32 +34,64 @@ to get you started. If you like to run the tests with different Python versions, the following setup proecess should work the same. -Install Virtualenv ------------------- +Install Tox +----------- -First, install ``virtualenv`` and create a virtual Python -environment. +First, install `tox `_.. .. code-block:: bash - pip install virtualenv - virtualenv -p python3 virtualenv-3 + pip install tox -Now, you need to execute the following each time you -open a new command line to activate this specific environment. +From now on, tox will manage Python versions and +test commands for you. + +Running Tests +------------- + +``tox`` manages all test environments in all Python versions. + +To run all tests in all environments, simply run ``tox`` + +.. code-block:: bash + + tox + +You may not have all Python versions installed or +you may want to run a specific one. +Have a look at the `documentation +`__. +This is how you can run ``tox`` with Python 3.9: .. code-block:: bash - source virtualenv-3/bin/activate + tox -e py39 + +Accessing a ``tox`` environment +------------------------------- + +If you like to enter a specific tox environment, +you can do this: + +.. code-block:: bash + + source .tox/py39/bin/activate + +Install ``icalendar`` Manually +------------------------------- -If for some reason you cannot install ``vitualenv``, you can +The best way to test the package is to use ``tox`` as +described above. +If for some reason you cannot install ``tox``, you can go ahead with the following section using your installed version of Python and ``pip``. -Install Dependencies --------------------- +If for example, you would like to use your local copy of +icalendar in another Python environment, +this section explains how to do it. -You can install the local copy of ``icalendar`` with ``pip``. +You can install the local copy of ``icalendar`` with ``pip`` +like this: .. code-block:: bash @@ -68,6 +100,9 @@ You can install the local copy of ``icalendar`` with ``pip``. This installs the module and dependencies in your Python environment so that you can access local changes. +If tox fails to install ``icalendar`` during its first run, +you can activate the environment in the ``.tox`` folder and +manually setup ``icalendar`` like this. Try it out: @@ -86,10 +121,7 @@ To build the documentation follow these steps: .. code-block:: bash - $ git clone https://github.com/collective/icalendar.git - $ cd icalendar - $ virtualenv-2.7 . - $ source bin/activate + $ source .tox/py39/bin/activate $ pip install -r requirements_docs.txt $ cd docs $ make html