{"type":"doc","content":[{"type":"heading","attrs":{"level":2},"content":[{"text":"Overview","type":"text"}]},{"type":"paragraph","content":[{"text":"This page describes common conventions to be used for the OpenMRS project. Specific topics should be referenced (linked) from this page. Our goal is not to create a long laundry list of rules, but to provide guidance such that if two developers were to create the same functionality, the resulting work would be 80% similar.","type":"text"}]},{"type":"paragraph","content":[{"text":"\"There is no such thing as an undocumented convention\" -OpenMRS","type":"text","marks":[{"type":"strong"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Developing Code for OpenMRS","type":"text"}]},{"type":"paragraph","content":[{"text":"The OpenMRS community has established a set of conventions regarding code style, format and more which aims at keeping the OpenMRS code consistent and in good shape. Refer to the following pages for more details","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Java Conventions","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/spaces/docs/pages/25477044"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"JavaScript Conventions","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/spaces/Archives/pages/25521000"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Pull Request Tips","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/spaces/docs/pages/25477199"}}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Code Repositories and Conventions","type":"text"}]},{"type":"paragraph","content":[{"text":"We use the ","type":"text"},{"text":"Git","type":"text","marks":[{"type":"link","attrs":{"href":"https://git-scm.com"}}]},{"text":" for version control and ","type":"text"},{"text":"GitHub","type":"text","marks":[{"type":"link","attrs":{"href":"http://github.com"}}]},{"text":" to host our ","type":"text"},{"text":"Code Repositories","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/spaces/Archives/pages/25462181"}}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Git","type":"text"}]},{"type":"paragraph","content":[{"text":"To read about how to use Git refer to: ","type":"text"},{"text":"Using Git","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/display/docs/Using+Git"}}]},{"text":" ","type":"text"}]},{"type":"paragraph","content":[{"text":"If you like watching a video try this one ","type":"text"},{"text":"here","type":"text","marks":[{"type":"link","attrs":{"href":"http://www.youtube.com/watch?v=x5OJvil1HE8"}}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"GitHub","type":"text"}]},{"type":"paragraph","content":[{"text":"If you want to contribute code you should read:","type":"text"},{"text":" GitHub Conventions","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/spaces/docs/pages/25475791"}}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Code Review","type":"text"}]},{"type":"paragraph","content":[{"text":"If you want to help out in reviewing code this should help:","type":"text"},{"text":" Code Review","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/spaces/Archives/pages/25477118"}}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Backporting Code","type":"text"}]},{"type":"paragraph","content":[{"text":"When bug fixes and/or features are applied to earlier versions of the system, this is called \"backporting.\" OpenMRS uses major.minor.maintenance versioning (e.g., 1.7.3). Maintenance releases are specifically designed to allow for bug fixes to be backported. Sometimes ","type":"text"},{"text":"features","type":"text","marks":[{"type":"em"}]},{"text":" (not just bug fixes) are applied to previous releases.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Bug fixes and security patches are generally applied to previous releases that are still being supported.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"New features are sometimes a candidate for backporting, but are treated on a case-by-base basis and should be backward compatible within the minor version.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Data Model Design","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Naming tables","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"We've chosen to use all lowercase names with underscores (_) between words (e.g., patient_address)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use the singular form (e.g. ","type":"text"},{"text":"patient_address","type":"text","marks":[{"type":"em"}]},{"text":" instead of ","type":"text"},{"text":"patient_addresses","type":"text","marks":[{"type":"em"}]},{"text":") except where the singular form is a reserved word (e.g. ","type":"text"},{"text":"users","type":"text","marks":[{"type":"em"}]},{"text":" instead of ","type":"text"},{"text":"user","type":"text","marks":[{"type":"em"}]},{"text":", since ","type":"text"},{"text":"user","type":"text","marks":[{"type":"em"}]},{"text":" is a ?","type":"text"},{"text":"SQL Reserved Word","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/spaces/Archives/pages/25520560"}}]},{"text":")","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Where auditing of rows is needed, use the following attributes:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"creator","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text"},{"text":"(FK to users)","type":"text","marks":[{"type":"em"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"date_created","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text"},{"text":"(datetime)","type":"text","marks":[{"type":"em"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"changed_by","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text"},{"text":"(FK to users)","type":"text","marks":[{"type":"em"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"date_changed","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text"},{"text":"(datetime)","type":"text","marks":[{"type":"em"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"voided","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text"},{"text":"(boolean)","type":"text","marks":[{"type":"em"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"voided_by","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text"},{"text":"(FK to users)","type":"text","marks":[{"type":"em"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"date_voided","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text"},{"text":"(datetime)","type":"text","marks":[{"type":"em"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"void_reason","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text"},{"text":"(varchar 255)","type":"text","marks":[{"type":"em"}]}]}]}]}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Special Table Name Suffices","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"_map","type":"text","marks":[{"type":"strong"}]},{"text":" is used for many-to-many relationship tables","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"_type","type":"text","marks":[{"type":"strong"}]},{"text":" is used for a table that categorizes objects in another table — e.g., ","type":"text"},{"text":"location_type","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"_attribute","type":"text","marks":[{"type":"strong"}]},{"text":" is used for a table that extends another table dynamically — e.g. ","type":"text"},{"text":"person_attribute","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"_property","type":"text","marks":[{"type":"strong"}]},{"text":" is used to define Java-ish key/value properties associated with a given object — e.g. ","type":"text"},{"text":"user_property","type":"text","marks":[{"type":"code"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Naming columns","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use lowercase with underscores (_) between words","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Auto-generated numeric primary keys are ","type":"text"},{"text":"_id","type":"text","marks":[{"type":"em"}]},{"text":" (e.g., ","type":"text"},{"text":"patient_id","type":"text","marks":[{"type":"em"}]},{"text":" and ","type":"text"},{"text":"encounter_id","type":"text","marks":[{"type":"em"}]},{"text":")","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Datatypes and use of Liquibase","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Do not use ","type":"text"},{"text":"int(11)","type":"text","marks":[{"type":"strong"}]},{"text":" (The display width in bracket is MySQL-specific and not useful), instead use ","type":"text"},{"text":"int","type":"text","marks":[{"type":"strong"}]},{"text":" only","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use type=\"BOOLEAN\" and defaultValueBoolean=\"\" instead of smallint, tinyint for boolean columns (Look out for voided, retired etc properties)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"DOUBLE PRECISION","type":"text","marks":[{"type":"strong"}]},{"text":" instead of ","type":"text"},{"text":"DOUBLE","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use dbms=\"<","type":"text"},{"text":"databasetypename","type":"text","marks":[{"type":"link","attrs":{"href":"http://www.liquibase.org/databases"}}]},{"text":">\" when creating database-specific SQL or changeset","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Until 1.9 it is safe to assume that everyone was using MySQL-only, after that all liquibase changesets/database scripts should be database-independent","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Following should be added for generating uuid in Microsoft SQL server:","type":"text"}]},{"type":"codeBlock","content":[{"text":"\n \n\n","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"autoIncrement=\"true\" in liquibase will create a sequence in postgres with name ","type":"text"},{"text":"__seq","type":"text","marks":[{"type":"strong"}]},{"text":". Use this to manipulate sequences during bulk inserts using the following:","type":"text"}]},{"type":"codeBlock","content":[{"text":"\n \n\n","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Instead of tag, use the more specific tags in ","type":"text"},{"text":"liquibase 2.0","type":"text","marks":[{"type":"link","attrs":{"href":"http://www.liquibase.org/v2_upgrade"}}]},{"text":" for column operations. e.g. ","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Always include a precondition for each changeset. Although liquibase does have a mechanism for applying only missing changesets, it is not always possible to rely on said mechanism due to maintenance workflows or historical reasons.","type":"text"},{"type":"hardBreak"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Some basic rules for preconditions:","type":"text"}]}]}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph"},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"When adding a new table, column or foreign key constraint, the precondition should check that none already exists with the same name","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"When adding a new table, it is recommended to add the foreign key constraints within the same changeset.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"When dropping a table, column or foreign key constraint, the precondition should check that one actually exists with the same name","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"When renaming a table or column, the precondition should check that none exists with the new name and that there is one that already exists with the old name","type":"text"}]}]}]}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If the precondition fails (for example, new table already exists), mark the changeset as already ran (attribute ","type":"text"},{"text":"onFail","type":"text","marks":[{"type":"code"}]},{"text":"=\"MARK_RAN\")","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Also document the changeset with a short comment","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The ids of changesets should typically be time stamps of the format YYYYMMDD-HHSS or YYYYMMDD-HH:SS e.g 20140716-1415 or 20140716-14:15 respectively. You can optionally append the ticket number e.g 20140716-1415-TRUNK-4402. For modules, it is recommended to prepend the moduleId to the id of the changeset so that it is guaranteed to differ from those in core or other modules e.g calculation-20140716-1415 where calculation is the moduleId","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Global and User Properties","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Property Names","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"All names must be globally unique amongst property names","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Dot notation, similar to Java properties, with specificity increasing from left to right","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Camel case or underscores to delineate words","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"No whitespace (spaces, tabs, carriage returns)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"All properties for modules should begin with the module id + \".\"","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"All portlet properties should begin with the portlet name + \".\"","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Modules","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Module Conventions","type":"text","marks":[{"type":"link","attrs":{"href":"https://openmrs.atlassian.net/wiki/spaces/docs/pages/25487526"}}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Web Application Development","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"User Interface","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Every openmrs business object needs to have a format tag for printing it to the screen.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"These should be used wherever possible on jsp pages: is much preferrable to ${patient.name}","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The tag should be called and live in src/web/org/openmrs/web/taglib as formatXXXTag.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Parameters that every tag should support:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"object=\"${patient}\" --> This is the object to be formatted","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"id=\"1234\" --> This is the id of the object to be formatted, which will necessitate a call to Context.getYYYService().getXXX(id)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"nolink=\"false|true\" --> If false (the default) then the output might include a link, e.g. formatPatient might link to that patient's dashboard","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"size=\"compact|normal|tooltip|descriptive|bookkeeping\"","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"To use a tag, you need to provide object or id (object should take precedence if both are non-null).","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If a business object is voided or retired, it should be struck through: PIH ID 1234-1 ","type":"text"},{"text":"Darius Jazayeri","type":"text"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"Size examplescompact -> shortest reasonable representation, e.g. just the name of a patient or form, but the shortname of a conceptDarius Jazayerinormal -> normal representation, and the default when size is not specifiedPIH ID 1234-1Darius Jazayeridescriptive -> The normal representation, plus extra descriptive information, such as a form's description or a patient's age and genderPIH ID 1234-1Darius Jazayeri,29 year old Maletooltip -> Would look like the normal-sized version followed by an 'additional info' icon. That icon's tooltip would contain the extra description you'd otherwise see when size=descriptivebookkeeping -> Like tooltip, but also includes all bookkeeping information (creator, date-created, modified-by, date-modified)","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"We should create tag files for standard data entry widgets, under ","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Parameters:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"id & name for the form field element","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"size: popup | in-place","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Create these for patient/user/person, concept, location, encounter type, etc.","type":"text"}]}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"SpringMVC","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"File naming:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"user.list is the name of the page that lists users","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"user.form is the name of the page that lets you edit users","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"userList.jsp and userForm.jsp are the names of the actual files","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"UserFormController.java and UserListController.java are the names of the controllers","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"UserValidator.java is the validator","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"messages.properties","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Object.","type":"text"},{"text":"property","type":"text","marks":[{"type":"em"}]},{"text":"=label (eg Obs.patient=Select a Patient)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"error.","type":"text"},{"text":"property","type":"text","marks":[{"type":"em"}]},{"text":"=error description (eg error.gender=Invalid patient gender)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"general.","type":"text"},{"text":"property","type":"text","marks":[{"type":"em"}]},{"text":"=general label (eg general.description.label=Description)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"formname.label=label (eg formentry.title=Form Entry)","type":"text"}]}]}]}]}]}],"version":1}