Submitting Patches

This page describes the full process of submitting a patch to the HSA Foundation, including reviewing and tracking changes with GitHub.

Prerequisites

Before you follow the instructions on this page, you will need to set up your local working environment and get the HSA source files or Fork the Repo on GitHub. For instructions, follow the “Getting Started” section here. https://help.github.com/articles/fork-a-repo

For details about GitHub , see GitHub Help pages http://help.github.com/.

For information about the different roles you can play within the HSA Open Source community, see Project roles. http://107.170.238.52/hsaf_csp-people-and-roles/ ‎

If you plan to contribute code to the HSA Open Source repository, be sure to read the HSAF_OSP’s licensing information. http://107.170.238.52/hsaf-csp-licences/

Note that changes to some of the upstream projects used by HSA should be made directly to that project, as described in Upstream Projects.

 

For Contributors

You need to have a registered GitHub Account and have been registered with HSA Foundation as a Contributor. You only need to do this once. Sign in on the GitHub and you will be able to select https://github.com/HSAFoundation/ team link.

 

To get help on setting up a GITHub Account see https://help.github.com/articles/set-up-git

 

Start a repo branch

For each change you intend to make, start a new branch within the relevant git repository:

 

Upload to GitHub

Once you have committed your change to your personal history, upload it to GitHub HSA Foundation Repo.

After a contribution submission is approved

After a contribution submission makes it through the review and verification process, GitHub automatically merges the change into the public repository. Other users will be able to run repo sync to pull the update into their local client.

For reviewers and verifiers

Reviewing a change
If you are assigned to be the Approver for a change, you need to determine the following:

  • Does this change fit within this project’s stated purpose?
  • Is this change valid within the project’s existing architecture?
  • Does this change introduce design flaws that will cause problems in the future?
  • Does this change follow the best practices that have been established for this project?
  • Is this change a good way to perform the described function?
  • Does this change introduce any security or instability risks?

If you approve of the change, mark it with LGTM (“Looks Good to Me”) within GitHub .

Verifying a change

If you are assigned to be the Verifier for a change, you need to do the following:

Patch the change into your local client using one of the Download commands.

Build and test the change.

Within GitHub use Publish Comments to mark the commit as “Verified” or “Fails,” and add a message explaining what problems were identified.

Downloading changes from GitHub

A submission that has been verified and merged will be downloaded with the next repo sync.

How do I become a Verifier or Approver?

In short, contribute high-quality code to one or more of the HSA Technology projects. For details about the different roles in the HSA Foundation Open Source community and who plays them, see Project Roles. 

Diffs and comments

To open the details of the change within GitHub, click on the “Id number” or “Subject” of a change. To compare the established code with the updated code, click the file name under “Side-by-side diffs.”

Adding comments

Anyone in the community can use GitHub to add inline comments to code submissions. A good comment will be relevant to the line or section of code to which it is attached in GitHub. It might be a short and constructive suggestion about how a line of code could be improved, or it might be an explanation from the author about why the code makes sense the way it is.

To add an inline comment, double-click the relevant line of the code and write your comment in the text box that opens. When you click Save, only you can see your comment.

To publish your comments so that others using GitHub will be able to see them, click the Publish Comments button. Your comments will be emailed to all relevant parties for this change, including the change owner; the patch set uploader (if different from the owner), and all current reviewers.

Upstream Projects

HSA Foundation makes use of a number of other open-source projects, such as the LLVM, re2C, and Linux kernel, as described in Branches and Releases. For most projects under external/, changes should be made upstream and then the HSA Foundation maintainers informed of the new upstream release containing these changes. It may also be useful to upload patches that move us to track a new upstream release, though these can be difficult changes to make if the project is widely used within HSA Foundation like most of the larger ones mentioned below, where we tend to upgrade with every release.