Page "Proposals/BEP-0005" was changed by olemis Diff URL: <https://issues.apache.org/bloodhound/wiki/Proposals/BEP-0005?action=diff&version=4> Revision 4 Comment: [BEP-0005] Improving Proposal section Changes: -------8<------8<------8<------8<------8<------8<------8<------8<-------- Index: Proposals/BEP-0005 ========================================================================= --- Proposals/BEP-0005 (version: 3) +++ Proposals/BEP-0005 (version: 4) @@ -51,35 +51,26 @@ == Proposal #proposal -''Let the plugin implement/indicate only the incremental differences during the environment setup process, leaving everything that might be abstracted and reused to be tackled by the reusable mechanism'' +''Let the plugin implement/indicate only the incremental differences during the environment setup process, leaving everything that might be abstracted and reused to be handled by the reusable mechanism'' === Details: -1. Create a new module bhdashboard.env, to place reusable elements. Create a base class named '''!BaseEnvironmentSetupParticipant''' within it; This class implements trac’s IEnvironmentSetupParticipant and contains all reusable logic regarding the environment upgrade process. -2. Have some component in your plugin extend this base class, and provide concrete information that varies from a plugin to another. Instead of directly implementing '''IEnvironmentSetupParticipant''', the component will override the following methods: +[=#upgrade-core] A new module `bhdashboard.env` will be added in dashboard plugin . Reusable classes will be implemented in there, especially a base class named `BaseEnvironmentSetupParticipant` . This is a mixin class [#refs-03 (1)] implementing `IEnvironmentSetupParticipant` interface . Reusable logic regarding the environment upgrade process will be found in there. + +[=#upgrade-components] Setup participants (i.e. components) in plugins will extend this base class, and provide concrete information that varies from a plugin to another. Instead of directly implementing `IEnvironmentSetupParticipant` interface, the component will override the following inherited methods: + ||=Method =||=Description =|| -||get_db_system_key || To return the value of the key that will be used to store the current plugin's version number in the 'system' table of trac. If not provided will get a default value formed by plugin_name + “_version” suffix. || -||get_plugin_name ||Returns the plugin's name to be used in the logging messages during the current environment setup process. || -||get_plugin_version||To return the current version of the plugin || -||get_db_setup_contributors =||Returns a list of db setup script names, E.g. (‘plugin.upgrades.db0’, ‘plugin.upgrades.db1’). The mechanism here gives the plugin a chance to explicitly indicate the setup scripts that must be used for the setup process. || -[[BR]] +|| `get_db_system_key` || Return the value of the key that will be used to store the current plugin's version number in 'system' table . If not provided then default value will be formed by `<plugin_name>_version suffix. || +|| `get_plugin_name` || Return the plugin's name to be used in the logging messages during the current environment setup process. || +|| `get_plugin_version` || Return the current version of the plugin || +|| `get_db_setup_contributors` || Returns a list of db setup script names, e.g. (`'plugin.upgrades.db0’`, `‘plugin.upgrades.db1’`). The mechanism here gives the plugin a chance to explicitly indicate the setup scripts that must be used for the setup process. || -3. Implement each plugin version’s db upgrade in a separate module accomplishing the following protocol. +[=#upgrade-modules] Each plugin version may be accompanied of specific upgrade tasks (e.g. add table columns, create filesystem folders, ... but not limited to these ...) . They should be written in a separate module. It **must** provide: -The module must provide: ||=Function =||=Description =|| -||get_new_tables() ||To indicate new tables to add to the schema. The returned structure is expected to be similar to trac.db_default.schema variable|| -||get_new_data() ||To indicate initial data to insert into the database. Its return value must be like the one returned by trac.db_default.get_data() function -||do_upgrade() ||To perform any free db upgrade if needed -[[BR]] - - - -4. At least two test scenarios must be verified: -* A complete install from scratch where no version of the plugin exists and a version N is installed -* An incremental install where a first initial install is made and subsequent versions are installed later. - - +|| `get_new_tables` || List new tables to add to the schema. The returned structure is expected to be similar to `trac.db_default.schema` variable || +|| `get_new_data` || Specify initial data to insert into the database. Its return value must be like the one returned by `trac.db_default.get_data` function +|| `do_upgrade` || Perform free db upgrade tasks if needed || == Rationale #rationale @@ -112,32 +103,48 @@ You can find a reference implementation [https://bitbucket.org/jose_angel_franco/bloodhound/compare/bep_0005_plugin_upgrades..default here], within a fork of bhdashboard plugin, a branch named bep_0005_plugin_upgrades has been created to ease the revision process. The diff includes the module bhdashboard.env.py with the implementation of the !BaseEnvironmentSetupParticipant class and the test related modules implementing two test cases for the identified test scenarios.[[BR]] -During the work for #140 this mechanism has been used, the code of bhdashboard.api.!DashboardSystem regarding environment upgrade looks something like this: +As part of the the work for #140 this mechanism has been created , used, and tested . The class `bhdashboard.api.DashboardSystem` will perform environment upgrades like this: + {{{ +#!py + class DashboardSystem(Component, BaseEnvironmentSetupParticipant): -... -#BaseEnvironmentSetupParticipant methods for handling db updates -def get_plugin_name(self): - return 'Bloodhound dashboard' -def get_plugin_version(self): - return 0 #First time installer, should be changed as the version increases + #-------8<------- Code omitted -------8<------- + #BaseEnvironmentSetupParticipant methods -def get_db_setup_contributors(self): - return "bhdashboard.upgrades.db0", #Nothing but a first install for now -... + def get_plugin_name(self): + return 'Bloodhound dashboard' + + def get_plugin_version(self): + #First time installer, should be changed as the version increases + return 0 + + #Nothing but a first install for now + def get_db_setup_contributors(self): + return "bhdashboard.upgrades.db0", + + #-------8<------- Code omitted -------8<------- }}} -Test cases are provided to validate the general reusable algorithm in both scenarios incremental and full plugin upgrade. +Test cases are provided to validate the general reusable algorithm in both scenarios incremental and full plugin upgrade. At least two test scenarios are verified: + + * A complete install from scratch where no version of the plugin exists and a version ''N'' is installed + * An incremental install where a first initial install is made and subsequent upgrades are applied on top of it. == Resources #resources -* Template Method design pattern by GoF [http://www.amazon.com/Design-Patterns-Object-Oriented-Professional-Computing/dp/0201634988 Elements of Reusable Object-Oriented Software] - -* Open / Closed design principle by Robert C. Martin [http://www.amazon.com/Software-Development-Principles-Patterns-Practices/dp/0135974445 Software-Development-Principles-Patterns-Practices] +**TODO** == References #references -[[BR]] + + - [=#refs01] E. Gamma, R.Helm, R.Johnson, J. Vlissides, ''Elements of Reusable Object-Oriented Software'' [[BR]] + ( http://www.amazon.com/Design-Patterns-Object-Oriented-Professional-Computing/dp/0201634988 ) + - [=#refs02] Robert C. Martin, ''Open / Closed design principle'' [[BR]] + ( http://www.amazon.com/Software-Development-Principles-Patterns-Practices/dp/0135974445 Software-Development-Principles-Patterns-Practices ) + - [=#refs03] Mixin class [[BR]] + ( http://en.wikipedia.org/wiki/Mixin ) + TODO: check if there should be a reference here to the ticket related to the use of bhdashboard.!ModelBase._meta as a source for environment upgrades == Copyright #copyright -------8<------8<------8<------8<------8<------8<------8<------8<--------
-- Page URL: <https://issues.apache.org/bloodhound/wiki/Proposals/BEP-0005> Apache Bloodhound <https://issues.apache.org/bloodhound/> The Apache Bloodhound (incubating) issue tracker This is an automated message. Someone added your email address to be notified of changes on 'Proposals/BEP-0005' page. If it was not you, please report to .
