Asier, I agree with your disagreement (I dislike the ad_callout, ad_info, etc. subfolders in 2.50) but I see a big risk of disparity if we don't have a concrete reference for packaging (functionality packaging is too much open). So we should prioritize this complete and concrete reference for packaging as much as possible.
Ismael -----Mensaje original----- De: Asier Lostalé [mailto:asier.lost...@openbravo.com] Enviado el: martes, 09 de marzo de 2010 17:32 Para: openbravo-development@lists.sourceforge.net Asunto: Re: [Openbravo-development] Proposed guidelines for naming modules Hi, In general I agree with all the rules proposed by Isma, the only one I would change is: -For the structure of source code my suggestion is to keep it stable (using ad_callout, ad_info, etc. folders, but without the erpcommon main folder) till we define and freeze the new 3.0 code structure (it will happen in 2/3 months from now). Once the new structure is defined then I would follow that new structure (again without the need to "fix" all previous modules). This subpackaging inside modules for me is like "type of artifacts" packaging which you propose to avoid. So I would keep for packages inside a module the rule of package taking into account functionality. On 03/07/2010 12:52 PM, Ismael Ciordia, Openbravo wrote: > Gorka, > > you are right, this is a key aspect and we are not following any rule for > packaging and source code structure in our modules. So please all of you read > this message and answer with your opinion. > > For packaging, right now we have several different approaches: > -org.openbravo.modulename (eg. org.openbravo.accrualsanddeferrals, > org.openbravo.idl, org.openbravo.massadvancedpayments) > -org.openbravo.modulename.translation.language (eg. > org.openbravo.idl.translation.es_ES) > -org.openbravo.localization.country (eg. org.openbravo.localization.spain) > -org.openbravo.localization.country.moredetails (eg. > org.openbravo.localization.spain.referencedata.accounts) > -org.openbravo.module.modulename (eg. org.openbravo.module.cifnifvalidator) > -org.openbravo.module.modulename.languagecode (eg. > org.openbravo.module.aeat347.es.es_ES) > -org.openbravo.module.modulename.countrycode (eg. > org.openbravo.module.aeat349.es) > -org.openbravo.modulenameSplitWithDots (eg. > org.openbravo.advancedpayments.pack, > -org.openbravo.technicalCategory.modulename (eg. > org.openbravo.alerts.accounting) > -org.openbravo.functionalCategory.modulename (eg. > org.openbravo.document.massinvoicing, org.openbravo.examples.webservice) > -org.openbravo.gps.modulename (eg. org.openbravo.gps.copyrole) > ... (many others) > > We have to put a common rule and force ourselves to follow it, but: > - changing the package of a module changes the public API of that module so > it should be managed properly. There is no need to fix all our modules now, > but apply the new rule for new modules and only fix current ones if there is > in parallel a relevant change in the module so a new major version is needed > any way. There is no need to add validations for the new rule since it is > internal (only applies for Openbravo modules) > - I don't see the need to have a rigid rule (eg. number of levels might be > different for different modules), but just a rule that help us to package > always in the same way and to avoid collisions between our modules (the > modules packaged in the org.openbravo.xxx, including core). > - we should keep in mind that it is not only for us, other organizations will > use our code as a reference and packaging is typically copied > > These are the rules I propose: > > -I would try to do as light as possible packaging (the less levels the > better) while keeping clear structure > > -Do not use "module" in the packaging, everything is a module (including > core) so it sounds redundant > > -In general modules should not use subpackages of other modules since it > might create a conflict. In particular I would not use subpackages for > modules included in a pack (eg. several modules in spanish localization pack > use as a package that is a subpackages of the spanish localization pack > package). That inclusion is declared in the pack itself and using > subpackaging would create a kind of redundancy (the module could be taken out > from the pack later) or modules originally not designed for the pack could be > included later. > > -The only case where subpackage make sense to me are translations since that > relationship can not be changed. For translations I would not use the word > "translation" but directly the languagecode: > translatedmodulepackage.languageCode (eg. > org.openbravo.document.massinvoicing.es_ES). For translations of core it does > not work (org.openbravo.es_ES) because core package is not clear enough. In > that case I would use org.openbravo.coretranslation.es_ES or just > org.openbravo.core.es_ES) > > -We should not use the "type of artifacts" included in the module for > packaging (eg. org.openbravo.report.xxx or org.openbravo.callout.xxx are > wrong in my opinion). The content of a module should not be defined by the > "technical components" used to implement them but by the functional objective > of the module. It might happen that the functional objective can be reached > in a different manner and it should not force repackaging. In some cases > functional and technical categories might be the same (eg. report) but then I > would put the word "report" in the name of the module but not as a package > (eg. org.openbravo.financial.taxreportXX instead of > org.openbravo.financial.report.taxXX) > > -After all these "don't do's", the difficult "do": in general a package for a > module developed by us should be: > org.openbravo.functionalcategory.modulename > > -In some cases it makes sense to use an additional level: > org.openbravo.functionalcategory.functionalsubcategory.modulename > > -The most difficult part is to use a common set of functional categories and > subcategories (when needed). Each scrum team should define their own list of > categories and subcategories. This could be a starting point (split by teams): > -applicationdictionary (platform) > -kernel (platform) -> although seam module uses base, so we can change to > base (Martin?) > -utility (platform) > -setup (erp engineering) > -common (erp engineering) > -document (erp engineering) -> this one has never been clear, it > consolidates sales and purchase (use them as optional subcategories?) > -warehouse (erp engineering) > -project (erp engineering) > -production (erp engineering) > -mrp (erp engineering) > -financial (erp engineering) > -erputil (erp engineering) > -localization (localization) -> subcategories for each country (eg. > localizatation.spain) > -localizationutil (localization) -> not sure if needed > -quickstart (industry templates / verticals are a category by itself) > -quickstartspain (industry templates / verticals are a category by itself) > > -We should also put a rule for db_prefixes. The idea would be very similar to > packaging. All our modules should use a prefix: > OBXYZ > where X: one character for each category (eg. K for Kernel, F for > Financial) > Y: one character for each subcategory (only if it exists) > Z: from one to 4 characters for the module itself > > -Some examples to illustrate (I've randomly taken several modules from our > CR):: > -Shipments Awaiting Invoice Report would be > org.openbravo.documents.shipmentsawaitinginvoicereport instead of > org.openbravo.reports.shipmentsawaitinginvoice > -3 digits ISO country codes would be org.openbravo.setup.countryisocode > instead of org.openbravo.module.countryisocode > -Tax Report Launcher would be org.openbravo.erputil.taxreportlauncher > instead of org.openbravo.module.taxreportlauncher > -Chart of accounts: PGC 2007 General would be > org.openbravo.localization.spain.generalcoa instead of > org.openbravo.localization.spain.referencedata.accounts > -Módulo de Impuestos para España mejorado would be > org.openbravo.localization.spain.taximprovements instead of > org.openbravo.module.taximprovements.es_ES > -POS Synchronization WebService would be org.openbravo.erputil.possyncws > instead of org.openbravo.service.pos > -Advanced Payments would be org.openbravo.financial.advancedpaymentspack > instead of org.openbravo.advancedpayments.pack > -Booking Control would be org.openbravo.financial.obbo instead of > org.openbravo.obbo > -Openbravo HQL Query Tool would not change: > org.openbravo.utility.hqlquerytool (platform module ;-) > -Validador de CIF y NIF would be > org.openbravo.localization.spain.cifnifvalidator instead of > org.openbravo.module.cifnifvalidator.es_ES > -Direct Debit Form of Payment would be org.openbravo.financial.directdebit > instead of org.openbravo.directdebit > -Chart of accounts: PGC 2007 PYMEs would be > org.openbravo.localization.spain.pymescoa instead of > org.openbravo.localization.spain.referencedata.accounts.pymes > -European Union countries would be org.openbravo.setup.eucountries instead > of org.openbravo.module.eucountries > -Professional Localization pack Spain (España) would be > org.openbravo.localization.spain.professionalpack instead of > org.openbravo.proflocalization.spain > -Skin Module Example would not change: org.openbravo.examples.skinexample > (platform module ;-) > -Condiciones de pago would be > org.openbravo.localization.spain.commonpaymentterms instead of > org.openbravo.spanishdefaultdata.paymentterms > -Camerfactura would be org.openbravo.documents.wscamerfactura instead of > org.openbravo.module.wscamerfactura > -Initial Data Load Spanish (Spain) Translation would be > org.openbravo.setup.idl.es_ES instead of org.openbravo.idl.translation.es_ES > -Taxes: configuration for Spain (Impuestos para España) would be > org.openbravo.localization.spain.commontaxes instead of > org.openbravo.localization.spain.referencedata.taxes > -Electronic Invoice would be org.openbravo.documents.einvoice instead of > org.openbravo.module.einvoice > -Mass Advanced Payments would be > org.openbravo.financial.massadvancedpayments instead of > org.openbravo.massadvancedpayments > -Facturación Electrónica - Facturae 3.1 would be > org.openbravo.documents.facturae31 instead of org.openbravo.module.facturae31 > -Openbravo Multi Business Partner Selector would be > org.openbravo.erputil.multiplebpselector instead of > org.openbravo.utility.multiplebpselector (platform module :-( > -Openbravo QuickStart Spain would be org.openbravo.quickstartspain instead > of org.openbravo.quickstart.spain > -Orders Awaiting Delivery would be > org.openbravo.documents.ordersawaitingdeliveryreport instead of > org.openbravo.reports.ordersawaitingdelivery > -Openbravo Seam would be org.openbravo.kernel.seam instead of > org.openbravo.base.seam > > -For the structure of source code my suggestion is to keep it stable (using > ad_callout, ad_info, etc. folders, but without the erpcommon main folder) > till we define and freeze the new 3.0 code structure (it will happen in 2/3 > months from now). Once the new structure is defined then I would follow that > new structure (again without the need to "fix" all previous modules). > > What do you think? > > Ismael > > -----Mensaje original----- > De: Gorka Ion Damián [mailto:gorkaion.dam...@openbravo.com] > Enviado el: lunes, 15 de febrero de 2010 13:42 > Para: Paolo Juvara > CC: openbravo-development > Asunto: Re: [Openbravo-development] Proposed guidelines for naming > modules > > > Hi All, > > From the developer point of view I miss a section for the java package > and the structure of the module's sources. > > About the java package, just seeing the mods page [1] we can clearly see > that we are following different approaches. All the module sources > published there hava an "org.openbravo.*" package. Some of them are just > "org.openbravo.moduleshortname" while other have another level, > "org.openbravo.reports.moduleshortname" or > "org.openbravo.utility.moduleshortname". I think that we should have > some rules for them. > > And about the sources. There are some modules that have all the sources > in the base folder of the java package, for example the BP Debt > Consolidation [2]. While others try to replicate the folders found on > the org.openbravo.erpCommon folder of core. For example the Orders > Awaiting Delivery report module [3]. I think that we should also set a > policy or guidelines so that we can expect the same structure on all > Openbravo's modules. > > Regards > Gorka Ion > > > > [1] https://code.openbravo.com/erp/mods > [2] > https://code.openbravo.com/erp/mods/org.openbravo.bpdebtconsolidation/file/3bb2b7adff2f > [3] > https://code.openbravo.com/erp/mods/org.openbravo.reports.ordersawaitingdelivery/file/823b06a0672d > Paolo Juvara wrote: > >> All, >> >> as we have now reached a whopping 115 modules published in the Central >> Repository, it starts becoming difficult for end users to find what >> they want in the Module Management window. In future, we will add >> categorization and better search capabilities but for now we need to >> rely on good names and descriptions. >> >> A few months ago, Peter and Gil proposed a set of naming rule but we >> never rolled them out. I now re-propose a new set of rules based on >> their original work. >> If we all agree on these rules, I will add them to the wiki as an >> official reference and we will start enforcing them. >> >> The most controversial rule is enforcing the usage of English for >> module names (but not for module descriptions - note: the Search >> function searches both names and descriptions). The rationale for this >> rule is to enforce some consistency and to allow users not knowing the >> language to know what the feature is about, even if it is not in their >> language (think of the case of a module developed by a Chinese >> developer in Chinese but applicable globally - a Spanish user might >> want to find it and provide a Spanish translation for this module). >> However, I know that not everybody agrees with this rule and possible >> alternatives are: >> >> 1. All module names are in English except for the modules that are >> a translation of another module. For example, the translation of >> the Tax Report Launcher will be called "Generador de >> declaraciones de impuestos" (I believe that this is Ismael's >> recommendation) while the rules below recommend "Tax Report >> Launcher Translation: Spanish Spain (es_ES)" >> 2. The name of a module is in the base language of the module (the >> name of a module in Chinese would be in Chinese). >> >> Please let me know if you have any opinions on this topic and what you >> think of these rules >> >> Thanks, >> >> Paolo >> >> ---------------- >> Naming guidelines for modules. >> >> It is important to select an appropriate name for your module in order >> to make it easier for users to recognize it both in the Forge and in >> the Module Management window. >> Here is a set of naming guidelines that we ask module author to honor: >> >> Branding rules: >> >> * The module name should match the project name in the Forge >> (optional) >> * Module names should not be longer than 5 or 6 words and less >> than 60 character long (optional) >> * Module names cannot contain the word "Openbravo" >> o JSON REST Web Services: CORRECT >> o Openbravo JSON REST Web Services: INCORRECT >> * Exception to the previous rule: modules that Openbravo S.L. >> decides to market as products rather than modules: >> o Openbravo QuickStart Template: CORRECT >> * You do not need to specify the Openbravo version in the module name: >> o Translation: Arabic Saudi Arabia (ar_SA): CORRECT >> o Translation: Arabic Saudi Arabia (ar_SA) for Openbravo >> 2.50: INCORRECT >> * Module names should not contain the word "Module" >> o Copy Role: CORRECT >> o Copy Role Module: INCORRECT >> >> Language and grammar conventions: >> >> * All module names must be in English. The module description and >> help can be in any other language. >> * Non English proper nouns are accepted as part of a module name >> specified in English >> o Tax Report: Modelo 349 (Spain): CORRECT >> o Tax Report: Form 349 (Spain): INCORRECT (rationale: Modelo >> 349 is a proper noun and should not be translated) >> o Informe Fiscal: Modelo 349 (Spain): INCORRECT >> * The module help must be different than the module description >> * Grammatically, module names should be consider proper nouns and >> you should capitalize the first letter of every word in the >> module name (with the exception of short words and acronyms) >> o Initial Data Load: CORRECT >> o Initial data load: INCORRECT >> o Direct Debit Form of Payment: CORRECT >> o Direct Debit Form Of Payment: INCORRECT >> o Three Digits ISO Country Codes: CORRECT >> o Three Digits Iso Country Codes: INCORRECT >> * You should avoid using numeric characters to express quantities >> (they are OK in codes and dates) >> o Three Digits ISO Country Codes: CORRECT >> o 3 Digits ISO Country Codes: INCORRECT >> o Chart of Accounts - PGC 2007 General: Spain: CORRECT >> o Tax Report: Modelo 349 - Spain >> * Module names should not end with a full stop: >> o Initial Data Load: CORRECT >> o Initial Data Load.: INCORRECT >> * Module description should end with a full stop >> o Generador de declaraciones de impuestos. Traducción al >> español (español España) del módulo Tax Report Launcher.: >> CORRECT >> o Generador de declaraciones de impuestos. Traducción al >> español (español España) del módulo Tax Report Launcher: >> INCORRECT >> >> Specific types of modules: >> >> * Core translations (translation of Openbravo Core) should follow >> the convention: >> o "Translation: $LANG $COUNTRY ($CODE)" >> o Example: Translation: Arabic Saudi Arabia (ar_SA) >> * Module translations (translations of modules other than >> Openbravo Core) should follow the convention: >> o "$MODULE NAME Translation: $LANG $COUNTRY ($CODE)" >> o Example: Tax Report Launcher Translation: Spanish Spain >> (es_ES) >> * The description for module translations should include an >> appropriate translation of the module name in the target >> language as well as both the name of the language and the name >> of the country in the target language: >> o Example: >> + Name: Tax Report Launcher Translation: Spanish Spain >> (es_ES) >> + Description: Generador de declaraciones de >> impuestos. Traducción al español (español España) >> del módulo Tax Report Launcher. >> * Chart of accounts modules should follow the convention: >> o "Chart of Accounts: $COUNTRY" >> o Example: Chart of Accounts: France >> * For countries with multiple charts of accounts, use the conventions >> o "Chart of Accounts: $TYPE - $COUNTRY" >> o Example: Chart of Accounts: PGC 2007 General - Spain >> o Example: Chart of Accounts: PGC 2007 PYMEs - Spain >> * Tax configuration modules should follow the convention: >> o "Tax Configuration: $COUNTRY" >> o Example: Tax Configuration: France >> * Tax report modules should follow the convention: >> o "Tax Report: $FORM_NAME - $COUNTRY" >> o Example: Tax Report: Modelo 347 - Spain >> * Region modules should follow the convention: >> o "Regions: $COUNTRY" >> o Examples: "Regions: Brazil" >> o NOTE: whenever the regions of a country are called >> something other than regions, you can use the correct term >> in the module description. Example: >> + Name: Regions: United States of America >> + Description: US states. >> * Report modules (other than tax reports) should follow the >> convention: >> o "Report: $REPORT_NAME" >> o Example: Report: Shipments Awaiting Invoice >> * Skin modules should follow the convention: >> o "Skin: $SKIN_NAME" >> o Example: Skin: Blue Sea >> * Tutorial modules (provided as examples to illustrate how to >> develop modules) should follow the convention: >> o "Tutorial: $TUTORIAL NAME" >> o Example: Tutorial: Solitaire >> * NOTE: in future, we might use these naming convention to >> automatically categorize modules based on tags. >> >> ------------------------------------------------------------------------ >> >> ------------------------------------------------------------------------------ >> The Planet: dedicated and managed hosting, cloud storage, colocation >> Stay online with enterprise data centers and the best network in the business >> Choose flexible plans and management services without long-term contracts >> Personal 24x7 support from experience hosting pros just a phone call away. >> http://p.sf.net/sfu/theplanet-com >> ------------------------------------------------------------------------ >> >> _______________________________________________ >> Openbravo-development mailing list >> Openbravo-development@lists.sourceforge.net >> https://lists.sourceforge.net/lists/listinfo/openbravo-development >> >> > ------------------------------------------------------------------------------ > SOLARIS 10 is the OS for Data Centers - provides features such as DTrace, > Predictive Self Healing and Award Winning ZFS. Get Solaris 10 NOW > http://p.sf.net/sfu/solaris-dev2dev > _______________________________________________ > Openbravo-development mailing list > Openbravo-development@lists.sourceforge.net > https://lists.sourceforge.net/lists/listinfo/openbravo-development > > > ------------------------------------------------------------------------------ > Download Intel® Parallel Studio Eval > Try the new software tools for yourself. Speed compiling, find bugs > proactively, and fine-tune applications for parallel performance. > See why Intel Parallel Studio got high marks during beta. > http://p.sf.net/sfu/intel-sw-dev > _______________________________________________ > Openbravo-development mailing list > Openbravo-development@lists.sourceforge.net > https://lists.sourceforge.net/lists/listinfo/openbravo-development > ------------------------------------------------------------------------------ Download Intel® Parallel Studio Eval Try the new software tools for yourself. Speed compiling, find bugs proactively, and fine-tune applications for parallel performance. See why Intel Parallel Studio got high marks during beta. http://p.sf.net/sfu/intel-sw-dev _______________________________________________ Openbravo-development mailing list Openbravo-development@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/openbravo-development ------------------------------------------------------------------------------ Download Intel® Parallel Studio Eval Try the new software tools for yourself. Speed compiling, find bugs proactively, and fine-tune applications for parallel performance. See why Intel Parallel Studio got high marks during beta. http://p.sf.net/sfu/intel-sw-dev _______________________________________________ Openbravo-development mailing list Openbravo-development@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/openbravo-development
