Update CONTRIBUTING docs for Python 2.x removal

This also updates the Contributing documentation with information on new
development tooling.

CONTRIBUTING.rst

@@ -137,8 +137,7 @@ Contribution quality standards
   code/formatting can be improved. If you are relying on your editor for PEP8
   compliance, note that the line length specified by PEP8 is 79 (excluding the
   line break).
-* Ensure your code is compatible with the latest Python 2.7 and 3.x releases — see our
+* Ensure your code is compatible with the `officially-supported Python releases`_.
-  `compatibility cheatsheet`_ for more details.
 * Add docs and tests for your changes. Undocumented and untested features will
   not be accepted.
 * `Run all the tests`_ **on all versions of Python supported by Pelican** to
@@ -155,4 +154,4 @@ need assistance or have any questions about these guidelines.
 .. _`Git Tips`: https://github.com/getpelican/pelican/wiki/Git-Tips
 .. _`PEP8 coding standards`: https://www.python.org/dev/peps/pep-0008/
 .. _`ask for help`: `How to get help`_
-.. _`compatibility cheatsheet`: https://docs.getpelican.com/en/latest/contribute.html#python-3-development-tips
+.. _`officially-supported Python releases`: https://devguide.python.org/#status-of-python-branches

docs/contribute.rst

@@ -7,72 +7,78 @@ can also help out by reviewing and commenting on
 `existing issues <https://github.com/getpelican/pelican/issues>`_.
 
 Don't hesitate to fork Pelican and submit an issue or pull request on GitHub.
-When doing so, please adhere to the following guidelines.
+When doing so, please consider the following guidelines.
 
 .. include:: ../CONTRIBUTING.rst
 
 Setting up the development environment
 ======================================
 
-While there are many ways to set up one's development environment, we recommend
+While there are many ways to set up one's development environment, the following
-using `Virtualenv <https://virtualenv.pypa.io/en/stable/>`_. This tool allows
+instructions will utilize Pip_ and Poetry_. These tools facilitate managing
-you to set up separate environments for separate Python projects that are
+virtual environments for separate Python projects that are isolated from one
-isolated from one another so you can use different packages (and package
+another, so you can use different packages (and package versions) for each.
-versions) for each.
 
-If you don't have ``virtualenv`` installed, you can install it via::
+Please note that Python 3.6+ is required for Pelican development.
 
-    $ pip install virtualenv
+*(Optional)* If you prefer to install Poetry once for use with multiple projects,
+you can install it via::
 
-Use ``virtualenv`` to create and activate a virtual environment::
+    curl -sSL https://raw.githubusercontent.com/sdispater/poetry/master/get-poetry.py | python
 
-    $ virtualenv ~/virtualenvs/pelican
+Point your web browser to the `Pelican repository`_ and tap the **Fork** button
-    $ cd ~/virtualenvs/pelican
+at top-right. Then clone the source for your fork and add the upstream project
-    $ . bin/activate
+as a Git remote::
 
-Clone the Pelican source into a subfolder called ``src/pelican``::
+    mkdir ~/projects
+    git clone https://github.com/YOUR_USERNAME/pelican.git ~/projects/pelican
+    cd ~/projects/pelican
+    git remote add upstream https://github.com/getpelican/pelican.git
 
-    $ git clone https://github.com/getpelican/pelican.git src/pelican
+While Poetry can dynamically create and manage virtual environments, we're going
-    $ cd src/pelican
+to manually create and activate a virtual environment::
 
-Install the development dependencies::
+    mkdir ~/virtualenvs
+    python3 -m venv ~/virtualenvs/pelican
+    source ~/virtualenvs/pelican/bin/activate
 
-    $ pip install -r requirements/developer.pip
+Install the needed dependencies and set up the project::
 
-Install Pelican and its dependencies::
+    pip install -e ~/projects/pelican invoke
+    invoke setup
 
-    $ python setup.py develop
+Your local environment should now be ready to go!
 
-Or using ``pip``::
+.. _Pip: https://pip.pypa.io/
+.. _Poetry: https://poetry.eustace.io/docs/#installation
+.. _Pelican repository: https://github.com/getpelican/pelican
 
-    $ pip install -e .
+Development
+===========
 
-To conveniently test on multiple Python versions, we also provide a ``.tox``
+Once Pelican has been set up for local development, create a topic branch for
-file.
+your bug fix or feature:
 
+    git checkout -b name-of-your-bugfix-or-feature
 
-Building the docs
+Now you can make changes to Pelican, its documentation, and/or other aspects of
-=================
+the project.
-
-If you make changes to the documentation, you should preview your changes
-before committing them::
-
-    $ pip install -r requirements/docs.pip
-    $ cd docs
-    $ make html
-
-Open ``_build/html/index.html`` in your browser to preview the documentation.
 
 Running the test suite
-======================
+----------------------
 
-Each time you add a feature, there are two things to do regarding tests: check
+Each time you make changes to Pelican, there are two things to do regarding
-that the existing tests pass, and add tests for the new feature or bugfix.
+tests: check that the existing tests pass, and add tests for any new features
+or bug fixes. The tests are located in ``pelican/tests``, and you can run them
+via::
 
-The tests live in ``pelican/tests`` and you can run them using the
+    invoke tests
-"discover" feature of ``unittest``::
 
-    $ python -Wd -m unittest discover
+In addition to running the test suite, the above invocation will also check code
+style and let you know whether non-conforming patterns were found. In some cases
+these linters will make the needed changes directly, while in other cases you
+may need to make additional changes until ``invoke tests`` no longer reports any
+code style violations.
 
 After making your changes and running the tests, you may see a test failure
 mentioning that "some generated files differ from the expected functional tests
@@ -82,11 +88,11 @@ the nature of your changes, then you should update the output used by the
 functional tests. To do so, **make sure you have both** ``en_EN.utf8`` **and**
 ``fr_FR.utf8`` **locales installed**, and then run the following two commands::
 
-    $ LC_ALL=en_US.utf8 pelican -o pelican/tests/output/custom/ \
+    LC_ALL=en_US.utf8 pelican -o pelican/tests/output/custom/ \
         -s samples/pelican.conf.py samples/content/
-    $ LC_ALL=fr_FR.utf8 pelican -o pelican/tests/output/custom_locale/ \
+    LC_ALL=fr_FR.utf8 pelican -o pelican/tests/output/custom_locale/ \
         -s samples/pelican.conf_FR.py samples/content/
-    $ LC_ALL=en_US.utf8 pelican -o pelican/tests/output/basic/ \
+    LC_ALL=en_US.utf8 pelican -o pelican/tests/output/basic/ \
         samples/content/
 
 You may also find that some tests are skipped because some dependency (e.g.,
@@ -101,48 +107,68 @@ environments.
 
 .. _Tox: https://tox.readthedocs.io/en/latest/
 
-Python 2/3 compatibility development tips
+Building the docs
-=========================================
+-----------------
 
-Here are some tips that may be useful for writing code that is compatible with
+If you make changes to the documentation, you should preview your changes
-both Python 2.7 and Python 3:
+before committing them::
 
-- Use new syntax. For example:
+    cd docs
+    make html
 
-  - ``print .. -> print(..)``
+Open ``_build/html/index.html`` in your browser to preview the documentation.
-  - ``except .., e -> except .. as e``
 
-- Use new methods. For example:
+Plugin development
+------------------
 
-  - ``dict.iteritems() -> dict.items()``
+To create a *new* Pelican plugin, please refer to the `plugin template`_
-  - ``xrange(..) - > list(range(..))``
+repository for detailed instructions.
 
-- Use ``six`` where necessary. For example:
+If you want to contribute to an *existing* Pelican plugin, follow the steps
+above to set up Pelican for local development, and then create a directory to
+store cloned plugin repositories::
 
-  - ``isinstance(.., basestring) -> isinstance(.., six.string_types)``
+   mkdir -p ~/projects/pelican-plugins
-  - ``isinstance(.., unicode) -> isinstance(.., six.text_type)``
 
-- Assume every string and literal is Unicode:
+Assuming you wanted to contribute to the Simple Footnotes plugin, you would
+first browse to the `Simple Footnotes`_ repository on GitHub and tap the **Fork**
+button at top-right. Then clone the source for your fork and add the upstream
+project as a Git remote::
 
-  - Use ``from __future__ import unicode_literals``
+    git clone https://github.com/YOUR_USERNAME/simple-footnotes.git ~/projects/pelican-plugins/simple-footnotes
-  - Do not use the prefix ``u'`` before strings.
+    cd ~/projects/pelican-plugins/simple-footnotes
-  - Do not encode/decode strings in the middle of something. Follow the code to
+    git remote add upstream https://github.com/pelican-plugins/simple-footnotes.git
-    the source/target of a string and encode/decode at the first/last possible
-    point.
-  - In particular, write your functions to expect and to return Unicode.
-  - Encode/decode strings if the string is the output of a Python function that
-    is known to handle this badly. For example, ``strftime()`` in Python 2.
-  - Do not use the magic method ``__unicode()__`` in new classes. Use only
-    ``__str()__`` and decorate the class with ``@python_2_unicode_compatible``.
 
-- ``setlocale()`` in Python 2 fails when we give the locale name as Unicode,
+Install the needed dependencies and set up the project::
-  and since we are using ``from __future__ import unicode_literals``, we do
+
-  that everywhere! As a workaround, enclose the locale name with ``str()``;
+    invoke setup
-  in Python 2 this casts the name to a byte string, while in Python 3 this
+
-  should do nothing, because the locale name was already Unicode.
+After writing new tests for your plugin changes, run the plugin test suite::
-- Do not start integer literals with a zero. This is a syntax error in Python 3.
+
-- Unfortunately there seems to be no octal notation that is valid in both
+    invoke tests
-  Python 2 and 3. Use decimal notation instead.
+
+.. _plugin template: https://github.com/getpelican/cookiecutter-pelican-plugin
+.. _Simple Footnotes: https://github.com/pelican-plugins/simple-footnotes
+
+Submitting your changes
+-----------------------
+
+Assuming linting validation and tests pass, add a ``RELEASE.md`` file in the root
+of the project that contains the release type (major, minor, patch) and a
+summary of the changes that will be used as the release changelog entry.
+For example::
+
+    Release type: patch
+
+    Fix browser reloading upon changes to content, settings, or theme
+
+Commit your changes and push your topic branch::
+
+    git add .
+    git commit -m "Your detailed description of your changes"
+    git push origin name-of-your-bugfix-or-feature
+
+Finally, browse to your repository fork on GitHub and submit a pull request.
 
 
 Logging tips
@@ -160,8 +186,8 @@ For logging messages that are not repeated, use the usual Python way::
     logger.warning("A warning with %s formatting", arg_to_be_formatted)
 
 Do not format log messages yourself. Use ``%s`` formatting in messages and pass
-arguments to logger. This is important, because Pelican logger will preprocess
+arguments to logger. This is important, because the Pelican logger will
-some arguments (like Exceptions) for Py2/Py3 compatibility.
+preprocess some arguments, such as exceptions.
 
 Limiting extraneous log messages
 --------------------------------