Freeway

From ADempiere
Jump to: navigation, search
This Wiki is read-only for reference purposes to avoid broken links.

State: we are finding Actors and Problems

Introduction

ADempiere as well as other database based software has always problems when you upgrade to a new version.

In addition the centrality of the database, that cannot be centralized as the source code, reduces the level of collaborations. Migrations and upgrades are only collateral aspects not the main issues.

Several actors are interested in developing different modules or completely different localizations.

With the source code the same problems are resolved with CVS/SVN. In particular the import command resolves some collaboration issues.

Several solutions to database version have been implemented like Schema Crawler or 2Pack.

The first kind of solution is not feasible for ADempiere as the AD very often differ on many ID, e.g. the AD_Table_ID for My_New_Table is not the same on two databases.

The ladder solution does not resolve conflicts during import between two actors both modifing the AD, e.g. customer's customization could be overwritten by an upgrade.

As an extension of the above problems let assume 100 companies have localized ADempiere over 100 countries. At the moment we can have a huge ADempiere with all 100 localizations inside or each companies is probably going to develop an homemade software for upgrading.

Below you can find the actors hopefully involved with ADempiere. Then we are going to details the problems these actors are supposed to encounter.

After the problems scenario is clear we are going to find a solution.

Analysis

Actors

  • The Adempiere Community: it develops into the main SVN trunk. The framework is improved constantly so developers get more fun with ADempiere and companies find it more and more productive.
  • Geekman: is a developer having fun with ADempiere developing WebService functionalities.
  • Schaeffer: is using ADempiere to run its business and has customized it a lot.
  • Germany Ltd: who has developed the german localization.
  • Mexico SA: who has developed the manufacturing module for ADempiere.
  • Italy spa: who has developed the italian localization.
  • Posterita: who has developed the Posterita POS, ZK Ajax UI, and contributing other modules.

Problem Scenario

  1. The ADempiere community is going quite well however they should syncronize to share IDs below 1000000. It would be worthwhile to avoid it. Some features are not stable enough for production and do not activate them while maintaining them in the main trunk would be usefull.
    • Reserving IDs: suppose Mar develop the Great package reserving IDs from 100..199. In the first version he use IDs from 100 to 150. Alex takes that package and build a new one.
    • Alex should use its own ID range, mixing his IDs with the Mar's IDs.
    • In addition consider that reserving IDs but do not define a policy for "names", I mean Table name, Column names, ..., it is only a way to posticipate the problem.
    • Mar: it seems to me better to use suffix rather than prefix: this way we can have getTotalAmountITA() and getTotalAmountGER() that for developer are better than ITA and GER at the beginning.
  2. Mexico SA is developing manufaturing on a secondary branch. Test its solution it's not straitforward. It could aggregate more and more developer with a friendly module architecture.
  3. Schaeffer is appling modification to AD with SQL scripts instead of directly from the System client, and it's reappling them after every upgrade.
  4. Geekman has developed a great improvement. However it took time for the ADempiere Community to test it and the AD modifications he submitted as contribution should be completely converted to have ID < 1000000 before to be committed to the trunk.
  5. Italy spa and German Ltd are developing on separated SVN and deal with upgrade problems, partially resolved by different homemade software.

Architectural Use Cases

Key points

  1. Distributed development requires a local DB as well as a local repository.
  2. Modifications are recorded in distinct branch into the AD.
  3. Modifications have a status to know if consider them or not during exports.
  4. Modification have a date to export them in order.
  5. More than one developer can connect to the same DB as long as they coordinates to do not conflicts between them.
    • As an extension more than one plugin can be developed in the same DB at the same time.
  6. ADempiere is not required to export/import the AD, this differ from 2Pack and XML2AD.
  7. The framework records what you do so you don't have to write XML file for exports.

Geekman

After reading some very long threads :-) finally he decide to start developing. He has its development server completely separated from the ADempiere community server.

  1. Checkout ADempiere, import the PostgreSQL dump, create a new workspace in eclipse.
  2. The AD_Plugin table contains the informations about all the plugins (name and version) installed in the DB dump. Geekman is going to have this as code base. ADempiere is itself a documented plugin.
  3. He can decide to import some others plugins as a pre-requisite. The AD_Plugin table will be updated by the import process.
  4. Geekman decide to use the suffix "Gee" for everything that can conflict with other developers, e.g. tables, columns, reference names, ...
  5. He also decide the name for his extension: GreatReports .
  6. With this he develop an sql script, main.sql, containing only DDL statement not DML, e.g. alter table but not insert statement.
    • This is general and can be executed on every installation without conflicts.
  7. At the end of the first version of the file he call a low-level function, setVersion() with the name of the plugin and its initial version.
  8. The DB is ok. Now comes the Application Dictionary.
  9. He open the System client and from the branch window create a new line called GreatReports. Than with the button on the same window he make that branch the current one.
    • The state for the branch is "development".
  10. From now on every modification is recorded and tagged GreatReports. The creation of a new line in the branch window also set the start of the branch.
  11. The AD is completly configured.
  12. New it comes the java development.
  13. Everything seems to work and he change the branch status to testing.
  14. ADempiere is been rebuilded and his friend will test the new feature.
  15. After testing the code are commmitted on the SVN and the branch status is setted to "tested".
  16. He can decide or not to tag the source code committed so far, and also tag the branch GreatReport from the Branch window of the System client.

Export the patch:

  1. Ready to exports to send a patch to the ADempiere community!!!
  2. The source code is easy: give the SVN revision number you have used and a .patch file made with your preferred tool.
  3. For the DDL statements is also easy: send the main.sql file.
  4. For the DML statements he use ADdiff a tool that read the modification made to the AD and exports them in XML format. He asks:
    • For a particolar list of plugins, in our case only the GreatReports plugin.
    • For two particular versions of each plugin, in our case GreatPlugin 0.0 and GreatPlugin 1.0
    • Or he can ask only for "tested" plugins.
  5. The source code patch, the main.sql file and the ADiff xml output form the GreatReport 1.0 to be submitted to the ADempiere community.

Apply the patch:

  1. To patch the source code is easy.
  2. To make PostgreSQL happy is also easy with the main.sql file.
    • Conflicts should not happen because of the naming convension used.
  3. ADpatch, the XML import tool runs through all the modifications:
    • For every modification it check if a particular column are in the state it had in the Geekman's database before he started developing.
    • If it matches the modification is applied.
    • If it is modified also on the target DB a conflicts resolution happen.

The GreatReports 2.0:

  1. When basic functionalities are tested he decide to step forward add new tables and columns for the 2.0 version.
  2. In the main.sql script he reports all DDL statement and at the end another call to the setVersion() function that update the AD_Plugin table.

Run the right ADempiere binary code:

  1. Not only the AD_System.Version is checked at startup.
  2. ADempiere at startup checks versions for all installed plugins.
  3. For this there is a property somewhere in the plugin source code matched with the contents of the AD_Plugin table.

To be defined

  1. ADpatch should require ADempiere to work?
    • Answer seems to be "No". Some modifications to the AD could require manual operation in this case.
  2. Conflicts resolution on the AD, e.g. two plugins need to change a particular display logic.
    1. In this case the plugin applied first change the column.
    2. The second plugin can check if the column as the value it aspect before change. In this case it did not. So a conflict is showed. As gentoo emerge command, the plugins is applied however conflicts remain pending and to be applied (see the etc-update command)
  3. False conflicts: some columns like the AD_Field.SeqNo column, are supposed to be exported to preserve the Field sequence on the screen. But every plugin is going to deal with it.
  4. Code organization to avoid CVS/SVN merge.
    • Some improvements to Model Validator.
    • How to extend MInvoice without touching the standard class.
    • Using smaller classes with less responsability: for example InvoiceGenerate contains the invoicing process and also invoice rules. The ladder usually is a custom.
  5. Implement Custom Properties like MMayCustomProperty (see JikiBloom project) to enable/disable features. It's a sort of "#IFDEF" from the C compiler. This is used to:
    • Generally disable unstable features.
    • Control features without adding a column into the database.
  6. Obviously we cannot reserve SeqNo ranges for each developer. :-D
  7. main.sql should be substituted with an engine multi-database to apply metadata changes (alter/create statements).