Edgewall Software

Changes between Version 17 and Version 18 of TracDev/PluginDevelopment/ExtensionPoints/trac.env.IEnvironmentSetupParticipant


Ignore:
Timestamp:
Mar 24, 2017, 6:29:40 AM (5 years ago)
Author:
Ryan J Ollos
Comment:

Minor edits.

Legend:

Unmodified
Added
Removed
Modified
  • TracDev/PluginDevelopment/ExtensionPoints/trac.env.IEnvironmentSetupParticipant

    v17 v18  
    88== Purpose
    99
    10 Responsibilities of the interface are to both participate in the creation of a new environment and during upgrade of an existing environment. This includes adding information to the database schema, such as table declarations and so on. Some implementations, see below, might also opt in for adding default data to the newly created database, or to set up the folder where the environment will be created in.
     10Responsibilities of the interface are to both participate in the creation of a new environment and during upgrade of an existing environment. This includes adding information to the database schema, such as table declarations and so on. Some implementations, see below, might also add default data to the newly created database, or modify content in the environment directory.
    1111
    1212On environment upgrade, the responsibilities of the participant are to non-destructively migrate existing user data to a newer database schema, provided that the data model has changed at the SQL level, and of course to migrate the environment's folder structure and content to meet the requirements of the participant.
     
    1414== Usage
    1515
    16 Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment].
     16Implementing the interface follows the standard guidelines found in TracDev/ComponentArchitecture and of course TracDev/PluginDevelopment.
    1717
    1818== Examples
     
    2121
    2222{{{#!python
    23 from trac.core import implements, Component
     23from trac.core import Component, implements
    2424from trac.env import IEnvironmentSetupParticipant
    2525
     
    112112== Available Implementations
    113113
    114  * [source:trunk/trac/env.py#L556 trac.env.EnvironmentSetup][[br]]
    115    This is the setup participant that will initialize the trac database and also the sample configuration provided with each trac instance, providing sane initial defaults for use with both an existing environment and a newly created one. For the creation of a new environment it uses [source:trunk/trac/db_default.py the default db structure]. and on upgrade it will use [source:trunk/trac/upgrades a db upgrade path] defined in the individual `db*.py` modules therein. The version number of the trac database schema is available from the ''system'' table, the key to look for is ''database_version.'' The value of this system property will be updated on environment upgrade. In addition to that, trac will also keep track of the initial database version that was installed when first creating the environment. The key to look for in the ''system'' table is ''initial_database_version''.
     114 * [source:trunk/trac/env.py#L727 trac.env.EnvironmentSetup][[br]]
     115   This is the setup participant that will initialize the Trac database and also the sample configuration provided with each Trac instance, providing sane initial defaults for use with both an existing environment and a newly created one. For the creation of a new environment it uses [source:trunk/trac/db_default.py the default db structure]. and on upgrade it will use [source:trunk/trac/upgrades a db upgrade path] defined in the individual `db*.py` modules therein. The version number of the Trac database schema is available from the ''system'' table, the key to look for is ''database_version.'' The value of this system property will be updated on environment upgrade. In addition to that, Trac will also keep track of the initial database version that was installed when first creating the environment. The key to look for in the ''system'' table is ''initial_database_version''.
    116116
    117117
     
    122122
    123123 * On upgrade the existing help pages in the wiki will not be updated[[br]]
    124    This is currently not being addressed by trac's default environment setup participant, as it is implemented in a different component. However, there is a proposed [wiki:TracDev/Proposals/NewHelp new help system] that would externalize all help pages to static resources in the filesystem.
    125    Note: in order to also upgrade existing wiki pages that will be installed by the system by default, you will have to run ''trac-admin <env-dir> wiki upgrade.''
    126 
     124   This is currently not being addressed by Trac's default environment setup participant. In order to also upgrade the help pages, you must run ''trac-admin <env-dir> wiki upgrade.'' However, there is a proposed [wiki:TracDev/Proposals/NewHelp new help system] that would externalize all help pages to static resources in the filesystem.
    127125 * comment:19:ticket:10779 and following discuss that IEnvironmentSetupParticipants are not ordered. Also they should be carefully written not to expect a particular version of the database schema, components or other code that is not guaranteed to be compatible with the upgrade.
    128126 
    129127 * [http://www.edgewall.org/docs/trac-trunk/html/api/trac_env.html#trac.env.IEnvironmentSetupParticipant API Reference]
    130128
    131  * `environment_created` is only called for a plugin if the plugin is enabled at the time the environment is created. To have a plugin enabled at the time the environment is created the `--inherit` (comment:42:ticket:8172) or `--config` (//since 1.2//) argument must be used to specify a configuration that enables the plugin.
     129 * `environment_created` is only called for a plugin if the plugin is enabled at the time the environment is created. To have a plugin enabled at the time the environment is created the `--inherit` (comment:42:ticket:8172) or `--config` (//since 1.2//) argument must specify a configuration that enables the plugin.
    132130
    133131==== API History