X-Git-Url: https://scripts.mit.edu/gitweb/wizard.git/blobdiff_plain/23a9093a401649961d73e7303bf8ef1929c6547e..3a2a3f6faeb318d11d9474e72c0b5fb9d29ad14c:/doc/create.rst
diff --git a/doc/create.rst b/doc/create.rst
index 826c2b1..94b0e77 100644
--- a/doc/create.rst
+++ b/doc/create.rst
@@ -39,9 +39,15 @@ Pristine
--------
This is a tutorial centered around creating a `Wordpress `_
-repository. For the sake of demonstration,
-we shall assume that this repository hasn't been created yet.
-The repository then doesn't exist, we should create it::
+repository. It assumes you have an upstream; if you do not,
+you can skip most of these steps: just ensure you have a Git repository
+which contains a :term:`pristine` and :term:`master` branch,
+as well as tags for all of the releases in the form ``appname-1.2.3``
+and ``appname-1.2.3-scripts``.
+
+For the sake of demonstration, we shall assume that this repository
+hasn't been created yet. The repository then doesn't exist, we should
+create it::
cd "$WIZARD/srv"
mkdir wordpress
@@ -64,6 +70,55 @@ create :file:`$WIZARD/wizard/app/wordpress.py` and fill it in with a bare bones
class Application(app.Application):
pass
+Finally, we have to tell Wizard about this new module. If you are
+creating this new module for Scripts, the easiest way to tell Wizard
+about the application is to add it to the :mod:`wizard_scripts`
+`setuptools plugin `_.
+Even if you don't know anything about setuptools, it's pretty easy
+to add your application: edit the file :file:`plugins/scripts/setup.py`
+and add your application to the ``wizard.app`` entry point by looking
+for the following chunk of code and adding a new line::
+
+ 'wizard.app': ['mediawiki = wizard.app.mediawiki:Application',
+ 'phpBB = wizard.app.phpBB:Application',
+ 'wordpress = wizard.app.wordpress:Application', # NEW LINE!
+ ],
+
+This tells Wizard that there is a new application named ``wordpress``,
+with a module named ``wizard.app.wordpress`` and a class named
+``Application`` in that module, which Wizard should use.
+
+You need to refresh plugin information by running the :file:`refresh.sh`
+script or by running :file:`python setup.py egg_info` in the
+:file:`plugins/scripts` directory.
+
+.. note::
+
+ If you do not want to place your application in the Scripts plugin,
+ you will need to create a :file:`setup.py` file from scratch in your
+ own plugin. A reasonable template file is::
+
+ import setuptools
+
+ setuptools.setup(
+ name = 'wizard-myapp',
+ version = '0.1.dev',
+ author = 'Me',
+ author_email = 'my-email@mit.edu',
+ description = ('My Awesome Application'),
+ license = 'My Awesome License',
+ url = 'http://www.example.com/',
+ packages = setuptools.find_packages(),
+ entry_points = {
+ 'wizard.app': ['wordpress = wizard.app.wordpress:Application',
+ ],
+ }
+ )
+
+ Don't forget to run :file:`python setup.py egg_info` and add your module
+ to your :envvar:`PYTHON_PATH` (otherwise, Wizard won't know that
+ your plugin exists!)
+
Now we are ready to put some code in our repository: the first thing we will
add is the :term:`pristine` branch, which contains verbatim the code from upstream.
@@ -141,14 +196,7 @@ First things first: verify that we are on the master branch::
patch -n0 < /mit/scripts/deploy/wordpress-2.0.2/wordpress.patch
-Then, run the following command to setup a :file:`.scripts` directory::
-
- wizard prepare-new
-
-This directory holds Wizard related files, and is also used by
-:command:`parallel-find.pl` to determine if a directory is an autoinstall.
-
-Finally, if you are running a PHP application, you'll need to setup
+If you are running a PHP application, you'll need to setup
a :file:`php.ini` and symlinks to it in all subdirectories.
As of November 2009, all PHP applications load the same :file:`php.ini` file;
so just grab one from another of the PHP projects. We'll rob our own
@@ -231,25 +279,33 @@ Some tips and tricks for writing :meth:`wizard.app.Application.install`:
to the connection, you can perform implicit execution.
To test if your installation function works, it's probably convenient to
-create a test script in :file:`tests`; :file:`tests/test-install-wordpress.sh`
+create a test script in :file:`tests`; :file:`tests/wordpress-install-test.sh`
in the case of Wordpress. It will look something like::
#!/bin/bash -e
+ cd `dirname $0`
DEFAULT_HEAD=1
- TESTNAME="install_wordpress"
+ TESTNAME="wordpress_install"
source ./setup
wizard install "wordpress-$VERSION-scripts" "$TESTDIR" --non-interactive -- --title="My Blog"
+.. note::
+
+ As you develop more test-scripts, you may find that you are
+ frequently copy pasting install commands. In this case, it may be
+ useful to create a 'wordpress-install' helper shell fragment and
+ source it whenever you need a vanilla installation.
+
``DEFAULT_HEAD=1`` indicates that this script can perform a reasonable
operation without any version specified (since we haven't tagged any of our
commits yet, we can't use the specific version functionality; not that we'd want
-to, though). ``TESTNAME`` is simply the name of the file with the leading
-``test-`` stripped and dashes converted to underscores. Run the script with
+to, though). ``TESTNAME`` is simply the name of the file with the trailing
+``-test`` stripped and dashes converted to underscores. Run the script with
verbose debugging information by using::
- env WIZARD_DEBUG=1 ./test-install-wordpress.sh
+ env WIZARD_DEBUG=1 ./wordpress-install-test.sh
The test scripts will try to conserve databases by running ``wizard remove`` on the
old directory, but this requires :meth:`~wizard.app.remove` be implemented.
@@ -273,7 +329,7 @@ exhibit different behavior depending on server configuration, you should run
the installation on a Scripts server. You can do this manually or use
the test script you created::
- env WIZARD_NO_COMMIT=1 ./test-install-wordpress.sh
+ env WIZARD_NO_COMMIT=1 ./wordpress-install-test.sh
:envvar:`WIZARD_NO_COMMIT` (command line equivalent to ``--no-commit``)
prevents the installer from generating a Git commit after the install, and will
@@ -481,6 +537,7 @@ Here is short version for quick reference:
#. Create the new repository and new module,
#. Implement :meth:`~wizard.app.Application.download`,
+#. Register the application at the ``wizard_scripts`` plugin,
#. *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``,
@@ -490,7 +547,7 @@ Here is short version for quick reference:
#. *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`,
+#. Create :file:`tests/$APP-install-test.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`,