Naming Your Module
- Module id should be all lowercase without spaces. We prefer no breaks in the word (e.g.,
htmlformentry); however, you may use hyphens if absolutely necessary.
- The Module id should correspond with the unqualified top-level package for classes in the module. So, org.openmrs.module.foo would have an id of foo.
- Avoid using a module id that conflicts with existing modules or tables that already exist in the data model — e.g., "concept" and "form" would be undesirable module ids, since there are existing tables with these names.
- Implementations of special functions should use dot notation: serialization.xstream, webservices.jaxws. (and this means a package of org.openmrs.module.serialization.xstream)
- Module name should be concise (ideally less than 20-25 letters), may contain spaces and upper case characters, but should avoid punctuation. It does not have to match the module id exactly.
If your module is on Git Hub, see the the Git conventions here
Module developers are encouraged to follow Subversion's suggested directory layout if your module is in SVN:
README conventions for modules in SVN
Each module should contain a README file within the trunk folder (or root folder if not using the trunk/branches/tags folder convention in subversion). The README may be named README, README.txt, README.md, or README.markdown (use .md or .markdown extension for a README using markdown syntax).
Your README should contain at least two sections: description and installation. For example:
- Module table names should begin with the module id — e.g., all tables added for a the "formentry" module should have table names beginning with "formentry_*".
- Be careful when naming your module to avoid conflicts with other modules or existing tables
Module Project Management
- While module developers are welcome to use their own ticketing system, we encourage module developers to use ?JIRA to track bugs and enhancement requests.
- Request a new JIRA project for your module by opening a ticket.
- Add milestones for your module to the Technical Road Map using the naming convention: <module name> Module x.x — e.g., FormEntry Module 1.0. Make one milestone for the current version and one for the next version. Optionally, you can make a milestone entitled "<module name> Module Someday" for enhancements not anticipated in the next version.
- Module authors are responsible for keeping tickets and milestones for their module up to date
- Module admin pages should fit in with other admin pages. Users like a standard look. Fancy js windows are cool but they have their place. Mimic the core jsp pages
- Don't include a log4j.xml: this will override the configuration in core and possibly break it. It also prevents system administrators from managing logging. If you need to change the log4j configuration then use the LogManager module. In a Mavenized module you can however include a log4j configuration file just for testing by placing it in src/test/resources.
- Use per class loggers: put the following line at the top of each class in your module:
- Logging exceptions: if you have a throwable (e.g. ex), use the pattern: log.debug("Concise title for debug message", e). Do not use the anti-pattern of: _log.debug(e) as there is no log.debug(Throwable) method, so the exception is cast to a string and the stack trace is lost.
- Expensive log messages: If you're going to log a message that is computationally intensive to calculate, use the isDebugEnabled, isWarnEnabled, isErrorEnabled methods. For example: