diff --git a/README.md b/README.md index 523f4e0209..810b6a837d 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,6 @@ Intel Atom Processors with Gen9 graphics devices (formerly Apollo Lake, Gemini L By default, please submit an issue using native github.com interface: https://github.com/intel/compute-runtime/issues. - ## How to contribute Create a pull request on github.com with your patch. Make sure your change is cleanly building and passing ULTs. @@ -44,7 +43,9 @@ A maintainer will contact you if there are questions or concerns. ## See also * Building and installation: [BUILD.md](https://github.com/intel/compute-runtime/blob/master/documentation/BUILD.md) +* Contribution guidelines: [CONTRIB.md](https://github.com/intel/compute-runtime/blob/master/documentation/CONTRIB.md) * Known issues and limitations: [LIMITATIONS.md](https://github.com/intel/compute-runtime/blob/master/documentation/LIMITATIONS.md) +* Frequently asked questions: [FAQ.md](https://github.com/intel/compute-runtime/blob/master/documentation/FAQ.md) +* Quality expectations: [RELEASES.md](https://github.com/intel/compute-runtime/blob/master/documentation/RELEASES.md) ___(*) Other names and brands my be claimed as property of others.___ - diff --git a/documentation/CONTRIB.md b/documentation/CONTRIB.md new file mode 100644 index 0000000000..7bf744f1f6 --- /dev/null +++ b/documentation/CONTRIB.md @@ -0,0 +1,48 @@ +# Contribution guidelines + +## Process overview + +### 1. Patch creation + +Start with a patch (we prefer smaller self-contained incremental changes vs. large blobs of code). +When adding new code, please also add corresponding unit level tests (ULT). Added ULTs should cover +all the decision points introduced by the commit and should fail if executed without the code changes. +Make sure it builds and passes _all_ ULT tests. For details about what compilers and build configurations +we expect, refer to [BUILD.md](https://github.com/intel/compute-runtime/blob/master/documentation/BUILD.md). +Make sure you adhere to our coding standard - this will be verified by clang-format and clang-tidy +(tool configuration is already included in NEO repository). + +### 2. Patch submission + +Create a pull request on github once you are confident that your changes are complete and fulfill +the requirements above. Make sure your commit message contains meaningful title (first line). +A few sentences of additional description is also required. All lines in the commit messages have 80 characters limit. + +### 3. Initial (cursory) review + +One of NEO maintainers will do an initial (brief) review of your code. We will let you know if anything major is missing. + +### 4. Verification + +We'll double-check that your code meets all of our minimal quality expectations (for every commit - see [RELEASES.md](https://github.com/intel/compute-runtime/blob/master/documentation/RELEASES.md)). +When all the automated checks are confirmed to be passing, we will start actual code review process. + +### 5. Code review + +We'll make sure that your code fits within the architecture and design of NEO, is readable and maintainable. Please make sure to address our questions and concerns. + +### 6. Patch disposition + +We reserve, upon conclusion of the code review, the right to do one of the following: +1. Merge the patch as submitted +2. Merge the patch (with modifications) +3. Reject the patch + +If merged, you will be listed as patch author. +Your patch may be reverted later in case of major regression that was not detected prior to commit. + +## Intel Employees + +If you are an Intel Employee *and* you want to contribute to NEO as part of your regular job duties, please: +* Contact us in advance +* Make sure your github account is linked to your intel.com email address diff --git a/documentation/FAQ.md b/documentation/FAQ.md new file mode 100644 index 0000000000..efb5ab49e6 --- /dev/null +++ b/documentation/FAQ.md @@ -0,0 +1,58 @@ +# Frequently asked questions + +## OS support + +### Which Linux versions does NEO support? + +NEO should work on any modern Linux distribution (i.e. Ubuntu, Fedora, etc.) +with default / stock configuration (no kernel patches), assuming the underlying +kernel's drm subsystem is 4.7 or higher. +Our default (most frequent) validation config is currently (as of Q1'18) Ubuntu 16.04.3 LTS. + +### Does NEO support Microsoft Windows? + +Our closed-source driver for Windows is using the same codebase. At this time, +we do not support compilation of the OpenCL stack for Windows. It is our long-term +intention to offer that option. + +### Why is the feature set different in latest Windows driver vs. latest NEO on github? + +Our Windows release process takes up to several weeks before drivers are available through intel.com +and/or Windows update. Features available in github will be available on Windows later. +This is applicable for most recent driver version (currently 15.65 as of Q1'18) +- older platforms (e.g. Broadwell) are considered to be in maintenance mode for Windows. + +### Does NEO support Android? + +The code can be ported and cross-compiled for Android systems. It is our long-term intention to offer that option. + +## Platform support + +### Which Intel platforms are supported by the driver? + +See [README.md](https://github.com/intel/compute-runtime/blob/master/README.md). + +### When will support for platform X be added? + +We will start adding platform support after platform is disclosed by Intel. +It is our intention to offer full support ahead of platform's market availability. + +## OpenCL version + +### Which version of OpenCL is supported? + +See [README.md](https://github.com/intel/compute-runtime/blob/master/README.md). + +### Which platforms will receive OpenCL 2.2 support? + +Any platforms supporting OpenCL 2.1 are eligible for move to OpenCL 2.2. + +## Who are we? + +NEO OpenCL team is part of VPG (Visual and Parallel Computing group). Historically, our team +was responsible for delivery of the closed source OpenCL driver for Windows, Linux, and Android. + +With that in mind, we tend to compare NEO against previous closed source releases +(i.e. [SRB5](https://software.intel.com/en-us/articles/opencl-drivers#latest_linux_driver)). + +Most of the developers are located in Poland (UTC+1 timezone). diff --git a/documentation/RELEASES.md b/documentation/RELEASES.md new file mode 100644 index 0000000000..b6fbe18c3c --- /dev/null +++ b/documentation/RELEASES.md @@ -0,0 +1,27 @@ +# Quality expectations + +## Every commit - must ... + +* Build under Linux - using multiple versions of gcc (4.8 ... 7.3) and clang (4.0.1) + +* Build under Windows (this is currently a requirement that cannot be verified externally) + +* Pass ULTs for all supported platforms + +* Pass clang-format check with the configuration contained within repository + +* Pass clang-tidy check with the configuration contained within repository + +* Pass sanity testing (test content recommendation for the external community will be provided in the future) + +## Weekly + +* Once a week, we run extended cycle on a selected driver. When the extended cycle passes, the corresponding commit on github is tagged (e.g. "2018ww08"). Such version is considered recommended for the community use ("latest good") + +* For selected weekly tags, we may choose to release binaries (deb, rpm, tarball) - those will usually be considered a Beta driver. + +## Monthly / quarterly releases + +* For major _driver_ releases, OpenCL driver is expected to be bundled with Media and/or MESA drivers. Cadence and timeline will be coordinated with our OTC colleagues. + +* The driver releases (weekly/monthly/quarterly) will then be bundled with software products (Intel(R) Computer Vision SDK, Intel(R) SDK for OpenCL(TM) Applications, Intel(R) Media Server Studio, etc.) as appropriate.