CONTRIBUTING.md

   1 # Contributing to ESPlusPlayer
   2
   3 - [Submission Guideline](#submit)
   4   - [Caution for Code Modification](#caution)
   5   - [Submitting a Pull Request (PR)](#submit-pr)
   6   - [Reviewing a Pull Request](#review-pr)
   7   - [Checking Automation Result](#automation)
   8 - [Coding Rules](#rules)
   9   - [Commit Message Format](#format)
  10   - [Coding Style](#style)
  11   - [Test Code](#test)
  12   - [ESPP Managed API](#mapi)
  13
  14 ## <a name="submit"></a> Submission Guideline
  15
  16 ### <a name="caution"></a> Caution for Code Modification
  17 * Apply code modification to this repository only, **not to VD P4**.
  18 * P4 auto-sync is applied to this repository, so the latest of main branch is always synced to VD P4 automatically.
  19
  20 ### <a name="submit-pr"></a> Submitting a Pull Request (PR)
  21 * Create your own branch first. That branch can be removed after pull request to main branch is merged or closed.
  22 * Commit the modification to your own branch directly during the code development. (Follow [Coding Rules](#rules))
  23 * Create pull request after your modification is completed and ready to commit to main branch.
  24 * Assign the entire [ESPP team](https://github.sec.samsung.net/orgs/tizen-vault/teams/espp) or at least one member in the team for the main reviewer.
  25 * Write the title short but clearly and properly (e.g., `Fix for DFXXXXXX-XXXXX`, `Change A to B`)
  26 * Follow the guideline provided in the [pull request template](./.github/pull_request_template.md).
  27 > If you write your PR on github web page, it is recommended to use [chrome extension](https://chrome.google.com/webstore/detail/better-review/pikfcnpeiknfelpbkiigjpplgjfbblgc) for better formatting and utilities.
  28
  29 ### <a name="review-pr"></a> Reviewing a Pull Request
  30 * When you are assigned as a reviewer of a PR, please try to check the PR as soon as possible.
  31   * review-bot will notify to reviewer group if there is no active review within 6 hours
  32 * When you make a comment for a PR, please write a tag in front of the comment as following:<br>
  33 `[<tag>] <Your comment>`
  34
  35 #### List of Review Tags
  36 | Tag | Review Action <br> (Meaning) | Description |
  37 | -- | -- | -- |
  38 | `P1` | `Request changes` <br> (Please make sure to reflect) | The reviewer requests the review requester to correct the contents of the PR through the `P1` tag if it is deemed necessary to make significant code corrections, such as potentially causing serious errors in the service. The review requester should be able to persuade the reviewer through reasonable opinions that cannot reflect or reflect the reviewer's request for the `P1` tag. |
  39 | `P2` | `Request changes` <br> (Please consider actively) | The author is encouraged to accept `P2` or listen to appropriate opinions and discuss them if they are unacceptable. |
  40 | `P3` | `Comment` <br> (Please reflect it as much as possible) | The author is encouraged to accept `P3`, explain why the PR cannot be reflected if it is unacceptable, or explicitly make plans to be reflected next time (such as JIRA tickets). It is used with `Comment`, not `Request changes`. |
  41 | `P4` | `Approve` <br> (You can reflect it or move on) | The author does not comment on `P4` and can ignore it. It's enough to think about whether it's better to reflect the opinion.
  42 | `P5` | `Approve` <br> (It's just a small opinion / Nitpick) | The author can ignore `P5` without any comment. |
  43
  44 ### <a name="automation"></a> Checking Automation Result
  45 * When your pull request is submitted, some automation will be triggered immediately.
  46 * You must check the result and resolve issues accordingly. Especially, build checker must be passed to merge your PR to `main` branch.
  47
  48 #### Review-Bot
  49 * ESPP repository enabled [review-bot](https://github.sec.samsung.net/review-bot) for the following categories.
  50   * Reviewability Service
  51   * Potential Defect / SAM / CQM
  52   * CheckSpell Service
  53   * Reform Service (see [Coding Style](#style))
  54   * Review Carefully Service
  55   * Idiom Service
  56 * If needed, ESPP member who has the permission can turn on more services later from [here](https://code.sec.samsung.net/crb/projects/1/18007?offset=0&rows=15&search=esplusplayer&sortOrder=-1&sortField=id&isFavoriteOnly=false&jobId=3095761)
  57
  58 #### Build Checker
  59 * ESPP repository enabled several github action workflow scripts for build checking.
  60 * For more detailed info, refer the [announcement](https://github.sec.samsung.net/tizen-vault/esplusplayer/discussions/29) in discussion.
  61
  62 #### MAPI-related Modification Checker
  63 * Check the below [section](#mapi-checker) about this checker.
  64
  65 ## <a name="rules"></a> Coding Rules
  66
  67 ### <a name="format"></a> Commit Message Format
  68 * It is recommened to write clear sentences: `add new function to do A`
  69   * Recommendation: Write it in present tense, not capitalized, and no period at the end
  70 * If possible, add type in front of the message: `fix: add new function to do A`
  71
  72 #### List of Commit Types
  73 * `build`: Changes about build system or build broken fix
  74 * `ci`: Changes about CI configuration (Github action script)
  75 * `docs`: Changes about documentation only (no code change)
  76 * `feat`: A new feature
  77 * `fix`: A bug fix
  78 * `perf`: Changes about improving performance
  79 * `refactor`: Changes about refactoring. Neither a bug nor new feature
  80 * `test`: Adding missing tests or extending existing tests
  81
  82 ### <a name="style"></a> Coding Style
  83 * ESPP follows [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html).
  84 * When sending a PR to `main` branch, review-bot will check the coding style.
  85 * If there is misformatted code, until it is resolved PR will not be merged.
  86 * It is recommended to set up your own IDE to conform coding style on each file save.
  87
  88 #### About Coding Style Setting
  89 * ESPP repository's review-bot is set to "Project Specific (read from .clang-format)"
  90 * The `.clang-format` [file](https://github.sec.samsung.net/tizen-vault/esplusplayer/blob/main/.clang-format) is at the root path of the repository.
  91 * The review-bot will read this file and check the style.
  92
  93 #### Local Style Checking: Running `clang-format` Manually
  94 * Install clang-format to your development environment
  95 * Run clang-format with `-style=file:<<.clang-format file path>>` will check format with the `.clang-format` file.
  96 * Check [here](https://clang.llvm.org/docs/ClangFormatStyleOptions.html) for more detail.
  97
  98 #### Local Style Checking: Using VSCode and Extensions (Recommended)
  99 * Install VSCode and [extension](https://marketplace.visualstudio.com/items?itemName=xaver.clang-format) to check C++ style.
 100 * Set `"editor.formatOnSave": true` to your `settings.json`.
 101 * During code writing with VSCode, style will be re-formed according to `.clang-format` file when saving the code.
 102
 103 ### <a name="test"></a> Test code
 104 * When your code change type is `Feature` or `Bugfix`, you are encouraged to provide test scope in your PR.
 105 * The existing test code can be extended or new test code can be provided if needed.
 106 * In case of adding new Managed API, it is mandatory to provide new test code in [esplusplayer-mapi-tc](https://github.sec.samsung.net/tizen-vault/esplusplayer-mapi-tc).
 107
 108 ### <a name="mapi"></a> ESPP Managed API
 109 * VD Managed API (MAPI) is the functions, structures, and enum types used by Application Layer modules.
 110 * It is described in the header files at `esplusplayer/include/..`
 111 * When your code change includes MAPI addition, the new API must have proper doxygen description.
 112 * For more details about MAPI, see [VD PLATZ](https://platz.sec.samsung.net/cpp/#/) for more details.
 113
 114 #### <a name="mapi-checker"></a> Leaving History about the Added or Modified Managed API
 115 * The workflow named `new-mapi-checker` will make a comment when new PR contains any modifications in `include` path.
 116 ![image](https://media.github.sec.samsung.net/user/17553/files/1de31d30-8e12-469e-8287-d37084f6678b)
 117 * When you get this message, please write the history on [wiki](https://github.sec.samsung.net/tizen-vault/esplusplayer/wiki).
 118