From 10b53cb2862c08a9973188e932e86a541dbaeb9f Mon Sep 17 00:00:00 2001 From: "Edward Z. Yang" Date: Fri, 20 Nov 2009 01:27:39 -0500 Subject: [PATCH] Documentation updates, create upgrade document. Signed-off-by: Edward Z. Yang --- doc/create.rst | 42 +++++++++++++++++++++------ doc/index.rst | 3 +- doc/upgrade.rst | 60 +++++++++++++++++++++++++++++++++++++++ wizard/command/install.py | 2 +- 4 files changed, 97 insertions(+), 10 deletions(-) create mode 100644 doc/upgrade.rst diff --git a/doc/create.rst b/doc/create.rst index 1e4e88d..cce7047 100644 --- a/doc/create.rst +++ b/doc/create.rst @@ -1,7 +1,7 @@ Creating a repository ===================== -:Authors: Edward Z. Yang +:Author: Edward Z. Yang .. highlight:: sh @@ -150,6 +150,7 @@ not being implemented yet. Let's fix that: .. code-block:: python class Application(app.Application): + # ... def download(self, version): return "http://wordpress.org/wordpress-%s.tar.gz" % version @@ -362,16 +363,16 @@ the scriptsified versions would contain generic copies of the configuration files. You're going to generate this generic copy now and in doing so, overload your previous scripts commit. Because some installers exhibit different behavior depending on server configuration, you should run -the installation on a Scripts server:: +the installation on a Scripts server. You can do this manually or use +the test script you created:: - wizard install wordpress --no-commit + env WIZARD_NO_COMMIT=1 ./test-install-wordpress.sh -The installer will interactively prompt you for some values, and then conclude -the install. ``--no-commit`` prevents the installer from generating a Git -commit after the install, and will make it easier for us to propagate the -change back to the parent repository. +:envvar:`WIZARD_NO_COMMIT` (command line equivalent to ``--no-commit``) +prevents the installer from generating a Git commit after the install, and will +make it easier for us to propagate the change back to the parent repository. -Look at the changes the installer made:: +Change into the generated directory and look at the changes the installer made:: git status @@ -564,6 +565,31 @@ commit as ``appname-x.y.z-scripts``, or in this specific case:: git tag wordpress-2.0.4-scripts git push --tags +Summary +------- + +Here is short version for quick reference: + +#. Create the new repository and new module, +#. Implement :meth:`~wizard.app.Application.download`, +#. *For Conversions:* Find the oldest extant version with ``wizard summary version $APP``, +#. Run ``wizard prepare-pristine $VERSION``, +#. Commit with ``-m "$APPLICATION $VERSION"`` and tag ``$APP-$VERSION``, +#. Create ``pristine`` branch, but stay on ``master`` branch, +#. *For Conversions:* Check for pre-existing patches, and apply them, +#. Run ``wizard prepare-new``, +#. *For PHP:* Copy in :file:`php.ini` file and run ``athrun scripts fix-php-ini``, +#. Commit with ``-m "$APPLICATION $VERSION"``, but *don't* tag, +#. Implement :data:`~wizard.app.Application.install_schema` and :meth:`~wizard.app.Application.install`, +#. Create :file:`tests/test-install-$APP.sh`, +#. On a scripts server, run ``wizard install $APP --no-commit`` and check changes with ``git status``, +#. Implement :attr:`~wizard.app.Application.extractors`, + :attr:`~wizard.app.Application.substitutions`, :attr:`~wizard.app.Application.parametrized_files`, + :meth:`~wizard.app.Application.checkConfig` and :meth:`~wizard.app.Application.detectVersion`, +#. Run ``wizard prepare-config``, +#. Amend commit and push back, and finally +#. Tag ``$APP-$VERSION-scripts`` + Further reading --------------- diff --git a/doc/index.rst b/doc/index.rst index fbc5b0c..46d719c 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -54,8 +54,9 @@ Table of Contents .. toctree:: :maxdepth: 1 - testing create + upgrade + testing glossary Modules diff --git a/doc/upgrade.rst b/doc/upgrade.rst new file mode 100644 index 0000000..2acbca3 --- /dev/null +++ b/doc/upgrade.rst @@ -0,0 +1,60 @@ +Preparing an upgrade +==================== + +:Author: Edward Z. Yang + +Wizard is designed to make pushing upgrades as painless as possible. +In the best case scenario, adding a new version to a Wizard repository +is as simple as running a few commands. Even when upstream makes +backwards incompatible changes, or some of your patches conflict with +other changes, Wizard aims to make resolving these changes tractable. + +This document is divided into two sections: first, the basic procedure, +and then troubleshooting tips for recalcitrant upgrades. + +Summary +------- + +``$VERSION`` is a version number i.e. ``1.2.4``, +``$APPLICATION`` is the official application name i.e. ``MediaWiki``, and +``$APP`` is our internal name i.e. ``mediawiki``. The key thing to note +is that we use ``wizard prepare-pristine`` in order to simulate the +upstream upgrade, and then we piggy back off of Git's merge machinery +to do everything else. + +First you prepare the pristine copy: + +.. code-block:: sh + + git checkout pristine + wizard prepare-pristine $VERSION + git commit -asm "$APPLICATION $VERSION" + git tag $APP-$VERSION + +Next, you merge those changes to the scriptsified ``master`` copy: + +.. code-block:: sh + + git checkout master + git merge pristine --no-commit + # resolve conflicts + git commit -asm "$APPLICATION $VERSION-scripts" + +Then, on a scripts server with Wizard pointed at the latest version, run: + +.. code-block:: sh + + cd tests + env WIZARD_NO_COMMIT=1 ./test-install-$APP.sh + cd testdir_install_$APP_head + wizard prepare-config + +Manually restore any custom changes we may have made to the configuration +file, make sure that no upstream changes broke our regular expressions +for matching. Then amend your commit and push back: + +.. code-block:: sh + + git commit --amend -a + git push --force + diff --git a/wizard/command/install.py b/wizard/command/install.py index fb2f085..87af986 100644 --- a/wizard/command/install.py +++ b/wizard/command/install.py @@ -58,7 +58,7 @@ def configure_parser(parser, baton): parser.add_option("--non-interactive", dest="non_interactive", action="store_true", default=False, help="Force program to be non-interactive and use SETUPARGS. Use --help with APP to find argument names.") parser.add_option("--no-commit", dest="no_commit", action="store_true", - default=False, help="Do not generate an 'installation commit' after configuring the application.") + default=command.boolish(os.getenv("WIZARD_NO_COMMIT")), help="Do not generate an 'installation commit' after configuring the application. Envvar is WIZARD_NO_COMMIT") baton.push(parser, "srv_path") def parse_args(argv, baton): -- 2.45.0