incubator-bloodhound-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Apache Bloodhound" <bloodhound-...@incubator.apache.org>
Subject [Apache Bloodhound] Proposals/BEP-0005 modified
Date Sun, 27 Jan 2013 19:14:15 GMT
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 .

Mime
View raw message