Skip to content

Commit 3e6a3ee

Browse files
kblaszczak-intelkblaszczak-intel
authored
[DOCS] contributing guidelines (openvinotoolkit#19218)
changes to the contribution guide
1 parent 7635f89 commit 3e6a3ee

File tree

3 files changed

+262
-53
lines changed

3 files changed

+262
-53
lines changed

‎CONTRIBUTING.md

+88-53
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,88 @@
1-
# How to contribute to the OpenVINO repository
2-
3-
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.
4-
5-
6-
## Before you start contributing you should
7-
8-
- Make sure you agree to contribute your code under [OpenVINO™ (Apache 2.0) license](https://github.com/openvinotoolkit/openvino/blob/master/LICENSE).
9-
- 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.
10-
- 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)).
11-
12-
13-
## "Fork & Pull Request model" for code contribution
14-
15-
### [](https://github.com/openvinotoolkit/openvino/blob/master/CONTRIBUTING.md#the-instruction-in-brief)The instruction in brief
16-
17-
- 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).
18-
- Install Git.
19-
- 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).
20-
- Choose a task for yourself. It may be a bugfix or an entirely new piece of code.
21-
- Choose a base branch for your work. More details about branches and policies are here: [Branches](https://github.com/openvinotoolkit/openvino/wiki/Branches)
22-
- Clone your fork to your computer.
23-
- Create a new branch (give it a meaningful name) from the base branch of your choice.
24-
- Modify / add the code, following our [Coding Style Guide](./docs/dev/coding_style.md).
25-
- 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)
26-
- 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)
27-
- Run testsuite locally:
28-
- execute each test binary from the artifacts directory, e.g. `<source dir>/bin/intel64/Release/ieFuncTests`
29-
- 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).
30-
31-
## Making a good pull request
32-
33-
Following these guidelines will increase the likelihood of your pull request being accepted:
34-
35-
- One PR – one issue.
36-
- Build perfectly on your local system.
37-
- Choose the right base branch, based on our [Branch Guidelines](https://github.com/openvinotoolkit/openvino/wiki/Branches).
38-
- Follow the [Coding Style Guide](./docs/dev/coding_style.md) for your code.
39-
- 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.
40-
- Cover your changes with test.
41-
- 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).
42-
- 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.
43-
- Remove changes unrelated to the PR.
44-
- If it is still WIP and you want to check CI test results early, use a _Draft_ PR.
45-
- Submit your PR and become an OpenVINO™ contributor!
46-
47-
48-
## Testing and merging pull requests
49-
50-
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!
51-
52-
53-
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.
1+
# Contributing to OpenVINO
2+
3+
## How to contribute to the OpenVINO project
4+
5+
OpenVINO™ is always looking for opportunities to improve and your contributions
6+
play a big role in this process. There are several ways you can make the
7+
product better:
8+
9+
10+
### Provide Feedback
11+
12+
* **Report bugs / issues**
13+
If you experience faulty behavior in OpenVINO or its components, you can
14+
[create a new issue](https://github.com/openvinotoolkit/openvino/issues)
15+
in the GitHub issue tracker.
16+
17+
* **Propose new features / improvements**
18+
If you have a suggestion for improving OpenVINO or want to share your ideas, you can open a new
19+
[GitHub Discussion](https://github.com/openvinotoolkit/openvino/discussions).
20+
If your idea is already well defined, you can also create a
21+
[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+)
22+
In both cases, provide a detailed description, including use cases, benefits, and potential challenges.
23+
If your points are especially well aligned with the product vision, they will be included in the
24+
[development roadmap](./ROADMAP.md).
25+
User feedback is crucial for OpenVINO development and even if your input is not immediately prioritized,
26+
it may be used at a later time or undertaken by the community, regardless of the official roadmap.
27+
28+
29+
### Contribute Code Changes
30+
31+
* **Fix Bugs or Develop New Features**
32+
If you want to help improving OpenVINO, choose one of the issues reported in
33+
[GitHub Issue Tracker](https://github.com/openvinotoolkit/openvino/issues) and
34+
[create a Pull Request](./CONTRIBUTING_PR.md) addressing it. Consider one of the
35+
tasks listed as [first-time contributions](https://github.com/openvinotoolkit/openvino/issues/17502).
36+
If the feature you want to develop is more complex or not well defined by the reporter,
37+
it is always a good idea to [discuss it](https://github.com/openvinotoolkit/openvino/discussions)
38+
with OpenVINO developers first. Before creating a new PR, check if nobody is already
39+
working on it. In such a case, you may still help, having aligned with the other developer.
40+
41+
Importantly, always check if the change hasn't been implemented before you start working on it!
42+
You can build OpenVINO using the latest master branch and make sure that it still needs your
43+
changes. Also, do not address issues that only affect older non-LTS releases, like 2022.2.
44+
45+
* **Develop a New Device Plugin**
46+
Since the market of computing devices is constantly evolving, OpenVINO is always open to extending
47+
its support for new hardware. If you want to run inference on a device that is currently not supported,
48+
you can see how to develop a new plugin for it in the
49+
[Plugin Developer Guide](https://docs.openvino.ai/canonical/openvino_docs_ie_plugin_dg_overview.html).
50+
51+
52+
### Improve documentation
53+
54+
* **OpenVINO developer documentation** is contained entirely in this repository, under the
55+
[./docs/dev](https://github.com/openvinotoolkit/openvino/tree/master/docs/dev) folder.
56+
57+
* **User documentation** is built from several sources and published at
58+
[docs.openvino.ai](docs.openvino.ai), which is the recommended place for reading
59+
these documents. Use the files maintained in this repository only for editing purposes.
60+
61+
* The easiest way to help with documentation is to review it and provide feedback on the
62+
existing articles. Whether you notice a mistake, see the possibility of improving the text,
63+
or think more information should be added, you can reach out to any of the documentation
64+
contributors to discuss the potential changes.
65+
66+
You can also create a Pull Request directly, following the [editor's guide](./docs/CONTRIBUTING_DOCS.md).
67+
68+
69+
### Promote and Support OpenVINO
70+
71+
* **Popularize OpenVINO**
72+
Articles, tutorials, blog posts, demos, videos, and any other involvement
73+
in the OpenVINO community is always a welcome contribution. If you discuss
74+
or present OpenVINO on various social platforms, you are raising awareness
75+
of the product among A.I. enthusiasts and enabling other people to discover
76+
the toolkit. Feel free to reach out to OpenVINO developers if you need help
77+
with making such community-based content.
78+
79+
* **Help Other Community Members**
80+
If you are an experienced OpenVINO user and want to help, you can always
81+
share your expertise with the community. Check GitHub Discussions and
82+
Issues to see if you can help someone.
83+
84+
85+
## License
86+
87+
By contributing to the OpenVINO project, you agree that your contributions will be
88+
licensed under the terms stated in the [LICENSE](./LICENSE.md) file.

‎CONTRIBUTING_DOCS.md

+111
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# OpenVINO Documentation Guide
2+
3+
## Basic article structure
4+
5+
OpenVINO documentation is built using Sphinx and the reStructuredText formatting.
6+
That means the basic formatting rules need to be used:
7+
8+
9+
### White Spaces
10+
11+
OpenVINO documentation is developed to be easily readable in both html and
12+
reStructuredText. Here are some suggestions on how to make it render nicely
13+
and improve document clarity.
14+
15+
### Headings (including the article title)
16+
17+
They are made by "underscoring" text with punctuation marks (at least as
18+
many marks as letters in the underscored header). We use the following convention:
19+
20+
```
21+
H1
22+
====================
23+
24+
H2
25+
####################
26+
27+
H3
28+
++++++++++++++++++++
29+
30+
H4
31+
--------------------
32+
33+
H5
34+
....................
35+
```
36+
37+
### Line length
38+
39+
In programming, a limit of 80 characters per line is a common BKM. It may also apply
40+
to reading natural languages fairly well. For this reason, we aim at lines of around
41+
70 to 100 characters long. The limit is not a strict rule but rather a guideline to
42+
follow in most cases. The breaks will not translate to html, and rightly so, but will
43+
make reading and editing documents in GitHub or an editor much easier.
44+
45+
### Tables
46+
47+
Tables may be difficult to implement well in websites. For example, longer portions
48+
of text, like descriptions, may render them difficult to read (e.g. improper cell
49+
widths or heights). Complex tables may also be difficult to read in source files.
50+
To prevent that, check the [table directive documentation](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#table-directives)
51+
and see our custom directives. Use the following guidelines for easier editing:
52+
53+
* For very big and complex data sets: use a list instead of a table or remove
54+
the problematic content from the table and implement it differently.
55+
* For very big and complex data sets that need to use tables: use an external
56+
file (e.g. PDF) and link to it.
57+
* For medium tables that look bad in source (e.g. due to long lines of text),
58+
use the reStructuredText list table format.
59+
* For medium and small tables, use the reStructuredText grid or simple table formats.
60+
61+
62+
## Cross-linking
63+
64+
There are several directives Sphinx uses for linking, each has its purpose and format.
65+
Follow these guidelines for consistent results:
66+
67+
* Avoid absolute references to internal documents as much as possible (link to source, not html).
68+
* Note that sphinx uses the "back-tick" character and not the "inverted-comma" => ` vs. '
69+
* When a file path starts at the same directory is used, put "./" at its beginning.
70+
* Always add a space before the opening angle bracket ("<") for target files.
71+
72+
Use the following formatting for different links:
73+
74+
* link to an external page / file
75+
* `` `text <url> `__ ``
76+
* use a double underscore for consistency
77+
78+
* link to an internal documentation page / file
79+
* `` :doc:`a docs page <relative file path>` ``
80+
* Link to an rst or md file within our documentation, so that it renders properly in html
81+
82+
* link to a header on the same page
83+
* `` 'a header in the same article <this-is-section-header-title>`__ ``
84+
* anchors are created automatically for all existing headers
85+
* such anchor looks like the header, with minor adjustments:
86+
* all letters are lower case,
87+
* remove all special glyphs, like brackets,
88+
* replace spaces with hyphens
89+
90+
* Create an anchor in an article
91+
* `` .. _anchor-in-the target-article:: ``
92+
* put it before the header to which you want to link
93+
* See the rules for naming anchors / labels at the bottom of this article
94+
95+
* link to an anchor on a different page in our documentation
96+
* `` :ref:`the created anchor <anchor-in-the target-article>` ``
97+
* link to the anchor using just its name
98+
99+
100+
* anchors / labels
101+
102+
Read about anchors
103+
104+
Sphinx uses labels to create html anchors, which can be linked to from anywhere in documentation.
105+
Although they may be put at the top of any article to make linking to it very easy, we do not use
106+
this approach. Every label definition starts with an underscore, the underscore is not used in links.
107+
108+
Most importantly, every label needs to be globally unique. It means that it is always a good
109+
practice to start their labels with a clear identifier of the article they reside in.
110+
111+

‎CONTRIBUTING_PR.md

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

0 commit comments

Comments
 (0)