Patch Process

Process Description

This Patch Process describes the process for establishing how an outside contributor will supply a patch to the baseline and how the patch will be incorporated. The process explains the workflow for how a patch should be developed, submitted, reviewed and included in the system functionality.

Definitions

  • GitHub – a web-based Git repository hosting service. It offers all of the distributed revision control and source code management (SCM) functionality of Git as well as adding its own features.
  • Collaborator – a member of the Ozone team that has the ability to push and merge code into the baseline.
  • Contributor – a contributor is someone who has contributed to a project with a pull request, but does not have collaborator access.
  • Reviewer – a member of the Ozone team that is responsible for reviewing a pull request to verify that it meets the code standards of the project and then if approved/accepted, merging the pull request into the baseline.
  • Pull Request – a set of proposed changes to a repository submitted by a contributor and accepted or rejected by a repository’s collaborators.
  • Fork – A fork is a copy of another user’s or group’s repository controlled by you. Forks allow you to change your version of a project without affecting the baseline. Forks remain attached to the baseline, allowing you to submit a pull request; if accepted, a reviewer will merge your changes into the baseline. Also, you can keep your fork up-to-date by pulling in updates from the baseline.

Roles

  • Contributor
    • Individuals who intend to submit code to the code base with the intent to fix an issue or add a new feature.
  • Development Team/Ozone Team/CRADA Custodian
    • Individuals that work on the products, this includes merging in code submitted by contributors.
    • The CRADA Custodian will verify the presence of:
      • Automated Tests
      • Manual Test Cases
      • Documentation
    • The pull request will be presented at the GOSS board for decision of inclusion of the new feature.
    • The pull request will be merged once testing is completed by the GOSS Community.
  • GOSS/FOSS Board
    • Members of the Ozone community that meet to discuss prioritized features.
    • Members of the community will verify the functionality is consistent with description of the pull request.
    • Verification of coding standards and styling are followed.
    • Verifying that the code builds successfully and passes all tests.
    • Responsible for testing pull requests as well as performing regression tests.
    • Approval of the pull request for merging into the baseline.

Process

Contributor Process

The contributor needs to determine the feature or bug fix that they wish to implement and contribute back to Ozone.

Using GitHub

The contributor must have a GitHub account.  Once the contributor has an account they must fork the repository to which that they wish to contribute.

GitHub Guidance

Developing the Pull Request

The contributor will develop the feature/bug fix in their version of the forked code. As development is happening, the following should be considered to aid and speed the acceptance of the pull request:

  • Stay within the professional coding standards to the best of your ability.
  • Add comments in the code to provide detailed developer-level documentation of your changes
  • Verify that the entire code base builds without issue after all changes are made
  • Document and provide unit/regression tests that verify that your new code functions and can be tested by others
  • Submit complete and adequate documentation with the pull request explaining the feature(s) and how it works

Preparing the Pull Request

Before submitting the pull request, the contributor must complete the following steps:

  1. Merge the latest code from the branch that you forked from (typically the master branch in a repository controlled by the Ozone Team) into the the contributor’s local branch.
  2. If there are any merge conflicts, you must resolve them before submitting their pull request for review.
  3. Once your code is up-to-date, run all tests successfully before submitting the Pull Request. All tests must pass before you submit the pull request.

Licenses

All code submitted must be compliant with and licensed under the Apache V2 license.

Submitting the Pull Request to GitHub

When submitting the pull request following the steps in GitHub (click the link for the GitHub pull request instructions), please include documentation, licenses, contact information (to be used for answering questions). Submit code to the main project.

Check List for Submitting the Pull Request

  • Verify you have emailed or attached to the Pull Request the following information:
    • Full Name
      Email
      Organization
      Let us know if you are willing to share the above information with the GOSS Board.
      Let us know if you are willing to share the above information with the community.
  • Validate that during the development and submission you have:
    • Merged the latest code from the branch that you forked from into your local branch.
      Fixed all merge conflicts. You must resolve them before submitting pull requests for review.
      Ran all tests successfully before submitting the Pull Request with the merged code. All tests must pass before you submit the pull request.
      Stayed within the professional coding standards to the best of your ability.
      Added comments in the code to provide detailed developer-level documentation of your changes.
      Verified that the entire code base builds without issue after all changes were made.
      Documented and provided unit/regression tests that verify that your new code functions and can be tested by others.
      Submitted complete and adequate documentation with the pull request explaining the feature(s) and how it works.

Reviewer Process

Reviewing the Pull Request

A member of the Ozone team will review the submitted pull request. The reviewer will verify:

  • Requested documentation was provided – Testing, Technical, User, etc
  • Communicate the submission to the GOSS Board for review

The GOSS Community will be responsible to verify:

  • Functionality is consistent with description of pull request
  • Standards and styling are followed
  • The code builds successfully

Any issue(s) found will be communicated to the contributor so that they have the opportunity to fix the issues and resubmit the pull request.

Go Back