[DOCS] contributing guidelines (#19218)

changes to the contribution guide

CONTRIBUTING.md

@@ -1,53 +1,88 @@
-# How to contribute to the OpenVINO repository
-
-We welcome community contributions to OpenVINO™. Please read the following guide to learn how to find ideas for contribution, follow best practices for pull requests, and test your changes with our established checks.
-
-
-## Before you start contributing you should
-
--   Make sure you agree to contribute your code under  [OpenVINO™ (Apache 2.0) license](https://github.com/openvinotoolkit/openvino/blob/master/LICENSE).
--   Decide what you’re going to contribute. If you are not sure what you want to work on, check out [Contributions Welcome](https://github.com/openvinotoolkit/openvino/issues/17502). See if there isn't anyone already working on the subject you choose, in which case you may still contribute, providing support and suggestions for the given issue or pull request.
--   If you are going to fix a bug, check if it still exists. You can do it by building the latest master branch and making sure that the error is still reproducible there. We do not fix bugs that only affect older non-LTS releases like 2020.2, for example (see more details about our [branching strategy](https://github.com/openvinotoolkit/openvino/wiki/Branches)).
-
-
-## "Fork & Pull Request model" for code contribution
-
-### [](https://github.com/openvinotoolkit/openvino/blob/master/CONTRIBUTING.md#the-instruction-in-brief)The instruction in brief
-
--   Register at GitHub. Create your fork of the OpenVINO™ repository  [https://github.com/openvinotoolkit/openvino](https://github.com/openvinotoolkit/openvino)  (see  [https://help.github.com/articles/fork-a-repo](https://help.github.com/articles/fork-a-repo)  for details).
--   Install Git.
-    -   Set your user name and email address in Git configuration according to the GitHub account (see  [First-Time-Git-Setup](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup)  for details).
--   Choose a task for yourself. It may be a bugfix or an entirely new piece of code.
--   Choose a base branch for your work. More details about branches and policies are here:  [Branches](https://github.com/openvinotoolkit/openvino/wiki/Branches)
--   Clone your fork to your computer.
--   Create a new branch (give it a meaningful name) from the base branch of your choice.
--   Modify / add the code, following our  [Coding Style Guide](./docs/dev/coding_style.md).
--   If you want to add a new sample, please have a look at the  [Guide for contributing to C++/C/Python IE samples](https://github.com/openvinotoolkit/openvino/wiki/SampleContribute)
--   If you want to contribute to the documentation and want to add a new guide, follow that instruction [Documentation guidelines](https://github.com/openvinotoolkit/openvino/wiki/CodingStyleGuideLinesDocumentation)
--   Run testsuite locally:
-    -   execute each test binary from the artifacts directory, e.g.  `<source dir>/bin/intel64/Release/ieFuncTests`
--   When you are done, make sure that your branch is up to date with latest state of the branch you want to contribute to (e.g.  `git fetch upstream && git merge upstream/master`). If so, push your branch to your GitHub fork and create a pull request from your branch to the base branch (see  [using-pull-requests](https://help.github.com/articles/using-pull-requests)  for details).
-
-## Making a good pull request
-
-Following these guidelines will increase the likelihood of your pull request being accepted:
-
--   One PR – one issue.
--   Build perfectly on your local system.
--   Choose the right base branch, based on our [Branch Guidelines](https://github.com/openvinotoolkit/openvino/wiki/Branches).
--   Follow the  [Coding Style Guide](./docs/dev/coding_style.md) for your code.
--   Document your contribution, if you decide it may benefit OpenVINO users. You may do it yourself by editing the files in the "docs" directory or contact someone working with documentation to provide them with the right information.
--   Cover your changes with test. 
--   Add the license statement at the top of new files [C++ example](https://github.com/openvinotoolkit/openvino/blob/master/samples/cpp/classification_sample_async/main.cpp#L1-L2), [Python example](https://github.com/openvinotoolkit/openvino/blob/master/samples/python/hello_classification/hello_classification.py#L3-L4). 
--   Add proper information to the PR: a meaningful title, the reason why you made the commit, and a link to the issue page, if it exists.
--   Remove changes unrelated to the PR.
--   If it is still WIP and you want to check CI test results early, use a  _Draft_  PR.
--   Submit your PR and become an OpenVINO™ contributor! 
-
-
-## Testing and merging pull requests
-
-Your pull request will be automatically tested by OpenVINO™'s precommit (testing statuses are automatically reported as "green" or "red" circles in precommit steps on the PR page). If any builders fail, you need to fix the issues before the PR can be merged. If you push any changes to your branch on GitHub the tests will re-run automatically. No need to close pull request and open a new one!
-
-
-When an assigned reviewer accepts the pull request and the pre-commit is "green", the review status is set to "Approved", which informs OpenVINO™ maintainers that they can merge your pull request.
+# Contributing to OpenVINO
+
+## How to contribute to the OpenVINO project
+
+OpenVINO™ is always looking for opportunities to improve and your contributions 
+play a big role in this process. There are several ways you can make the 
+product better:
+
+
+### Provide Feedback
+
+   * **Report bugs / issues**  
+     If you experience faulty behavior in OpenVINO or its components, you can 
+     [create a new issue](https://github.com/openvinotoolkit/openvino/issues)
+     in the GitHub issue tracker. 
+
+   * **Propose new features / improvements**  
+     If you have a suggestion for improving OpenVINO or want to share your ideas, you can open a new
+     [GitHub Discussion](https://github.com/openvinotoolkit/openvino/discussions). 
+     If your idea is already well defined, you can also create a 
+     [Feature Request Issue](https://github.com/openvinotoolkit/openvino/issues/new?assignees=octocat&labels=enhancement%2Cfeature&projects=&template=feature_request.yml&title=%5BFeature+Request%5D%3A+)
+     In both cases, provide a detailed description, including use cases, benefits, and potential challenges.
+     If your points are especially well aligned with the product vision, they will be included in the 
+     [development roadmap](./ROADMAP.md).
+     User feedback is crucial for OpenVINO development and even if your input is not immediately prioritized,
+     it may be used at a later time or undertaken by the community, regardless of the official roadmap.
+
+
+### Contribute Code Changes
+
+   * **Fix Bugs or Develop New Features**  
+     If you want to help improving OpenVINO, choose one of the issues reported in 
+     [GitHub Issue Tracker](https://github.com/openvinotoolkit/openvino/issues) and 
+     [create a Pull Request](./CONTRIBUTING_PR.md) addressing it. Consider one of the
+     tasks listed as [first-time contributions](https://github.com/openvinotoolkit/openvino/issues/17502).
+     If the feature you want to develop is more complex or not well defined by the reporter, 
+     it is always a good idea to [discuss it](https://github.com/openvinotoolkit/openvino/discussions) 
+     with OpenVINO developers first. Before creating a new PR, check if nobody is already
+     working on it. In such a case, you may still help, having aligned with the other developer.
+
+     Importantly, always check if the change hasn't been implemented before you start working on it!
+     You can build OpenVINO using the latest master branch and make sure that it still needs your
+     changes. Also, do not address issues that only affect older non-LTS releases, like 2022.2.
+
+   * **Develop a New Device Plugin**  
+     Since the market of computing devices is constantly evolving, OpenVINO is always open to extending
+     its support for new hardware. If you want to run inference on a device that is currently not supported, 
+     you can see how to develop a new plugin for it in the 
+     [Plugin Developer Guide](https://docs.openvino.ai/canonical/openvino_docs_ie_plugin_dg_overview.html).
+
+
+### Improve documentation
+
+   * **OpenVINO developer documentation** is contained entirely in this repository, under the 
+     [./docs/dev](https://github.com/openvinotoolkit/openvino/tree/master/docs/dev) folder.
+
+   * **User documentation** is built from several sources and published at 
+     [docs.openvino.ai](docs.openvino.ai), which is the recommended place for reading 
+     these documents. Use the files maintained in this repository only for editing purposes. 
+
+   * The easiest way to help with documentation is to review it and provide feedback on the 
+     existing articles. Whether you notice a mistake, see the possibility of improving the text, 
+     or think more information should be added, you can reach out to any of the documentation 
+     contributors to discuss the potential changes.
+
+     You can also create a Pull Request directly, following the [editor's guide](./docs/CONTRIBUTING_DOCS.md).
+
+
+### Promote and Support OpenVINO
+
+   * **Popularize OpenVINO**  
+     Articles, tutorials, blog posts, demos, videos, and any other involvement 
+     in the OpenVINO community is always a welcome contribution. If you discuss 
+     or present OpenVINO on various social platforms, you are raising awareness
+     of the product among A.I. enthusiasts and enabling other people to discover
+     the toolkit. Feel free to reach out to OpenVINO developers if you need help
+     with making such community-based content.
+
+   * **Help Other Community Members**  
+     If you are an experienced OpenVINO user and want to help, you can always 
+     share your expertise with the community. Check GitHub Discussions and 
+     Issues to see if you can help someone. 
+
+
+## License
+
+By contributing to the OpenVINO project, you agree that your contributions will be 
+licensed under the terms stated in the [LICENSE](./LICENSE.md) file.

CONTRIBUTING_DOCS.md

@@ -0,0 +1,111 @@
+# OpenVINO Documentation Guide
+
+## Basic article structure
+
+OpenVINO documentation is built using Sphinx and the reStructuredText formatting. 
+That means the basic formatting rules need to be used:
+
+
+### White Spaces
+
+OpenVINO documentation is developed to be easily readable in both html and 
+reStructuredText. Here are some suggestions on how to make it render nicely 
+and improve document clarity.
+
+### Headings (including the article title)
+
+They are made by "underscoring" text with punctuation marks (at least as 
+many marks as letters in the underscored header). We use the following convention:
+
+```
+   H1
+   ==================== 
+    
+   H2
+   ####################  
+    
+   H3
+   ++++++++++++++++++++ 
+    
+   H4
+   --------------------
+    
+   H5
+   ....................
+```
+
+### Line length
+
+In programming, a limit of 80 characters per line is a common BKM. It may also apply 
+to reading natural languages fairly well. For this reason, we aim at lines of around 
+70 to 100 characters long. The limit is not a strict rule but rather a guideline to 
+follow in most cases. The breaks will not translate to html, and rightly so, but will 
+make reading and editing documents in GitHub or an editor much easier.
+
+### Tables 
+
+Tables may be difficult to implement well in websites. For example, longer portions 
+of text, like descriptions, may render them difficult to read (e.g. improper cell 
+widths or heights). Complex tables may also be difficult to read in source files. 
+To prevent that, check the [table directive documentation](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#table-directives)
+and see our custom directives. Use the following guidelines for easier editing:
+
+* For very big and complex data sets: use a list instead of a table or remove 
+  the problematic content from the table and implement it differently. 
+* For very big and complex data sets that need to use tables: use an external 
+  file (e.g. PDF) and link to it.
+* For medium tables that look bad in source (e.g. due to long lines of text), 
+  use the reStructuredText list table format.
+* For medium and small tables, use the reStructuredText grid or simple table formats.
+
+
+## Cross-linking
+
+There are several directives Sphinx uses for linking, each has its purpose and format. 
+Follow these guidelines for consistent results:
+
+* Avoid absolute references to internal documents as much as possible (link to source, not html).
+* Note that sphinx uses the "back-tick" character and not the "inverted-comma" => ` vs. '
+* When a file path starts at the same directory is used, put "./" at its beginning.
+* Always add a space before the opening angle bracket ("<") for target files.
+
+Use the following formatting for different links:
+
+* link to an external page / file
+  * `` `text <url> `__ ``
+  * use a double underscore for consistency
+
+* link to an internal documentation page / file
+  * `` :doc:`a docs page <relative file path>` ``
+  * Link to an rst or md file within our documentation, so that it renders properly in html
+
+* link to a header on the same page
+  * `` 'a header in the same article <this-is-section-header-title>`__ ``
+  * anchors are created automatically for all existing headers
+  * such anchor looks like the header, with minor adjustments:
+    * all letters are lower case,
+    * remove all special glyphs, like brackets,
+    * replace spaces with hyphens 
+
+* Create an anchor in an article
+   * `` .. _anchor-in-the target-article:: ``
+   * put it before the header to which you want to link
+   * See the rules for naming anchors / labels at the bottom of this article
+
+* link to an anchor on a different page in our documentation
+   * `` :ref:`the created anchor <anchor-in-the target-article>` ``
+   * link to the anchor using just its name
+
+
+* anchors / labels 
+
+  Read about anchors 
+
+  Sphinx uses labels to create html anchors, which can be linked to from anywhere in documentation. 
+  Although they may be put at the top of any article to make linking to it very easy, we do not use 
+  this approach. Every label definition starts with an underscore, the underscore is not used in links.
+
+  Most importantly, every label needs to be globally unique. It means that it is always a good 
+  practice to start their labels with a clear identifier of the article they reside in.
+
+

CONTRIBUTING_PR.md

@@ -0,0 +1,63 @@
+# How to Prepare a Good PR
+
+   OpenVINO is an open-source project and you can contribute to its code directly. 
+   To do so, follow these guidelines for creating Pull Requests, so that your 
+   changes get the highest chance of being merged.
+
+
+## General Rules of a Good Pull Request
+
+* Create your own fork of the repository and use it to create PRs. 
+  Avoid creating change branches in the main repository.
+* Choose a proper branch for your work and create your own branch based on it. 
+* Give your branches, commits, and Pull Requests meaningful names and descriptions. 
+  It helps to track changes later. If your changes cover a particular component, 
+  you can indicate it in the PR name as a prefix, for example: ``[DOCS] PR name``.
+* Follow the [OpenVINO code style guide](https://github.com/openvinotoolkit/openvino/blob/master/docs/dev/coding_style.md).
+* Make your PRs small - each PR should address one issue. Remove all changes 
+  unrelated to the PR.
+* Document your contribution! If your changes may impact how the user works with
+  OpenVINO, provide the information in proper articles. You can do it yourself, 
+  or contact one of OpenVINO documentation contributors to work together on
+  developing the right content. 
+* For Work In Progress, or checking test results early, use a Draft PR.
+
+
+## Ensure Change Quality
+
+Your pull request will be automatically tested by OpenVINO™'s pre-commit and marked 
+as "green" if it is ready for merging. If any builders fail, the status is "red," 
+you need to fix the issues listed in console logs. Any change to the PR branch will 
+automatically trigger the checks, so you don't need to recreate the PR, Just wait
+for the updated results. 
+
+Regardless of the automated tests, you should ensure the quality of your changes:
+
+* Test your changes locally:
+  * Make sure to double-check your code. 
+  * Run tests locally to identify and fix potential issues (execute test binaries 
+    from the artifacts directory, e.g. ``<source dir>/bin/intel64/Release/ieFuncTests``)
+* Before creating a PR, make sure that your branch is up to date with the latest 
+  state of the branch you want to contribute to (e.g. git fetch upstream && git 
+  merge upstream/master).
+
+
+## Branching Policy
+
+* The "master" branch is used for development and constitutes the base for each new release.
+* Each OpenVINO release has its own branch: ``releases/<year>/<release number>``.
+* The final release each year is considered a Long Term Support version, 
+  which means it remains active.
+* Contributions are accepted only by active branches, which are:
+  * the "master" branch for future releases,
+  * the most recently published version for fixes,
+  * LTS versions (for two years from their release dates).
+
+
+## Need Additional Help? Check these Articles
+
+* [How to create a fork](https://help.github.com/articles/fork-a-rep) 
+* [Install Git](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup)
+* If you want to add a new sample, please have a look at the Guide for contributing
+  to C++/C/Python IE samples and add the license statement at the top of new files for
+  C++ example, Python example.