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 08:36:07 GMT
Page "Proposals/BEP-0005" was changed by olemis
Diff URL: <https://issues.apache.org/bloodhound/wiki/Proposals/BEP-0005?action=diff&version=3>
Revision 3
Comment: [BEP-0005] A few more words in Abstract and Motivation sections
Changes:
-------8<------8<------8<------8<------8<------8<------8<------8<--------
Index: Proposals/BEP-0005
=========================================================================
--- Proposals/BEP-0005 (version: 2)
+++ Proposals/BEP-0005 (version: 3)
@@ -4,7 +4,7 @@
 [[PageOutline]]
 
 || '''BEP''' || 5 ||
-|| '''Title''' || Plugin upgrade facility ||
+|| '''Title''' || Plugin upgrade infrastrcuture ||
 || '''Version''' ||  ||
 || '''Last-Modified''' ||  ||
 || '''Author''' || José Angel Franco Navarro <jangel.franco@gmail.com> ||
@@ -18,45 +18,40 @@
 
 == Abstract #abstract
 
-Plugin upgrades is a reusable mechanism to provide trac plugins an upgrade process similar
to the core upgrade process of trac itself. [[BR]]
-The upgrade code of each new version of the plugin can be encapsulated in a separate module,
the mechanism dynamically loads the modules and consistently uses them as indicated for each
plugin version. The amount of coding needed in the plugin is reduced as much as possible,
since repetitive code related to the upgrade process is handled in a reusable manner.
-[[BR]]
-Test cases are provided to validate the general reusable algorithm in both scenarios incremental
and full plugin upgrade.
+This proposal is about a reusable mechanism for Plugin upgrades . It is aimed at providing
Apache™ Bloodhound plugins with an upgrade process similar to the core upgrade process of
''Trac'' itself.
 
-
+The upgrade procedure of each new version of the plugin can be encapsulated in a separate
module. The mechanism dynamically loads the modules and consistently uses them as indicated
for each plugin version. The amount of coding needed in the plugin is reduced since repetitive
code related to the upgrade process is written once and reused in many other places.
 
 == Motivation ==
 
-An important motivation is been that of simplifying as much as possible the plugins concrete
work regarding the environment upgrade by reusing steps of the upgrade algorithm that would
be otherwise strong candidates for code repetition between plugins.
+An important motivation is to simplify as much as possible the plugins concrete work regarding
the environment upgrade by reusing steps of the upgrade algorithm that would be otherwise
repeated over and over.
 
-Till now, some class in the plugin must implement trac’s IEnvironmentSetupParticipant interface.
 The operation '''environment_needs_upgrade''' implemented in this class would have a very
similar implementation across plugins, it would be something like:
+Till now, some class in the plugin must implement trac’s IEnvironmentSetupParticipant interface.
 The method `environment_needs_upgrade` of this class would have a very similar implementation
across plugins, it would be something like:
 
-•	Query for installed version
-•	Check if installed version is greater than current plugins version, raising error if
it is
-•	Check if current plugin’s version is greater than installed version and if so, environment
does need to be upgraded
+  1. Query for installed version
+  2. Check if installed version is greater than current plugins version, raising error if
it is
+  3. Check if current plugin’s version is greater than installed version and if so, environment
does need to be upgraded
 
-There is an opportunity here to introduce some Template Method (GoF), leaving the plugin
the space to indicate its name and its current version number, the rest of the algorithm could
be reused avoiding code repetition.
+There is an opportunity here to introduce some Template Method (GoF) and let the plugin to
indicate its name and current version number. The rest of the algorithm will be straightforward
and should not be repeated.
 
-The operation '''upgrade_environment''' of IEnvironmentSetupParticipant  is likely to be
implemented providing new tables to the schema (generally if it is the first fresh install)
inserting new/default data to the tables specified and/or performing some unstructured database
update (e.g. changing field types, adding new columns, updating existent data values).
+The operation `upgrade_environment` of `IEnvironmentSetupParticipant`  is likely to consist
in providing new tables to the schema (generally if it is the first fresh install) inserting
new/default data to the tables specified and/or performing some unstructured database update
(e.g. changing field types, adding new columns, updating existing data values ... but not
limited to these ...).
 
-In current implementations like '''multiproduct.api.!MultiProductSystem''', you can see the
code making if statements evaluating if the current version is the first one, else if it is
the second one to alternatively create schema tables or simply perform the upgrade block related
to the new version.
+In current implementations like `multiproduct.api.MultiProductSystem` it is possible to notice
many conditional statements to decide whether the current version is the first one, the second
one ... and so on . All this in spite of deciding whether to create tables or just perform
the upgrade operations related to the new version.
 
-'''What will happen once there get to be several versions of the plugin?''' Each one of them
could require new tables, new data, and/or modification to the existing schema or data.
+'''What will happen once several versions of the plugin have been rolled out ?''' Each one
of them could require new tables, new data, and/or modification to the existing schema or
data. Hence there will be a need to change the already functioning code all the time. 
 
-There will possibly be a need to constantly change the already functioning code. 
+The possible improvement here comes with the application of the Open Close design principle;
the existing code would not need to change if each new block of changes regarding each new
plugin version is isolated. So the design and code gets open for extensions and closed for
modifications as the design principle states.
 
-The possible improvement here comes with the application of the Open Close design principle;
the existing code wouldn’t need to change if each new block of changes regarding each new
plugin version is kept separately. So the design and code gets Open for extensions and closed
for modifications as the design principle states.
+When the upgrade process finishes, the plugin needs to update the system table indicating
the current version has been installed. This step once again is a candidate for code repetition
across plugins. 
 
-When the upgrade process finishes, the plugin needs to update the system table indicating
the current version has been installed. This step once more is a candidate for code repetition
across plugins. 
+All along the process, the plugin might also need to register logs, and that is yet another
aspect to reuse.
 
-All along the process, the plugin might have the need to register logs, and that is yet another
aspect to reuse.
-
-Every fragment of code that is mentioned to be exposed to copy+paste between different plugins,
is a point for possible bugs to be injected. The whole upgrade algorithm of the plugin inside
a single upgrade operation, when version numbers increase, is also error prone, it affects
both maintainability and testability. 
+Every fragment of code that is mentioned to be prone to copy+paste between different plugins,
is a point for possible bugs to be injected thus jeopardizing smooth upgrades . As version
numbers increase, putting the whole upgrade algorithm inside a single upgrade operation is
also error prone. It has a negative impact on both maintainability and testability. 
 
 
 == Proposal #proposal
-=== Summary:
-''Let the plugin implement/indicate only what is variable during the environment setup process,
leaving everything that might be abstracted and reused in the hands of 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 tackled 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.
@@ -133,8 +128,7 @@
 ...
 }}}
 
-
-
+Test cases are provided to validate the general reusable algorithm in both scenarios incremental
and full plugin upgrade.
 
 == Resources #resources
 
-------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