- more cleanup and better structure

docs/developer/development-culture.rst → docs/developer/guidelines.rst

@@ -1,6 +1,33 @@
 Developer guidelines
 ====================
 
+.. note::
+    Any code contributions that are more than trivial typo fixes require
+    a signed contributor agreement. Please see :doc:`becoming-a-committer`
+    for details.
+
+
+Pull requests
+-------------
+
+Pull requests for bug fixes, features or documentation are always welcome.
+Here's how you can make it easy to accept your contribution:
+
+- Please create branches in the package's repository instead of forking the
+  package. That way other contributors can help easily.
+
+- Respect the conventions you find in the package you're contributing to. This
+  includes code style, tools used to run and configure tests, the package
+  structure and its management. Coordinate with other developers for that
+  package before changing any of these.
+
+- Keep cosmetic and code changes apart. If necessary, put them in separate pull
+  requests.
+
+- If your code is fixing a bug it should have unit tests that exercise the
+  bug and pass with your fix.
+
+
 .. _coding-standards:
 
 Coding Standards
@@ -33,8 +60,8 @@ maintains or improves the target project's conformance to these goals.
 
 .. _layout-conventions:
 
-Layout and Conventions
-----------------------
+Package layout
+--------------
 
 Each project should consist of a single, top-level project folder in
 GitHub. Because we are mostly working on Python code here, projects are
@@ -85,37 +112,3 @@ building in-place and running tests using :mod:`zc.buildout`.
    ...
    $ bin/test
    ...
-
-
-Python 2 support policy
------------------------
-
-.. note::
-    This policy applies to packages that are direct dependencies of Zope 4
-
-Zope 4 will retain full Python 2 (and Python 3.5) compatibility throughout its
-lifetime. That means all its `direct dependencies
-<https://zopefoundation.github.io/Zope/releases/4.x/versions-prod.cfg>`_
-and (ideally) many popular add-on packages should also continue supporting
-Python 2 until Zope 4 reaches end-of-life status.
-
-We encourage all package maintainers to provide Python 2 support on the current
-``master`` release branch instead of a separate maintenance branch because a
-separate maintenance branch leads to a lot of extra work:
-
-- fixes must be ported between branches
-
-- a contributor may not even be aware of a separate maintenance branch
-
-- at package release time releases need to be cut from both the ``master`` and
-  maintenance branches
-
-With that in mind, dropping Python 2 (or Python 3.5) support for a Zope 4
-dependency is allowable under the following circumstances:
-
-- there are compelling technical reasons - or -
-
-- the developer who implements the Python 2/Python 3.5 support drop assumes all
-  responsibility for creating a suitable maintenance branch, porting fixes to
-  it, and making releases from the maintenance branch until Zope 4 support
-  ends.

docs/developer/index.rst

@@ -1,63 +1,44 @@
 Developer Information
 =====================
 
-Intended Audience
------------------
-
 This guide is for developers who are working **on** the various Zope-related
 software projects, rather than for developers who work **with** those
 projects' released software to build applications.  Developers in the
-latter category should visit :doc:`/documentation/index` instead.
-
-
-Contributor Roles
------------------
-
-There are many different ways you might contribute to a Zope-related
-project.  This guide tries to allow for different levels of participation
-in such projects.  For instance:
+latter category should visit the general :doc:`/documentation/index` section
+instead.
 
-- Susan might find a bug in the project while using the project's
-  software in her own application.
+The projects under the zopefoundation GitHub organization are open source and
+welcome contributions in different forms:
 
-- Later, she might volunteer to help triage and fix bugs during a bugday.
+* bug reports
+* code improvements and bug fixes
+* documentation improvements
+* pull request reviews
 
-- She might attend a sprint to work on an important new feature in the
-  project with other volunteers.
+For any changes in the repository besides trivial typo fixes you are required
+to sign the contributor agreement. See :doc:`becoming-a-committer` for details.
 
-- Eventually, Susan might volunteer to assume responsibility with other
-  team members for the ongoing maintenance and release management of the
-  project.
 
-
-Resources for Contributors
---------------------------
+Resources
+---------
 
 Visit https://github.com/zopefoundation to see and browse all repositories
 maintained by the Zope developer community.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
-   bug-trackers
+   reporting-bugs
    mailing-lists
-   development-culture
+   becoming-a-committer
 
 
-Contributing as a Non-Committer
--------------------------------
+Guidelines
+----------
 
 .. toctree::
    :maxdepth: 2
 
-   reporting-bugs
+   guidelines
    sphinx-documentation
-
-
-Becoming a Zope Committer
--------------------------
-
-.. toctree::
-   :maxdepth: 2
-
-   becoming-a-committer
+   python2

docs/developer/python2.rst

@@ -0,0 +1,105 @@
+Python 2 support
+================
+
+.. note::
+    This document is relevant for packages that are either direct dependencies
+    of Zope version 4 or popular add-ons for Zope version 4 and their
+    dependencies.
+
+Zope 4 will retain full Python 2 (and Python 3.5) compatibility throughout its
+lifetime. That means all its `direct dependencies
+<https://zopefoundation.github.io/Zope/releases/4.x/versions-prod.cfg>`_
+and (ideally) many popular add-on packages should also continue supporting
+Python 2 and Python 3.5 until Zope 4 reaches end-of-life status.
+
+
+When to drop support
+--------------------
+
+We encourage all package maintainers to provide Python 2 support on the
+``master`` release branch instead of a separate maintenance branch because a
+separate maintenance branch leads to a lot of extra work:
+
+- fixes must be ported between branches
+
+- a contributor may not even be aware of a separate maintenance branch
+
+- at package release time releases need to be cut from both the ``master`` and
+  maintenance branches
+
+With that in mind, dropping Python 2 (or Python 3.5) support for a Zope 4
+dependency is allowable under the following circumstances:
+
+- there are compelling technical reasons - or -
+
+- the developer who implements the Python 2/Python 3.5 support drop assumes all
+  responsibility for creating a suitable maintenance branch, porting fixes to
+  it, and making releases from the maintenance branch until Zope 4 support
+  ends.
+
+
+How to drop support
+-------------------
+
+When dropping Python 2 support you should also "upgrade" the code to support
+more modern practices, like using `f-strings
+<https://www.python.org/dev/peps/pep-0498/>`_.
+
+Prerequisites
+~~~~~~~~~~~~~
+
+- ``pyupgrade`` installed (the code examples below expect it to be on the
+  search PATH.)
+
+
+Typical steps
+~~~~~~~~~~~~~
+
+The following steps are necessary to remove Python 2 support from a package:
+
+- Create a new branch from ``master`` first that can be used as maintenance
+  branch with Python 2 support for backporting important fixes if needed.
+
+- Create a new branch from ``master`` to hold your code changes and switch to
+  that branch for the next steps.
+
+- ``setup.py``
+
+  - Update version number to next major version.
+  - Remove Python 2 from the list of classifiers.
+  - Remove ``six`` from the list of dependencies
+  - Update ``python_requires`` to ``python_requires='>=3.6, <4'``
+  - Remove other things pointing to Python 2 or PyPy/PyPy2.
+
+- ``setup.cfg``
+
+  - set ``universal = 0`` in section ``[bdist_wheel]``
+
+- ``tox.ini``
+
+  - Remove ``py27``, ``pypy`` or ``pypy2`` from ``envlist``
+  - Remove Python 2 specific environments
+
+- ``.travis.yml``
+
+  - Remove Python 2.7 and PyPy/PyPy2 jobs.
+
+- ``appveyor.yml``
+
+  - Remove Python 2 job(s) if existing.
+
+- ``CHANGES.rst``
+
+  - Update the version number of the unreleased version
+  - Add an entry: ``Drop support for Python 2.``
+
+- Remove Python 2 support code
+
+  - Replace all code that uses ``six`` with its Python 3 equivalent,
+    find it by running ``grep -rn six src``
+  - Run the tests with ``tox`` and fix any problems you encounter
+  - Run ``egrep -rn "2.7|sys.version|PY2|PY3|Py2|Py3|Python 2|Python 3|__unicode__|ImportError" src`` to find any remaining code that may support Python 2
+  - Run ``find src -name "*.py" -exec pyupgrade --py36-plus {} \;``
+    to update the code to Python 3 only coding standards.
+
+- Create pull request against ``master`` from your code change branch.

docs/developer/reporting-bugs.rst

@@ -1,37 +1,36 @@
-Reporting Bugs against Zope Packages
-====================================
+Reporting Bugs
+==============
 
-.. note::
-
-   This outline needs fleshing out.
+The Zope developer community uses the `GitHub zopefoundation organization
+<https://github.com/zopefoundation>`_ to host all projects. Each repository
+has its own issue tracker for bug reports, feature requests or questions.
+For example, Zope developers track bugs within Zope using the ``Zope``
+project on GitHub:
 
+ https://github.com/zopefoundation/Zope/issues
 
-Identifying the Project which Has the Bug
------------------------------------------
 
-- Look at tracebacks from "bottom up".
+How to write a good bug report
+------------------------------
 
-- Look for recently updated eggs.
+Here's how you get help most effectively:
 
+- Before filing a bug report, make sure you can reproduce the issue on a plain
+  vanilla Zope installation. If you cannot, then it's probably not a Zope bug.
 
-Writing the Bug Report
-----------------------
+- Please provide as many details as possible, such as...
 
-- Identify version(s) of code which manifest the bug
+  - Zope version
+  - Python version
+  - Operating system
+  - Full Python tracebacks if you have them
 
-- Describe the symptom as clearly as possible.
-
-- Provide a complete recipe for reproducing the bug.
-
-
-Useful Patches for the Bug Report
----------------------------------
-
-In order of increasing helpfulness:
-
-- Changes to non-test code which work around the problem
-
-- Unit tests which fail against the current code
-
-- Changes to non-test code, which pass against those tests.
+- It's helpful to describe bugs in terms of expected and actual outcomes, that
+  makes it easier to follow along and reproduce it: *In the Zope ZMI I was
+  clicking on the Interfaces tab of a DTML Method, and instead of seeing the
+  Interfaces tab I saw the following error output: ...*
 
+- If the developers need more information and follow up with questions, please
+  make sure to answer in a timely manner, especially if the issue report is
+  marked with the feedback required tag. If we don't hear from you after 2-3
+  weeks the issue may be closed.

docs/developer/sphinx-documentation.rst

@@ -1,5 +1,5 @@
-Documenting Zope Packages Using Sphinx
-======================================
+Documenting code with Sphinx
+============================
 
 .. note::