site_admin_notes.txt

Stuff that only site admins need to know
----------------------------------------

                      Configuring rounds etc
                      ======================

The file pinc/stages.inc defines the site's set of 'stages' ('rounds' and
'pools'), and their various characteristics (id, full name, entrance
requirements, description, etc).  As shipped, it defines the set of stages
used at www.pgdp.net, but as part of configuring your site (i.e., before
creating any real projects), you can edit the file to set things up the way
you want them for your site.

For documentation on the parameters for the Stage(), Round(), and Pool()
constructors, see pinc/Stage.inc, pinc/Round.inc, and pinc/Pool.inc.

Currently, database fields containing round-ids are declared as CHAR(2)
because that's all we need at www.pgdp.net. If you want to have a longer
round-id, you'll have to change the database in a few places. For example,
to allow a three-character round-id, you'd need to do:
    ALTER TABLE page_events      MODIFY COLUMN round_id   CHAR(3);
    ALTER TABLE queue_defns      MODIFY COLUMN round_id   CHAR(3);
    ALTER TABLE wordcheck_events MODIFY COLUMN round_id   CHAR(3);
    ALTER TABLE best_tally_rank  MODIFY COLUMN tally_name CHAR(3);
    ALTER TABLE current_tallies  MODIFY COLUMN tally_name CHAR(3);
    ALTER TABLE past_tallies     MODIFY COLUMN tally_name CHAR(3);
    ALTER TABLE site_tally_goals MODIFY COLUMN tally_name CHAR(3);
The PHP code shouldn't need any changes, though.

Once your site is running, certain changes become problematic:
    - changing the id of a stage
    - changing the order of stages
    - adding or removing a stage
(Especially if the stage is a round. If it's a pool there are fewer problems.)
It can be done, but it isn't as simple as just running a script. We're hoping
that a future redesign will make such changes easy.


                      Manual database changes
                      ========================

There are several maintenance procedures for which we haven't yet bothered to
make a web interface. Instead, a site admin must tweak the database "by hand",
e.g. via the 'mysql' command-line client, or via phpMyAdmin (if you have it
installed).

Notes on the SQL commands shown here:

 -- If your SQL installation has multiple databases, you have to be using the
    correct one, i.e. the one whose name is bound to _DB_NAME in your
    configuration.sh. For example, if that name is 'dp_main', you could issue
    the command "USE dp_main", or invoke 'mysql' with "-D dp_main", or select
    dp_main from the database list in phpMyAdmin, etc.

 -- A word in ALL-CAPS indicates where you need to substitute a specific
    value. E.g., if the command says
        username='USERNAME'
    you might actually type
        username='joe'


Granting/revoking privileges:
-----------------------------
See tools/site_admin/manage_site_access_privileges.php for a web interface
to grant/revoke privileges.


Setting daily goals for the rounds:
-----------------------------------

You don't need to set daily goals (in effect, they default to zero), but if
you want to, here's how. For each round that you want to set a goal for:
    insert into site_tally_goals
    set date='YYYY-MM-DD', tally_name='ROUND_ID', goal='GOAL'
where YYYY-MM-DD is today's date, or whatever date you want to be the first
day of goal-setting. Then if you have the site crontab set up to run
crontab/extend_site_tally_goals.php each day, it will ensure that the latest
goals are duplicated to 35 days in the future.

When you want to change the goal for a round:
    update site_tally_goals
    set goal='NEW_GOAL'
    where tally_name='ROUND_ID' and date >= 'YYYY-MM-DD'
where YYYY-MM-DD is the effective date of the change.


Defining queues:
----------------
You don't have to define queues: if there are no queues defined for a round,
projects in the round's 'waiting for release' state will automatically (the
next time automodify.php runs) transition to the 'available for work' state.

But if you want to:
    insert into queue_defns
    set round_id='ROUND_ID',
        enabled='1',
        name='NAME',
        comment='COMMENT',
        project_selector='PROJECT_SELECTOR',
        projects_target=PROJECTS_TARGET,
        pages_target=PAGES_TARGET,
        ordering='NNN'
where
 -- NAME is a shortish name for the queue (i.e., a name for the set of
    projects that it deals with).

 -- COMMENT is a longer description, if desired.

 -- PROJECT_SELECTOR is the condition you would put in a SQL WHERE-clause
    to select the projects that this queue deals with. E.g.
        project_selector = '(genre="Non-Fiction" or genre="Other")'
    Below, we refer to these as "selected projects".

 -- PROJECTS_TARGET and PAGES_TARGET are numbers that together specify the
    conditions under which this queue should release one of its waiting
    projects, as follows.

    When automodify.php runs, it considers each queue (in order), and counts
    two quantities:
     -- 'relevant projects': selected projects that are currently in the
        round's 'available for work' state.
     -- 'relevant pages': unproofed pages in relevant projects.
        ("unproofed" = "in any state other than saved-as-done")

    If the number of relevant projects is less than the queue's
    projects_target, or the number of relevant pages is less than its
    pages_target, then automodify.php will attempt to release a project
    from that queue. (It might not succeed, for various reasons.)

    A queue's targets shouldn't be thought of as minima or maxima, as there
    are circumstances in which a relevant quantity can be more or less
    than the corresponding target.

    Example 1:
        projects_target = 2, pages_target = 100
    says that the queue should release a project if there are fewer than 2
    relevant projects or if there are fewer than 100 relevant pages.

    Example 2:
        projects_target = 2, pages_target = 0
    says that the queue should release a project if there are fewer than 2
    relevant projects or if there are fewer than 0 relevant pages. But since
    there can never be fewer than 0 relevant pages, the release condition is
    just that there are fewer than 2 relevant projects.

    Example 3:
        projects_target = 0, pages_target = 0
    says that the queue should never release a project. This has about the
    same effect as disabling the queue (setting 'enabled' to 0).

 -- NNN is an integer that determines the order in which this queue is
    processed. If queues' project_selectors are completely independent (i.e.,
    they have no selected projects in common), then this doesn't matter, but
    if there is overlap, then it becomes important. If an earlier queue
    releases a project, that may prevent a later queue from releasing.


Special Days
------------
You don't have to define any special days. If you want to, you can use
tools/site_admin/manage_special_days.php


                           Miscellaneous
                           =============

Genres:
-------
To change the set of genres, you have to edit the pinc/genres.inc file.


# vim: sw=4 ts=4 expandtab