This is internal documentation, mostly for Zope maintainers who manage software releases and the documentation
The following persons have access to the
Zope package on PyPI
(in order to release new versions):
Steps for creating a new Zope release
Make sure you have the necessary tools around and install the manually if needed:
$ bin/pip install -U wheel tox twine
Create releases for the packages mentioned in buildout.cfg below
auto-checkoutenter them into
Garden the change log and check it for spelling issues.
Check the future PyPI long description for ReST errors:
$ cat README.rst <(echo) CHANGES.rst | bin/rst2html.py >/tmp/test.html && open /tmp/test.html
Check in the changes.
Update version information in change log and
setup.pyand specify today’s date as release date in the change log:
$ bin/prerelease # if you use zest.releaser or $ vi CHANGES.rst setup.py
Update the version information in the Sphinx documentation configuration:
$ vim docs/conf.py
Pin the Zope version in
Run all tests:
$ bin/tox --pall
If the tests succeed, commit the changes.
Upload the tagged release to PyPI:
$ bin/release # if you use zest.releaser or $ git tag -as <TAG-NAME> -m "- tagging release <TAG-NAME>" $ git push --tags $ bin/zopepy setup.py egg_info -Db '' sdist bdist_wheel $ bin/twine upload -s dist/Zope-<TAG-NAME>*
Update version information in the change log and setup.py:
$ bin/postrelease # if you use zest.releaser or $ vi CHANGES.rst setup.py
Remove the version pin for Zope:
$ vi versions-prod.cfg (remove Zope pin) $ bin/buildout
Commit and push the changes.
Check that the changes have been propagated to https://zope.readthedocs.io/en/latest/changes.html. (This should be done automatically via web hooks defined in GitHub and RTD.)
$ git checkout gh-pages $ python3 build_index.py
Add the newly created files and commit and push the changes.
Check on https://zopefoundation.github.io/Zope/ for the new release.
Check the versions.cfg file for outdated or updated packages and update version information where necessary. You can get a good overview of outdated packages on requires.io:
$ bin/checkversions versions-prod.cfg $ bin/checkversions versions.cfg $ bin/buildout
This step is done after the release to have time to fix problems which might get introduced by new versions of the dependencies.
There is no version pin for zc.buildout as it has to be installed in the virtual environment but checkversions also prints its version number.
There is no version pin for zc.recipe.egg in versions-prod.cfg as it is only needed for buildout install and not for pip, so we do not want to have it in requirements.txt.
The script is called two times so the rendered version updates can be easily assigned to the correct file.
Run the tests:
Build the documentation:
Commit and push the changes.
Update the Zope release schedule at https://www.zope.dev/releases.html
Announce the release to the world via email@example.com and https://community.plone.org/c/announcements.
Maintaining the Zope documentation
Contributing to the documentation
Any signed Zope contributor may contribute to the Sphinx-based documentation
docs subfolder, including The Zope Book and the Zope Developer’s
Just like with code contributions, please follow best practice. Test your changes locally before creating a pull request or pushing to the repository. Use a reasonable line length (<80).
Building the documentation
After you have bootstrapped and run the buildout, you can build the
documentation using the script
bin/make-docs to create the documentation
HTML output. The script will tell you where it saves the output.
The official documentation site on Read the Docs
Pushes to the Zope repository on GitHub will automatically trigger an automatic
documentation refresh on the official documentation site at
https://zope.readthedocs.io. This is true for the
master branch, but also
for versions 2.12 and 2.13. The trigger is implemented as a GitHub Webhook, see
Settings | Webhooks in the GitHub repository.
The RTD configuration at https://readthedocs.org/projects/zope/ is currently maintained by the following people:
Maintaining Zope documentation translations
The Sphinx documentation has some translations now. Adding new translations or maintaining existing ones is done in several steps. The following is mostly taken from https://www.sphinx-doc.org/en/master/usage/advanced/intl.html.
Adding a new document translation
If you are just working on an existing
.po file you can skip these steps.
.potfiles that form the basis for all translations:
$ cd docs $ make gettext
.potfile for the new document to the correct language folder, the following example uses
jafor the Japanese translation. If the folder does not exist yet, just create it:
$ mkdir -p locale/ja/LC_MESSAGES $ cp _build/gettext/maintenance.pot locale/ja/LC_MESSAGES/maintenance.po
Now continue with the steps in the next section.
Maintaining existing translations
Start here if the translation
.po file already exists. This example uses a
maintenance.po from the Japanese translation:
At the top of the
.pofile, enter your name and optionally email address into the field Last-Translator:
$ cd docs $ vim locale/ja/LC_MESSAGES/maintenance.po
Enter translated strings into the various msgstr fields
Build the translated HTML pages from the
$ make -e SPHINXOPTS="-D language='ja'" html
When you are happy with the result, commit the changes to the repository:
$ git commit locale/ja/LC_MESSAGES/maintenance.po
Please do not add any
.pofiles to the repository that have no translations. Those will not do anything but increase the size of the released package.