[Checkins] SVN: groktoolkit/trunk/doc/ update release procedure
Jan-Wijbrand Kolman
janwijbrand at gmail.com
Tue Feb 8 10:54:58 EST 2011
Log message for revision 120218:
update release procedure
Changed:
D groktoolkit/trunk/doc/developing_grok.rst
U groktoolkit/trunk/doc/docindex.template
A groktoolkit/trunk/doc/release.rst
-=-
Deleted: groktoolkit/trunk/doc/developing_grok.rst
===================================================================
--- groktoolkit/trunk/doc/developing_grok.rst 2011-02-08 15:27:53 UTC (rev 120217)
+++ groktoolkit/trunk/doc/developing_grok.rst 2011-02-08 15:54:57 UTC (rev 120218)
@@ -1,123 +0,0 @@
-===============
-Developing Grok
-===============
-
-.. contents::
-
-Making Grok (Toolkit) releases
-------------------------------
-
-Manual steps
-~~~~~~~~~~~~
-
-Grok Toolkit's release procedure (and that of the comprising package like grok
-and the ``grokcore.*`` family of libraries) follows ZTK's `official release
-guidelines`_.
-
-.. _`official release guidelines`: http://docs.zope.org/zopetoolkit/process/releasing-software.html
-
-Automated steps
-~~~~~~~~~~~~~~~
-
-Even if it can be useful to follow these release steps by hand, most of it is
-automated in the `zest.releaser`_ package that is included in Grok Toolkit's
-``buildout.cfg``. Using this tool will prevent making mistakes caused by the
-rather repetitive nature of the release process.
-
-.. _`zest.releaser`: http://pypi.python.org/pypi/zest.releaser
-
-Part of the `official release guidelines`_ is reviewing the changelog recorded
-in ``CHANGES.txt``. This is an important step that cannot be automated.
-
-In other words, before starting a release make sure that:
-
- 1) All tests pass
- 2) All local changes are committed
- 3) The changelogs in the Grok packages are up to date.
-
-The `zest.releaser` package provides a command line utility to help reviewing
-the changelog. It will display a diff between the most recently created
-release tag and the current maintenance branch of trunk::
-
- $ ./bin/lasttagdiff
-
-After having reviewed the changelog (and making sure any changes are commited!)
-the actual release can be made::
-
- $ ./bin/fullrelease
-
-Grok Tookit contains a post-release step triggered by zest.releaser that will
-upload a ``versions.cfg`` file to::
-
- grok.zope.org:/var/www/html/grok/releaseinfo/[VERSION]/versions.cfg
-
-Manual post-release steps
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-After having released Grok, the following steps should be taken:
-
-1. Grokproject generates a ``buildout.cfg`` with an ``extends`` directive
- pointing to the most recent release versions file. It determines the URL
- to this versions file by reading http://grok.zope.org/releaseinfo/current.
- This file needs to be updated to point to the uploaded ``*.cfg`` file for
- the official "final" releases.
-
-2. Add a document with the release announcement in the `releases folder`_
- Name it after the release version number. Summarize what is in
- ``CHANGES.txt``. Make sure you move it to become the first item of the
- releases folder. You can move it up by using the contents view of the
- folder. The last column in that table presents a handle by which you can
- drag up the document in the folder.
-
- .. _`releases folder`: http://grok.zope.org/project/releases/
-
-3. Official Documentation: Create a build of the docs from the tagged
- release and copy it to the server. Detailed steps are documented in the
- `Updating the Official Grok Documentation (OGD)`_ page.
-
-4. Create a news item in the `blog folder`_ announcing the news. The text
- can be based on the release notes written at point 7.
-
- .. _`blog folder`: http://grok.zope.org/blog/
-
-5. Make both the new release notes, the new news item, as well as the
- updated upgrade notes public.
-
-6. Update the sidebar in the site. You can edit it here::
-
- http://grok.zope.org/portal_skins/custom/portlet_download/manage_main
-
-7. Community Documentation: Update the Plone Help Center used for Grok
- Community Documentation so that the new Version is available. Important: you
- can select multiple "current" versions for community documentation, any
- documentation for a release which is not "current" gets a big nasty
- "outdated" header at the top of it. We only want to do this for
- documentation which is truly outdated and no longer best practice. Do this
- here: http://grok.zope.org/documentation/edit
-
-8. Send out an email to at least zope-announce at zope.org as well as grok-
- dev at zope.org announcing the new release. The text can be based on the
- release notes written at step 2.
-
-9. Update the Grok Wikipedia article with the information about the latest
- release: http://en.wikipedia.org/wiki/Grok_(web_framework)
-
-.. _`Updating the Official Grok Documentation (OGD)`: http://grok.zope.org/project/meta/updating-the-official-grok-documentation-ogd
-
-Binary eggs on Windows
-----------------------
-
-Grok aims to work on Windows as well. This is not a problem for the most part,
-but takes special attention when updating the list of dependencies. The follow
-eggs need a compiler on Unixy platforms, and a binary egg on Windows::
-
- zope.i18nmessageid
- zope.interface
- zope.security
- zope.container
- ZODB3
- zope.hookable
- zope.proxy
-
-Please make sure a Windows version of the egg is available when you update a
-dependency!
Modified: groktoolkit/trunk/doc/docindex.template
===================================================================
--- groktoolkit/trunk/doc/docindex.template 2011-02-08 15:27:53 UTC (rev 120217)
+++ groktoolkit/trunk/doc/docindex.template 2011-02-08 15:54:57 UTC (rev 120218)
@@ -11,31 +11,31 @@
<p><strong>Sections</strong></p>
<table class="contentstable" align="center"><tr>
<td width="50%">
- <p class="biglink"><a class="biglink" href="{{ pathto("tutorial") }}">Grok Tutorial</a><br>
+ <p class="biglink"><a class="biglink" href="{{ pathto("tutorial") }}">Grok tutorial</a><br>
<span class="linkdescr">Get started with Grok.</span></p>
- <p class="biglink"><a class="biglink" href="{{ pathto("reference/index") }}">The Grok Reference</a><br>
+ <p class="biglink"><a class="biglink" href="{{ pathto("reference/index") }}">Grok reference</a><br>
<span class="linkdescr">Describes syntax and package elements.</span></p>
- <p class="biglink"><a class="biglink" href="{{ pathto("grok_overview") }}">Grok Developer Notes</a><br>
- <span class="linkdescr">Overview of what's in Grok and how to use it.</span></p>
+ <p class="biglink"><a class="biglink" href="{{ pathto("upgrade") }}">Upgrade notes</a><br>
+ <span class="linkdescr">How to upgrade your project to a new version of Grok.</span></p>
- <p class="biglink"><a class="biglink" href="{{ pathto("naming_conventions") }}">Naming Conventions</a><br>
- <span class="linkdescr">How to name your stuff correctly.</span></p>
-
- </td><td width="50%">
<p class="biglink"><a class="biglink" href="{{ pathto("packages") }}">Packages</a><br>
<span class="linkdescr">The packages that comprise Grok.</span></p>
- <p class="biglink"><a class="biglink" href="{{ pathto("upgrade") }}">Upgrade notes</a><br>
- <span class="linkdescr">How to upgrade your project to a new version of Grok.</span></p>
+ <p class="biglink"><a class="biglink" href="{{ pathto("releases") }}">Releases</a><br>
+ <span class="linkdescr">A history of Grok releases.</span></p>
- <p class="biglink"><a class="biglink" href="{{ pathto("developing_grok") }}">Developing Grok</a><br>
+ </td><td width="50%">
+ <p class="biglink"><a class="biglink" href="{{ pathto("grok_overview") }}">Grok developer notes</a><br>
+ <span class="linkdescr">Overview of what's in Grok and how to use it.</span></p>
+
+ <p class="biglink"><a class="biglink" href="{{ pathto("naming_conventions") }}">Naming conventions</a><br>
+ <span class="linkdescr">How to name your stuff correctly.</span></p>
+
+ <p class="biglink"><a class="biglink" href="{{ pathto("release") }}">Making releases of Grok</a><br>
<span class="linkdescr">Notes for developers <strong>of</strong> Grok.</span></p>
- <p class="biglink"><a class="biglink" href="{{ pathto("releases") }}">Releases</a><br>
- <span class="linkdescr">A history of Grok releases.</span></p>
-
</td></tr>
</table>
@@ -44,10 +44,10 @@
<td width="50%">
<p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">Table of Contents</a><br>
<span class="linkdescr">Lists all sections and subsections.</span></p>
-<!--
+
<p class="biglink"><a class="biglink" href="{{ pathto("search") }}">Search page</a><br>
<span class="linkdescr">search this documentation</span></p>
--->
+
</td><td width="50%">
<p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">Index</a><br>
<span class="linkdescr">All functions, classes, terms.</span></p>
Copied: groktoolkit/trunk/doc/release.rst (from rev 120216, groktoolkit/trunk/doc/developing_grok.rst)
===================================================================
--- groktoolkit/trunk/doc/release.rst (rev 0)
+++ groktoolkit/trunk/doc/release.rst 2011-02-08 15:54:57 UTC (rev 120218)
@@ -0,0 +1,125 @@
+===============
+Developing Grok
+===============
+
+.. contents::
+
+Making releases of packages that make up Grok
+=============================================
+
+Making releases
+===============
+
+The release procedure for the packages that comprise Grok, like ``grok`` and
+the ``grokcore.*`` family of libraries, follows ZTK's `official release
+guidelines`_.
+
+.. _`official release guidelines`: http://docs.zope.org/zopetoolkit/process/releasing-software.html
+
+Automating the release
+----------------------
+
+Even if it can be useful to follow these release steps by hand, most of it is
+automated in the `zest.releaser`_ package that is included in groktoolkit's
+``buildout.cfg``. Using this tool will prevent making mistakes caused by the
+rather repetitive nature of the release process.
+
+.. _`zest.releaser`: http://pypi.python.org/pypi/zest.releaser
+
+Before commencing the release it is important to to make sure the packages'
+changelog is up to date. A useful tool, part of the `zest.releaser`_ tool
+chain, is the ``lasttagdiff`` command. This command will output the changes
+between the latest release tag and the current trunk:
+
+ $ ./bin/lasttagdiff.
+
+After having reviewed the changes and updating the changelog of a package (and
+making sure any changes are commited!) the actual release can be made::
+
+ $ ./bin/fullrelease
+
+Part of the ``fullrelease`` procedure is the registration and upload of the
+packge to the Python `Package Index <http://pypi.pytthon.org/>`_. Make sure
+you're actually allowed to upload the particular package to the index!
+
+Making the groktoolkit release
+==============================
+
+Releases of groktoolkit are similar to that of making releases of the
+individual packages. The ``zest.releaser`` tool will help you create the
+release tag and update the version information.
+
+The groktoolkit contains a post-release step triggered by ``zest.releaser``
+that will upload a ``versions.cfg`` file to::
+
+ grok.zope.org:/var/www/html/grok/releaseinfo/[VERSION]/versions.cfg
+
+Manual groktoolkit post-release steps
+-------------------------------------
+
+After having released the groktoolkit, the following steps should be taken:
+
+1. Grokproject generates a ``buildout.cfg`` with an ``extends`` directive
+ pointing to the most recent release versions file. It determines the URL
+ to this versions file by reading http://grok.zope.org/releaseinfo/current.
+ This file needs to be updated to point to the uploaded ``*.cfg`` file for
+ the official "final" releases.
+
+2. Add a document with the release announcement in the `releases folder`_
+ Name it after the release version number. Summarize what is in
+ ``CHANGES.txt``. Make sure you move it to become the first item of the
+ releases folder. You can move it up by using the contents view of the
+ folder. The last column in that table presents a handle by which you can
+ drag up the document in the folder.
+
+ .. _`releases folder`: http://grok.zope.org/project/releases/
+
+3. Official Documentation: Create a build of the docs from the tagged
+ release and copy it to the server. The steps are roughly as follows::
+
+ $ svn co svn+ssh://svn.zope.org/repos/main/groktoolkit/tags/[VERSION] gtk
+ $ cd gtk
+ $ python bootstrap.py
+ $ ./bin/buildout -c documentation.cfg
+ $ cd doc && make clean && make all
+ $ scp -r _build/html grok.zope.org:/var/www/html/grok/doc/[VERSION]
+ $ ssh grok.zope.org \
+ "rm /var/www/html/grok/doc/current; \
+ ln -s /var/www/html/grok/doc/[VERSION] /var/www/html/grok/current"
+
+4. Create a news item in the `blog folder`_ announcing the news. The text
+ can be based on the release notes written at point 7.
+
+ .. _`blog folder`: http://grok.zope.org/blog/
+
+5. Make both the new release notes, the new news item, as well as the
+ updated upgrade notes public.
+
+6. Update the sidebar in the site. You can edit it here::
+
+ http://grok.zope.org/portal_skins/custom/portlet_download/manage_main
+
+8. Send out an email to at least zope-announce at zope.org as well as grok-
+ dev at zope.org announcing the new release. The text can be based on the
+ release notes written at step 2.
+
+9. Update the Grok Wikipedia article with the information about the latest
+ release: http://en.wikipedia.org/wiki/Grok_(web_framework)
+
+Binary eggs on Windows
+----------------------
+
+Grok aims to work on Windows as well. This is not a problem for the most part,
+but takes special attention when updating the list of dependencies. The follow
+eggs need a compiler on Unixy platforms, and a binary egg on Windows::
+
+ zope.i18nmessageid
+ zope.interface
+ zope.security
+ zope.container
+ ZODB3
+ zope.hookable
+ zope.proxy
+
+Please make sure a Windows version of the egg is available when you update a
+dependency!
More information about the checkins
mailing list