Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: shrink the logging section by refering to the java conventions page


Project Layout

If your module is on Git HubGithub, see the the Git conventions here

Module developers are encouraged to follow Subversion's suggested directory layout if your module is in SVN:



Also try the OpenMRS SDK which can get you started quickly.

README conventions for modules


on Github

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,, 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:


Refer to

for sample files

Module Tables

  • 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


  • 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 MapRoadmap 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


  • 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:
    Code Block
    private static final Log log = LogFactory.getLog(MyClassName.class);
  • 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:
    Code Block
    if (log.isDebugEnabled()) {
      String expensiveStep = service.invoke("slowMethod");
      log.debug("We should definitely wrap an " + expensiveStep);

See Also

See Also