Submitting to the Gerrit Code Review System
Bug fixes or minor code modifications and formal OSEHRA releases both require submission to the Gerrit Code Review System. The basic procedures of code submission, including initialization, checkout of the OSEHRA code base, and pushing to Gerrit, remain the same and are covered in Contributor Git Instructions. In this section, we discuss the differences between submissions designed to modify the code base and submissions designed to initiate the code release process.
Both types of submissions, code modifications and release version initiation, begin with an entry in the Jira issue tracker, with the exception that bug reports and requests for code modifications can be submitted to Jira by any person; whereas, the initiation of new releases must be made by a trusted member of the community as part of a formal release process. For release version initiation, the Jira ticket should be titled “Initiation of release #(SHA1)”, where SHA1 corresponds to the unique git tag for the current review target. Non-release Jira tickets should be given a descriptive name and should be given sufficient details in the description so as to allow the developer to understand and replicate the issue.
The specific procedures for setting up a Gerrit environment and for performing the mechanics of submitting to the repository are covered at: Contributor Git Instructions. Please refer to that page for additional supplemental information.
Depending on the type of submission and on the complexity of the code contribution, supplemental materials may be required to complete the submission and pass Software Quality Certification. A list of documents and checklist is included below:
- Business Requirements Document (BRD)
- Software Requirements Specification (RSD)
- Initial Operating Capability (IOC) Testing
- Data Dictionary Modification Request (for Database Administrator)
- Integration Control Registrations (ICR)s
- Clearance on potential impact on FDA Regulated interfaces or devices (from Package maintainers)
- Change submission to Architecture Review Group
- Application Self-Scoring Evaluation Support System (ASSESS) (Capacity Planning form)
- Patch Installation Instructions (Installation Guide)
- List of patch dependencies (Patch Release Check)
- National Patch Module Patch Template
- Updated Documentation describing new Functionalities
- HL7 Messaging Coordinator Approval for related changes
- OED Testing Service Report
Submitting code in response to a standard Jira ticket
To submit code in response to a standard Jira ticket, first obtain a current release from the OSEHRA code repository and follow the directions to set up a testing environment and execute the tests. Download the “OSEHRA M-Code Primary Developer Checklist” and follow the procedures referenced in that document to verify code operation prior to and after the code modifications. Once the code modification is ready, complete the “M-Code Primary Developer Checklist”, attach it to the Jira ticket, and proceed to Contributor Git Instructions to complete the push of the code into Gerrit, referencing the Jira ticket number in the description of the code change. Note that if the code requires modifications or additions to the testing repository, the Gerrit submission process should be executed twice, first in the testing checkout and then in the OSEHRA code checkout. In this case the description provided during the Gerrit code push should refer to the testing checkin as well as the Jira issue. Any required aforementioned supplemental material should be attached to the Jira ticket.
Submitting code in response to a release version initiation
Code submitted in response to a release version initiation should consist of a single push consisting of a change to the upper level OSEHRA Code Base ATTESTATION file. The change should consist of the addition of a single line as the topmost attestation. The line will contain the SHA1 key for the repository to be released, the date, and the name of the attester. Figure 1 shows an example ATTESTATION file after the addition of the first release attestation. Again complete the “Primary Developer Checklist” and attach it to the Jira ticket prior to performing the push to Gerrit; although, for this specific case, most of the entries will be N/A. For the short description, the message should replicate the Jira title “Initiation of release #(SHA1)”. The long description can contain release notes along with the reference to the correct Jira ticket.
Figure 1 - Structure of the ATTESTATION file. The highlighted line shows the structure of the new addition containing the SHA1 key, date and attester name.