Edgewall Software

Changes between Version 15 and Version 16 of TracDev/PluginDevelopment/ExtensionPoints/trac.env.IEnvironmentSetupParticipant


Ignore:
Timestamp:
Mar 23, 2017, 3:50:01 AM (5 years ago)
Author:
Ryan J Ollos
Comment:

Document some discussion in #8172.

Legend:

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

    v15 v16  
    3232    def environment_created(self):
    3333        self.log.debug("creating environment for sample plugin.")
    34         pass
    3534
    3635    def environment_needs_upgrade(self):
     
    4039    def upgrade_environment(self):
    4140        self.log.debug("upgrading existing environment for sample plugin.")
    42         pass
    4341}}}
    4442
     
    8684
    8785    def environment_created(self):
    88         dbm = DatabaseManager(self.env)
    89         dbm.create_tables(PLUGIN_SCHEMA)
    90         dbm.insert_into_tables(INITIAL_PLUGIN_DATA)
    91         dbm.set_database_version(PLUGIN_VERSION, PLUGIN_NAME)
     86        # Same work is done for environment created and
     87        # upgraded, in almost all use-cases.
     88        self.upgrade_environment()
    9289
    9390    def environment_needs_upgrade(self):
     
    116113
    117114 * [source:trunk/trac/env.py#L556 trac.env.EnvironmentSetup][[br]]
    118    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''.
     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''.
    119116
    120117
     
    132129 * [http://www.edgewall.org/docs/trac-trunk/html/api/trac_env.html#trac.env.IEnvironmentSetupParticipant API Reference]
    133130
    134  * #8172 aims to introduce more helper methods that simplify implementing this interface according to best practices.
     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 with the plugin enabled.
    135132
    136133==== API History
     
    139136  * Added `environment_needs_upgrade` and `upgrade_environment` methods. (changeset:1840)
    140137* 1.1.2 deprecated `db` parameters. (changeset:12829, #11605)
     138* 1.1.5 added database helper methods (#8172)
    141139* 1.3.1 removed `db` parameters. (changeset:14888, #11901)