View source for Naming guidelines for modules

=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. 
 
In future, Openbravo may also use these naming convention to automatically categorize modules based on tags, therefore it is important that these naming conventions are followed. 

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"
**JSON REST Web Services:   <span style="background: #51990F; color: white;">CORRECT</span>
**Openbravo JSON REST Web Services:   <span style="background: #FF0000; color: white;">INCORRECT</span>
* Exception to the previous rule: modules that Openbravo S.L. decides to market as products rather than modules:
**Openbravo QuickStart Template:   <span style="background: #51990F; color: white;">CORRECT</span>
* You do not need to specify the Openbravo version in the module name:
**Translation: Arabic Saudi Arabia (ar_SA):   <span style="background: #51990F; color: white;">CORRECT</span>
**Translation: Arabic Saudi Arabia (ar_SA) for Openbravo 2.50:   <span style="background: #FF0000; color: white;">INCORRECT</span>
* Module names should not contain the word "Module"
**Copy Role:   <span style="background: #51990F; color: white;">CORRECT</span>
**Copy Role Module:   <span style="background: #FF0000; color: white;">INCORRECT</span>

==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
**Tax Report: Modelo 349 (Spain):   <span style="background: #51990F; color: white;">CORRECT</span>
**Tax Report: Form 349 (Spain):   <span style="background: #FF0000; color: white;">INCORRECT</span> (rationale: Modelo  349 is a proper noun and should not be translated)
**Informe Fiscal: Modelo 349 (Spain):   <span style="background: #FF0000; color: white;">INCORRECT</span>
* The module help must differ from the module description
* Grammatically, module names should be treated as proper nouns and you should capitalize the first letter of every word in the module name (with the exception of short words and acronyms)
**Initial Data Load:   <span style="background: #51990F; color: white;">CORRECT</span>
**Initial data load:    <span style="background: #FF0000; color: white;">INCORRECT</span>
**Direct Debit Form of Payment:   <span style="background: #51990F; color: white;">CORRECT</span>
**Direct Debit Form Of Payment:   <span style="background: #FF0000; color: white;">INCORRECT</span>
**Three Digits ISO Country Codes:   <span style="background: #51990F; color: white;">CORRECT</span>
**Three Digits Iso Country Codes:   <span style="background: #FF0000; color: white;">INCORRECT</span>
* You should avoid using numeric characters to express quantities (they are OK in codes and dates)
**Three Digit ISO Country Codes:   <span style="background: #51990F; color: white;">CORRECT</span>
**3 Digit ISO Country Codes:   <span style="background: #FF0000; color: white;">INCORRECT</span>
**Chart of Accounts - PGC 2007 General: Spain:   <span style="background: #51990F; color: white;">CORRECT</span>
**Tax Report: Modelo 349 - Spain
* Module names should not end with a full stop:
**Initial Data Load:   <span style="background: #51990F; color: white;">CORRECT</span>
**Initial Data Load.:   <span style="background: #FF0000; color: white;">INCORRECT</span>
* Module description should end with a full stop
**Generador de declaraciones de impuestos. Traducción al  español (español España) del módulo Tax Report Launcher.:    <span style="background: #51990F; color: white;">CORRECT</span>
**Generador de declaraciones de impuestos. Traducción al  español (español España) del módulo Tax Report Launcher:    <span style="background: #FF0000; color: white;">INCORRECT</span>

==Specific types of modules:==

* Core translations (translation of Openbravo Core) should follow the convention:
**"Translation: $LANG $COUNTRY ($CODE)"
**Translation: Arabic Saudi Arabia (ar_SA) <span style="background: #51990F; color: white;">CORRECT</span>
* Module translations (translations of modules other than Openbravo Core) should follow the convention:
**"$MODULE NAME Translation: $LANG $COUNTRY ($CODE)"
**Tax Report Launcher Translation: Spanish Spain  (es_ES) <span style="background: #51990F; color: white;">CORRECT</span>
* 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:
**+ 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. <span style="background: #51990F; color: white;">CORRECT</span>
* Chart of accounts modules should follow the convention:
**"Chart of Accounts: $COUNTRY"
**Chart of Accounts: France <span style="background: #51990F; color: white;">CORRECT</span>
* For countries with multiple charts of accounts, use the conventions
**"Chart of Accounts: $TYPE - $COUNTRY"
**Chart of Accounts: PGC 2007 General - Spain <span style="background: #51990F; color: white;">CORRECT</span>
**Chart of Accounts: PGC 2007 PYMEs - Spain <span style="background: #51990F; color: white;">CORRECT</span>
* Tax configuration modules should follow the convention:
**"Tax Configuration: $COUNTRY"
**Tax Configuration: France <span style="background: #51990F; color: white;">CORRECT</span>
* Tax report modules should follow the convention:
**"Tax Report: $FORM_NAME - $COUNTRY"
**Tax Report: Modelo 347 - Spain <span style="background: #51990F; color: white;">CORRECT</span>
* Region modules should follow the convention:
**"Regions: $COUNTRY"
**"Regions: Brazil" <span style="background: #51990F; color: white;">CORRECT</span>
**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:
**"Report: $REPORT_NAME"
**Report: Shipments Awaiting Invoice <span style="background: #51990F; color: white;">CORRECT</span>
* Skin modules should follow the convention:
**"Skin: $SKIN_NAME"
**Skin: Blue Sea <span style="background: #51990F; color: white;">CORRECT</span>
* Tutorial modules (provided as examples to illustrate how to develop modules) should follow the convention:
**"Tutorial: $TUTORIAL NAME"
**Tutorial: Solitaire <span style="background: #51990F; color: white;">CORRECT</span>

=Packaging=

*Do not use "module" in the packaging, everything is a module (including core) so this would be redundant

*In general modules should not use subpackages of other modules since it might create a conflict. In particular do not use subpackages for modules included in a pack (eg. several modules in the spanish localization pack use as a package that is a subpackage 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 a subpackage makes sense are translations since that relationship can not be changed. 
*For translations do not use the word "translation" but directly the language code: 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 use org.openbravo.coretranslation.es_ES or just org.openbravo.core.es_ES)

* Do not use the "type of artifacts" included in the module for packaging (eg. org.openbravo.report.xxx or org.openbravo.callout.xxx are wrong). 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 are the same (eg. report) - in this case 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)

*A package for a module developed by Openbravo S.L.U. and staff should be:
  org.openbravo.functionalcategory.modulename

**In some cases it makes sense to use an additional level:
  org.openbravo.functionalcategory.functionalsubcategory.modulename

**Use a common set of functional categories and subcategories (when needed). Each scrum team defines their own list of categories and subcategories. This is 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)

=Choosing a db_prefix=

==Modules created by the community==
* Use a db_prefix that do '''not''' begin with the letters '''OB'''
* '''EM''' is a reserved word '''not allowed as a db_prefix'''

==Modules created by Openbravo, S.L.U. and staff==
* Use a db_prefix OBXYZ where X, Y and Z are:
** X: for each category (eg. K for Kernel, F for Financial, more to be defined)
** Y: one character for each subcategory (only if it exists)
** Z: from one to 4 characters for the module itself

==Customization modules==

* Use a db_prefix beginning with CUST

Usually customization modules are not intended to be published in Central Repository. In this case, DBPrefix should start with '''CUST'''. Modules with these kind of DBPrefixes '''cannot be registered''' in Central Repository but are collision safe because no other module in Central Repository can use this DBPrefix. This is an important decision to be taken before starting the module development: in case there is any chance of publishing the module at some moment, it should follow the standard rule, if it is absolutely sure that it will not be published you can use ''CUST'' and do not register it.

[[Category:Openbravo ERP 2.50]]