Contributing a New Sample - jimmytwei/oneAPI-samples GitHub Wiki

If you are looking at adding a new sample to the oneAPI ecosystem, we welcome your input! To do so, please perform the following steps.

  1. Inform the samples maintainers (Program Manager) of your proposed sample, and we will work with you on the requirements

  2. Add an Issue to the oneAPI-samples repo with the title Request to add a oneAPI Sample <YourSampleName>.

    • Enter a description of your proposed sample and anything else required by this template
      • Within the description, include the purpose of the Code Sample, ie what is this sample showing that others in this family of code samples does not
    • Request the following GitHub users in the body of your proposal
    • Get approval from the oneAPI Samples working group, please fill out this form
      • Note: These third-party components, require additional approvals via the Intel Open Source Product Development Team(OSPDT). This can take 1-4 weeks depending on the scheduling and complexity of the request

  3. Fork the oneAPI_samples repo

Note: See step 1. on the 'Making a contribution to the repository' wiki page for help with creating a fork.

  1. Clone your new fork of the oneAPI-samples repo to your local system. It helps if you rename the clone of your forked repo on your local disk, for example, like this:
git clone https://github.com/<YourGitHubName>/oneAPI-samples.git oneAPI-samples-fork

IMPORTANT: Do not clone the oneAPI-samples repository: https://github.com/oneapi-src/oneAPI-samples. You need to clone YOUR fork of the oneAPI-samples repo. You can only push directly into your cloned repo. Attempting to push into the oneAPI-samples will fail.

  1. Create a new Branch within your cloned repo to hold your sample. Try to be accurate with your folder placement within your working clone. If you aren't sure, we can adjust it to the correct location later.

  2. Write your proposed sample using proper coding guidelines, see the Guidelines section within the Wiki. Here are a few of them:

    • Any new dependencies, libraries, binaries, images, etc. communicate the addition asap to the Domain Expert

    • Use consistent variable and type naming​ ​Google Coding Style Guidelines

    • Use consistent source code formatting​​ Google Coding Style Guidelines

      • Enforced via "clang-format" config file clang-format -style=google -i file.cpp
      • Do not use std::endl except in an exception
      • If you have any questions, seek a review from the people identified in step 1
        • Add user to YOUR FORK from Step 1
        • Create an Issue in YOUR FORK and assign it to the above user

    • Need to add a samples.json file, use the one from the Mandlebrot sample for additional information on the sample.json see the wiki pages

    • Create a README.md for your sample, using the mandelbrot README.md as an example

    • Validate your sample using Intel's DevCloud.

  3. Set your sample up for submission to the repo

    • Have concept approval from oneApi samples Team (see step 1. above)
    • Perform the preliminary SDL requirements
      • PHP samples - Perform bandit scans, fix issues and submit a report to the Program Manager
      • C++ Samples
        • Compile your code using compiler flag "enable -Wall -Wformat-security -Werror=format-security" this will provide a report of any errors that may have been missed.
    • Set up for CI
      • Create a sample.json file in the root of your sample folder oneAPI-samples-fork/<MySampleFolderName> Use the mandelbrot sample.json as a template
      • Modify the sample.json file variables as necessary for your sample
        • To create a GUID for your sample.json file
          • Go to GUID Generator
          • Check the 'Uppercase' and 'hyphens' boxes
          • Push the "Generate GUIDs" button
          • Copy the GUID from the box e.g.: 825BEB2D-C9FA-4527-8770-9F7D765AAAAA
        • For assistance determining the correct "Categories" field in your sample.json file, you can see the current list by doing the following
          • Download and install an oneAPI toolkit oneAPI Toolkits
          • run the setvars script (located in the oneAPI root installation folder)
          • type oneapi-cli --ignore-os at the prompt
          • select the C++ option and review the samples that are presented
        • Go here for assistance with the ciTest object
      • Modify the guids.json file
  • To validate that your sample.json is free of syntax errors
    • License Files
      • License.txt (Requirement)- By default, all sample code should use the MIT license and the License.txt file from the root of this repo should be included in the root of the sample
      • third-party-programs.txt (TPP file) (Required/optional)- if the sample is using any third-party components, the sample will require prior approval thru OSPDT and must be compatible with the MIT License. Once approval has been completed a new "third-party-programs.txt" will be added to the root of this repo, which the sample author will then include in the root of the sample being developed.
        • Required - Including the TPP file is a requirement for any sample with third party components
        • Optional - if not using third-party, it can still be included but is not required

  1. Pushing your new sample and/or changes into your oneAPI-samples fork repo

    • Do a git status to make sure the only changes are for your sample; be sure that you do not accidentally make changes outside of your sample.

    • Add and Commit to your fork's custom branch within your fork clone).

      Make sure you always use the git commit -s option when making your commits. Your commits must be signed.

      git add .
git commit -s
git push origin

    • If you get an authentication error at this point, there could be a couple of problems:

      • Your GitHub configuration is bad.
      • You are using the wrong password.
      • You cloned the main repo instead of a fork of it.

  2. Create a Merge Request to merge this sample from your fork and Branch to the oneAPI-samples repo

    • See the GitHub docs regarding how to make a Pull Request, especially steps 3, 4, and 5.
    • Since you are making a pull request from a forked repo, be sure that:
      • You click the "compare across forks" link
      • Set the "base repository" (left side) so it points to the oneAPI-samples repo
      • Set the "head repository" (right side) so it points to your Branch within your forked repo
    • When creating the merge request, the description box is auto-populated with a checklist.
      • If all these steps are not done, please add WIP to the beginning of the title and finish your Merge Request.
      • When all the checklist is done, please update the description and remove the WIP from the title.

  3. Review the Merge Request for various issues, The oneAPI Team will be reviewing your code and may or may not request changes. Once the sample has one review, the ci will run and you will be required to fix any additional issues found

  4. When the sample gets tagged for a production build, verify your sample shows up in the IDE correctly by downloading the new toolkit Testing in IDEs