Minimal Documentation Requirements

Open Source Documentation Standards

This blog is the current understanding of the minimal requirements for a contribution to the OSEHRA code repository to be considered for OSEHRA Software Quality Certification.  This is a criiticial consideration, since any requirements must balance the needs of providing sufficient documentation and other artifacts such that software quality can be assessed while at the same time not discouraging developers from contributing quality code.  While this document concentrates on just the artifacts, it is not intended to replace the full certification process documented at http://www.osehra.org/document/osehra-software-quality-certification-plan, but should be viewed as an expansion and clarification.  Slides addressing this concept can be found in the "Annotated Swimlane Slides" located at http://www.osehra.org/document/testing-and-intake-workflow-process.

Several items are worth consideration.  Most notably, the OSEHRA code submission tools provide for wide ranging artifacts to be attached to any submission.  Developers who have already generated additional artifacts, or who are required to develop artifacts under contract, are encouraged to augment their submissions with any additional materials they have available.  Also, OSEHRA Software Quality Certification is the first step on getting code accepted into other systems vendors.  The feedback process allows for additional artifacts to be requested and developed after OSEHRA Certification, but before acceptance into a deployable system.

Two scenarios are addressed corresponding to bug fixes and package contributions.

Bug Fix Documentation

For software quality certification purposes, the goal of the bug fix documentation is to document a deficiency, validate that the deficiency is fixed, verify that the software changes make sense as a response to the issue (i.e. guard against trojan horses and extraneous code changes), guard against re-entry of the bug into the code base, and verify that the code changes do not adversely impact existing tests.  Accordingly, bug fixes must consist of at least the following minimal set:

  1. Entry in the OSEHRA bug tracker
  2. Test code that demonstrates the bug
  3. Description of test data plus system/database state
  4. Code fix that passes test
  5. Commit message including:
    1. Identify targeted bug
    2. Succinct description of modifications

The reviewer can use the provided documentation to carry out the review responsibilities in support of certification activities and is expected to:

  1. Download OSHERA testing system
  2. Baseline system status
    1. Execute all tests including failure case
  3. Download code fix
  4. Manually review code using Gerrit review tool
    1. Safe, Compliant, Functional Checklist
  5. Validate system including bug fix (pass all tests including the failing test)
  6. Recommend for/against certification

New Package Documentation

For software quality certification purposes, the goal of new package submission is to document a new functionality in terms of a testable set of capability, validate that the code works as expected, verify that the software submission makes sense as a response to the new functionality (i.e. guard against trojan horses and extraneous code changes), guard against changes that break the new functionality,  and verify that the new submission does not adversely impact existing tests.  Accordingly, new package submissions must consist of at least the following minimal set:

  1. Technical article containing:
    1. Description of the new capability
      1. Requirements/Goals/Rationale
    2. Code walk through
    3. Usage
  2. Test code
    1. Unit tests
      1. Target 100% code coverage
    2. Example(s) of usage
  3. Sample and Test Data

The reviewer can use the provided documentation to carry out the review responsibilities in support of certification activities and is expected to:

  1. Download OSHERA testing system
  2. Baseline system status
  3. Download submission
  4. Read the article
  5. Manually review code
  6. Review tests for completeness
  7. Validate system including new code tests
  8. Recommend for/against certification

Additional Documentation

Both bug fix and new code contributions can contain documentation in excess of the minimum requirements.  If additional documentation needs to be developed to support intake procedures for other entities, both the bug fix and new contribution tools provide places for the additonal documentation to be provided along with the submissions.  In particular, the bug tracker provides utilities for attaching documentation beyond the required documentation to a given issue.  Similarly, the OSEHRA Technical Journal can accept arbitrary numbers and types of documents.  If this documentation exists or if it is generated as part of an external intake process, OSEHRA strongly encourages it to be provided back to the open source community.  Such additional artifacts can greatly increase adoption of the new contribution by additional user communities.

 

Groups: