~launchpad-pqm/launchpad/devel

Sample data

===========

There are two sorts of sample data. One used by developers when playing around

in http://launchpad.dev and another used by our tests.

The sample data used by default in http://launchpad.dev is stored as a SQL

file called current-dev.sql, in this same directory. That data is loaded into

the launchpad_dev DB and you can change it as you like, as its main purpose is

to aid developers experimenting all features of Launchpad.

Sample data for tests is stored as a SQL file called current.sql, under this

same directory. This data is loaded into the launchpad_ftest_template and

launchpad_ftest_playground DBs. The former is used by our test runner and the

latter can be accessed through http://launchpad.dev when you run the web app

using the test-playground config (i.e. make LPCONFIG=test-playground run),

so that you can see the world as one of our tests would.

Changing sample data

--------------------

For non trivial modifications, it is best if you store your sample

data modifications as a .sql script of INSERT, UPDATE and DELETE statements.

This is so when you want to commit your changes it is a simple case

of building a fresh batch of sample data, running your script, and

making a fresh sampledata snapshot. This ensures that only the changes you

want to make are made, as well as saving you time if somebody else updates

the sample data while you are working.

To update the sample data:

    1.  Go to the db schema directory:

            cd database/schema

    2.  Make a database with the current sample data:

            make

    3a. Connect to the db, and then do any INSERT or UPDATE commands you need:

            psql -d launchpad_dev -f my_sample_data_mods.sql

        If, for any reason, you want to change the sample data used for tests,

        you should replace launchpad_dev with launchpad_ftest_playground on

        the line above.

        If there are errors, fix and start again.

    3b. Alternatively, use 'make harness' to connect to the database and use

        any APIs you need:

            make harness

        Or:

            make harness LPCONFIG=test-playground

    4.  Make a fresh snapshot of the sample data to newsampledata.sql:

            make newsampledata

    5.  Inspect the new sample data:

            cd ../sampledata

            diff current-dev.sql newsampledata-dev.sql

        If your changes are to the sampledata used for tests, the files

        above will be named current.sql and newsampledata.sql instead.

    6.  If it passes your sanity checks, just copy it over the existing one:

            cp newsampledata-dev.sql current-dev.sql

        Or

            cp newsampledata.sql current.sql

        if your changes are to the sample data used for tests.

    7.  Ensure the tests still pass:

            cd ../..

            make check  # Yeah, yeah, we all know our machines can stand that.

    8.  Commit your changes and submit for review:

            bzr commit -m 'Added frotz to sampledata..."

            bzr push

            bzr review-submit ...