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 21:26:09 GMT
Page "Proposals/BEP-0005" was changed by olemis
Diff URL: <https://issues.apache.org/bloodhound/wiki/Proposals/BEP-0005?action=diff&version=6>
Revision 6
Comment: [BEP-0005] Improve Rationale section and compatibility TODO
Changes:
-------8<------8<------8<------8<------8<------8<------8<------8<--------
Index: Proposals/BEP-0005
=========================================================================
--- Proposals/BEP-0005 (version: 5)
+++ Proposals/BEP-0005 (version: 6)
@@ -74,30 +74,34 @@
 
 == Rationale #rationale
 
-1.	The design was motivated by the way trac implements its core environment setup: A default_db
module contains default initial schema and data. Subsequent install versions are kept apart
one module per version number. In accordance with the current trac’s version and the current
installed version, those setup upgrades are loaded and ran from current installed version
to current environment’s version. 
+[=#rationale-antecedent] One of the goals of the design was to mimic the way trac implements
its core environment setup: 
 
-2.	A first decision to be made was '''''whether encapsulating upgrade algorithms in classes
or directly in modules.''''' 
-* Classes would allow us to have one class per plugin version no matter they were placed
in a single module each or not. [[BR]]
-* Finally the use of separate modules without classes prevailed taking into consideration
'''''memory use optimization''''', if a version was not to be used; the module and every declared
member on it wouldn’t be loaded at all.
+  * A `default_db` module contains default initial schema and data. 
+  * Subsequent install versions are isolated in one module per version number. 
+  * Considering both installed and current trac’s version only the necessary setup upgrades
are loaded and executed to migrate deployed version towards latest version. 
 
-3.	A second design decision to be made was '''''how to dynamically load the setup upgrade
modules?'''''  
-* This could be done by convection like trac does, the plugin should then have a directory
named “upgrades” and modules within it should be named following the ‘db<version_number>’
convention; this way ‘db0.py’ corresponds to the initial install and ‘dbN.py’ corresponds
to the N version of the plugin.
+[=#rationale-upgrade-modules] A first decision to be made was '''''whether to encapsulate
upgrade algorithms in classes or directly in modules.''''' 
 
-* The decision made was to let the plugin '''''explicitly''''' indicate the names of the
setup script modules, '''''to gain in flexibility.''''' This way setup scripts wouldn’t
be forced to be placed in a single directory. The mere existence of these modules within “upgrades”
directory wouldn’t forcedly indicate they should be used for the install. Been so, the plugin
could indicate that some db upgrade module e.g version n-1 is not to be used during its current
version setup, maybe because the current version’s setup totally overrides the previous
one.
+  * Classes would allow to have one class per plugin version without worrying too much about
whether to place them all in a single module or not.
+  * Finally the use of separate modules without classes prevailed taking into consideration
'''''memory and performance optimization''''', if a version was not to be used; the module
and every declared member on it will not be loaded at all.
 
-4.	 A third decision to be made was '''''whether using !ModelBase._get_schema() to generate
the schema data of the environment setup script or not.'''''
-* Once the benefits of keeping each version of db upgrades separate are clear, saying that
bhdashboard.model.!ModelBase._meta '''''is not version aware''''' should be enough. !ModelBase._meta
has always the last snapshot of  the database schema related to a persistent class. This means
that making a fresh install of version N from scratch works, but making an upgrade from version
n-3 to version n would result a bit difficult, since there is no track of differences between
versions.
+[=#rationale-module-import] A second design decision to be made was '''''how to dynamically
load the setup upgrade modules?'''''  
 
-* Let’s in addition say that the structure of the real database schema could be richer
than what !ModelBase._meta supports. Indicating indexes, size of the columns, data types,
m:n relationships 1:n relationships and so on. !ModelBase._meta is not yet aware of some of
these elements, and maybe it shouldn’t even be, since it doesn’t need many of them at
all '''''(CRUD logic doesn’t really need field size, type or indexes).'''''
- 
-* The only reason why !ModelBase might need some of these elements is to '''''let us generate
the db schema''''' during the env upgrade process.  [[BR]] That  makes us wonder if '''''it
shouldn’t just be the opposite.'''''  Or maybe due to the richness of what a setup script
might imply(take a look a trac.upgrades directory), and the relative independence of !ModelBase
with that upgrade logic, it would be appropriate for !ModelBase to '''''have only the last
snapshot of exactly what it needs''''' while setup scripts make the install magic with as
much details as required.
+  * This could be done by following name conventions just like in ''Trac''. The plugin should
then have a directory named ''upgrades'' and modules within it should stick to `db<version
number>` convention e.g. ‘db0.py’ corresponds to the initial install and ‘dbN.py’
corresponds to the N-th upgrade step of the plugin.
+  * The decision made was to let the plugin '''''explicitly''''' indicate the names of the
setup script modules, '''''to gain in flexibility.''''' This way setup scripts would not be
forced to be placed in a single directory, and might even be reused , if appropriate. The
mere existence of these modules within “upgrades” directory would not indicate that they
should be used as part of the upgrade process. That being said, the plugin could specify that
some database upgrade module e.g version `n-1` is not to be used during a given upgrade path,
maybe because the current version’s setup totally overrides the previous one.
 
-* While no further decision is made over the responsibilities of !ModelBase '''''maybe it
is safe to keep things apart.'''''
+[=#rationale-generate-schema] A third decision to be made was '''''whether using `ModelBase._get_schema()`
to generate the schema data of the environment setup script or not.'''''
+
+  * Once the benefits of keeping each database upgrade step in isolation are understood ,
then saying that `bhdashboard.model.ModelBase._meta` '''''is not version aware''''' is a logical
consequence of that fact. `ModelBase._meta` always declares the last snapshot of  the underlying
schema related to a persistent class. This means that making a fresh install of version `n`
from scratch works, but making an upgrade from version `n-3` to version `n` would be a bit
difficult, since there is no track of differences between versions.
+  * Let’s in addition say that the structure of the real database schema could be more
sophisticated than what `ModelBase._meta` supports (e.g. indexes, columns size, data types,
many-to-many relationships , 1:n relationships , ...) `ModelBase._meta` is not yet aware of
some of these elements, and maybe it shouldn’t even be, since it doesn’t need many of
them at all '''''(CRUD statements do not really need field size, type or indexes).'''''
+  * The only reason why `ModelBase` might be upgraded to support some of these elements is
to '''''let plugin developers generate the db schema''''' during environment upgrade process.
 So there is a question of whether '''''it should just be the opposite.'''''  Due to the expressiveness
needed by setup scripts (consider `trac.upgrades` package by example), and the relative independence
of `ModelBase` with that upgrade logic its appropriate for `ModelBase` to '''''have only the
last snapshot of exactly what it needs''''' . On the other hand setup scripts make the install
magic with as much details as required.
+  * Given the fact that further decisions need to be made regarding the responsibilities
of `ModelBase` class '''''maybe it is better to keep both concerns apart.'''''
 
 
 == Backwards Compatibility #backwards-compatibility
 
 **TODO** verify if there is something needed here
+**answer** yes , please list the possible targets in current code that are good candidates
for upgrade and then sketch how to do it by paying special attention to particularly challenging
details involved in each case , if any .
 
 == Reference Implementation #reference-implementation
 
-------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