From cbefa3ce040f21233d054bbdb245289c610784ea Mon Sep 17 00:00:00 2001
From: Piotr Rozenfeld <piotr.rozenfeld@intel.com>
Date: Thu, 13 Apr 2023 14:14:58 +0000
Subject: [PATCH] documentation: expand commit message guidelines

Signed-off-by: Piotr Rozenfeld <piotr.rozenfeld@intel.com>
---
 .github/lint.yml | 23 +++++++++++++
 CONTRIBUTING.md  | 89 ++++++++++++++++++++++++++++++++++++++++++++----
 2 files changed, 106 insertions(+), 6 deletions(-)

diff --git a/.github/lint.yml b/.github/lint.yml
index 0b94878571..f540291723 100644
--- a/.github/lint.yml
+++ b/.github/lint.yml
@@ -62,3 +62,26 @@ lint:
     - IGC
     - LOCI
     - HSD
+    - GSD
+
+  commit_message_subject:
+    types:
+      - feature
+      - fix
+      - refactor
+      - documentation
+      - build
+      - ci
+      - performance
+      - test
+    scope:
+      values:
+        - usm
+        - ulls
+        - ooos
+        - debugger
+        - zebin
+        - sysman
+        - ocl
+        - wa
+        - internal
\ No newline at end of file
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e8eb7f9657..85bfe09d36 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -24,11 +24,16 @@ this will be verified by clang-format and clang-tidy
 (tool configuration is already included in NEO repository).
 
 ### 2. Certificate of origin
+
 In order to get a clear contribution chain of trust we use the
 [signed-off-by language](https://01.org/community/signed-process) used by the Linux kernel project.
 Please make sure your commit message adheres to this guideline.
 
-### 3. Patch submission
+### 3. Commit message content
+
+All contributions should follow specific [commit message](#commit-message-guidelines) guidelines outlined below.
+
+### 4. 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 follows these rules:
@@ -37,12 +42,12 @@ the requirements above. Make sure your commit message follows these rules:
 * additional description can be provided in the body
 * title and body need to be separated by an empty line
 
-### 4. Initial (cursory) review
+### 5. 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.
 
-### 5. Verification
+### 6. Verification
 
 We'll double-check that your code meets all of our minimal quality expectations. Every commit must:
 * Build under Linux - using clang (8.0) and gcc (7.x ... 9.0)
@@ -55,12 +60,12 @@ We'll double-check that your code meets all of our minimal quality expectations.
 
 When all the automated checks are confirmed to be passing, we will start actual code review process.
 
-### 6. Code review
+### 7. 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.
 
-### 7. Patch disposition
+### 8. Patch disposition
 
 We reserve, upon conclusion of the code review, the right to do one of the following:
 1. Merge the patch as submitted
@@ -75,4 +80,76 @@ Your patch may be reverted later in case of major regression that was not detect
 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
\ No newline at end of file
+* Make sure your github account is linked to your intel.com email address
+
+## Commit Message Guidelines
+
+### Introduction
+
+The intention of the strict rules for the content and structure of the commit message is to make project history more readable.
+Both Conventional Commits [specification](https://www.conventionalcommits.org/en/v1.0.0/) and Angular's [Commit Message Guidelines](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#commit) inspired the rules outlined below
+
+### Commit Message Format
+
+Each commit message consists of a **header**, a **body** and a **footer**.  The header has a special
+format that includes a **type**, a **scope** and a **subject**:
+
+```
+<type>(<scope>): <subject>
+<BLANK LINE>
+<body>
+<BLANK LINE>
+<footer>
+```
+
+The **type** is mandatory and the **scope** of the header is optional. Both **type** and **scope** should always be **lowercase**. Multiple values of **type** and **scope** are not allowed.
+
+Provide a couple sentences of human-readable content in the **body** of the commit message. Focus on the purpose of the changes.
+
+Metadata associated with commit should be included in the **footer** part. Currently, it is expected to contain certificate of origin ( _Signed-Off-By:_ ) and tracker reference ( _Resolves:_ / _Related-To:_ ). 
+
+Allowed values for the **scope** are listed at the end of the [lint.yml](https://github.com/intel/compute-runtime/blob/master/.github/lint.yml) and should be extended sparingly, with extra caution.
+
+Allowed values for the **type** are 
+* build
+* ci
+* documentation
+* feature
+* fix
+* performance
+* refactor
+* test
+
+Use the following checklist to determine which **type** to use in your commit:
+
+0. Revert of a prior commit is a special case - use the following commit message format:
+```
+Revert "<subject of commit being reverted>"
+
+This reverts commit <ID of commit being reverted>
+```
+    * Example: 3d3ee8dccb71ddedbc500e3569f024b1775c505a
+
+1. Use **type** == **documentation** when your commit modifies _only_ the human readable documentation
+	* this is currently applicable to markdown files, including programming guide
+	
+2. Use **type** == **ci** when your commit modifies _only_ the files with metadata related to the way we test, but does not affect local build flow
+
+3. Use **type** == **build** when your commit modifies the build flow, but does not modify the codebase of compute-runtime itself
+	* example: updating the header dependencies in third_party folder
+
+4. Use **type** == **test** when your commit modifies _only_ the files in test folders (unit_test, etc.) and not the actual runtime code
+
+5. Use **type** == **performance** when your commit is intended to improve observable performance without affecting functionality, 
+    * when in doubt whether to use performance vs. fix as type, performance is usually a better fit
+	
+6. Use **type** == **fix** when your commit is intended to improve the functional behavior of the compute-runtime
+    * when in doubt whether to use fix vs. feature as type, consider whether the feature being modified is enabled by default and already available in a posted release. If it is, use type == fix, otherwise use type == feature
+
+7. Use **type** == **feature** when your commit is intended to add new functionality, 
+    * New functionality means meaningful changes in functional behavior that would be detected by a black-box test in deterministic manner
+	* For features not intended to be eventually enabled by default (e.g. debugability / logging improvements / code only enabled via debug keys) - use **scope** == **internal**
+
+8. Use **type** == **refactor** for all other cases
+
+Note: usage of tracker reference with the _Resolves:_ or _Related-To:_ notation is mandatory for **type** == **feature** or **scope** == **wa**, and optional for all other values.