<!--  -->
<sect1 id="releasechecklist"> <title> Release Checklist </title>

<indexterm><primary>release checklist</primary></indexterm>

<para> Here are things that should be done whenever a release is prepared:</para>
<itemizedlist>

<listitem><para>Positive build reports for each supported platform -
although it is arguably less necessary for a comprehensive list if we
are releasing a minor upgrade </para></listitem>

<listitem><para>Some kind of Standard Test Plan</para></listitem> 

<listitem><para> If the release modified the set of version-specific
SQL files in <filename>src/backend</filename>
(<emphasis>e.g.</emphasis> - it added a new
<filename>slony1_base.v83.sql</filename> or
<filename>slony1_funcs.v83.sql</filename>), or if we have other
changes to the shape of &postgres; version support, the function
<function>load_slony_functions() </function> in
<filename>src/slonik/slonik.c</filename> needs to be revised to
reflect the new shape of things.</para> </listitem>

<listitem><para> The new release needs to be added to function
<function>upgradeSchema(text)</function> in
<filename>src/backend/slony1_funcs.sql</filename>. </para>

<para> This takes place in a <quote>cross-branch</quote> fashion; if
we add version 1.1.9, in the 1.1 branch, then version 1.1.9 needs to
be added to the 1.2 branch as well as to later branches
(<emphasis>e.g.</emphasis> - 1.3, 1.4, HEAD).  Earlier branches will
normally not need to be made aware of versions added to later
branches. </para> 

<para> This was not true for version 2 - version 2.0 was different
enough from earlier versions that we rejected having a direct upgrade
from 1.x to 2.0, so there are <emphasis>no</emphasis> versions in 1.x
branches in <function>upgradeSchema(text)</function> for &slony1;
version 2.0. </para></listitem>

<listitem><para>Binary RPM packages</para></listitem> 

<listitem> <para>If the release is a <quote>.0</quote> one, we need to
open a new STABLE branch</para>

<para> <command> git checkout HEAD</command></para> 
<para> <command> git checkout -b REL_3_0_STABLE</command></para> 
</listitem>

<listitem> <para>Tag with the release ID. For version 1.1.2, this
would be <envar>REL_1_1_2 </envar></para>

<para> <command> git tag -a REL_1_1_2 </command></para> </listitem>

<listitem><para>Check out an exported copy via:
<command>git archive REL_1_1_2  -o /tmp/slony1-engine-1.0.2.tar </command> 
</para></listitem>

<listitem><para>Run <application>autoconf</application> so as to
regenerate <filename>configure</filename> from
<filename>configure.ac</filename></para></listitem>

<listitem><para>Purge directory <filename>autom4te.cache</filename> so it is not included in the build  </para>
<para> Does not need to be done by hand - the later <command> make distclean </command> step does this for you. </para>
</listitem> 

<listitem><para> Run <filename>tools/release_checklist.sh</filename> </para>

<para> This does a bunch of consistency checks to make sure that
various files that are supposed to contain version numbers contain
consistent values.</para> 
</listitem>
<listitem><para>For instance, configure should contain, for release 1.1.2:</para></listitem>

<listitem><para>PACKAGE_VERSION=REL_1_1_2</para></listitem>

<listitem><para>PACKAGE_STRING=slony1 REL_1_1_2</para></listitem>

</itemizedlist>
<itemizedlist>
<listitem><para> <filename> config.h.in </filename> needs to contain the version
number in two forms; the definitions for
<envar>SLONY_I_VERSION_STRING</envar> and
<envar>SLONY_I_VERSION_STRING_DEC</envar> both need to be
updated. </para> </listitem>

<listitem><para> <filename>src/backend/slony1_funcs.sql</filename> has
major/minor/patch versions in functions
<function>slonyVersionMajor()</function>,
<function>slonyVersionMinor()</function>, and
<function>slonyVersionPatchlevel()</function>.  These need to be
assigned <quote>by hand</quote> at this point.</para> </listitem>

<listitem><para> It sure would be nice if more of these could be assigned
automatically, somehow.</para>

<para><emphasis>Don't</emphasis> commit the new
<filename>configure</filename>; we shouldn't be tracking this in Git.
</para></listitem>

<listitem><para>make sure that the generated files from .l and .y are
created, for example <filename>slony/conf-file.[ch]</filename> </para>

<para> Currently this is best done by issuing <command> ./configure &&
make all && make clean</command> but that is a somewhat ugly approach.</para>

<para> Slightly better may be <command> ./configure && make
src/slon/conf-file.c src/slonik/parser.c src/slonik/scan.c </command>
</para></listitem> 

<listitem><para> Make sure that generated Makefiles and such from the
previous step(s) are removed.</para>

<para> <command>make distclean</command> will do
that... </para>

<para> Note that <command>make distclean</command> also clears out
<filename>autom4te.cache</filename>, thus obsoleting some former steps
that suggested that it was needful to delete them. </para>
</listitem>

<listitem><para>Generate HTML tarball, and RTF/PDF, if
possible... Note that the HTML version should include
<filename>*.html</filename> (duh!), <filename>*.jpg</filename>,
<filename>*.png</filename>, and <filename>*.css</filename> </para>

<para> Note that, if starting from a <quote>clean</quote> copy of the
documentation, in order to properly build the HTML tarball, it is
necessary to run <command>make html</command>
<emphasis>twice</emphasis>, in order for the document index to be
properly constructed.

<itemizedlist>

<listitem><para> The first time <command>make html</command> is run,
the file <filename>HTML.index</filename> does not yet exist.</para>

<para> When <application>jade</application> is run, against the
document, a side-effect is to generate
<filename>HTML.index</filename>, extracting all index tags from the
&slony1; documentation.</para></listitem>

<listitem><para> The second time <command>make html</command> is run,
<filename>HTML.index</filename> is transformed into
<filename>bookindex.sgml</filename>, which
<application>jade</application> may then use to generate a nice <link
linkend="bookindex">index page</link> indicating all the index entries
included in the documentation tree.</para></listitem>

</itemizedlist></para>

</listitem>

<listitem><para>Run <command>make clean</command> in
<filename>doc/adminguide</filename> before generating the tarball in
order that <filename>bookindex.sgml</filename> is NOT part of the
tarball </para></listitem>

<listitem><para>Alternatively, delete
<filename>doc/adminguide/bookindex.sgml </filename> </para></listitem>

<listitem><para>Rename the directory (<emphasis>e.g.</emphasis> -
<filename>slony1-engine</filename>) to a name based on the release,
<emphasis>e.g.</emphasis> - <filename>slony1-1.1.2</filename>
</para></listitem>

<listitem><para>Generate a tarball - <command>tar tfvj
slony1-1.1.2.tar.bz2 slony1-1.1.2 </command> </para></listitem>

<listitem><para>Build the administrative documentation, and build a
tarball as <filename>slony1-1.1.2-html.tar.bz2</filename></para>

<para> Make sure that the docs are inside a subdir in the tarball.
</para></listitem>

<listitem><para>Put these tarballs in a temporary area, and notify
everyone that they should test them out ASAP based on the Standard
Test Plan. </para></listitem>

</itemizedlist>
</sect1>
<!-- Keep this comment at the end of the file
Local variables:
mode:sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:"slony.sgml"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
-->
