esp-idf/CONTRIBUTING.rst

Contributions Guide
===================

We welcome contributions to the esp-idf project!

How to Contribute
-----------------

Contributions to esp-idf - fixing bugs, adding features, adding documentation - are welcome. We accept contributions via `Github Pull Requests <https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests>`_.

Before Contributing
-------------------

Before sending us a Pull Request, please consider this list of points:

* Is the contribution entirely your own work, or already licensed under an Apache License 2.0 compatible Open Source License? If not then we unfortunately cannot accept it. Please check the :doc:`Copyright Header Guide <copyright-guide>` for additional information.

* Does any new code conform to the esp-idf :doc:`Style Guide <style-guide>`?

* Have you installed the :doc:`pre-commit hook <install-pre-commit-hook>` for esp-idf project?

* Does the code documentation follow requirements in :doc:`documenting-code`?

* Is the code adequately commented for people to understand how it is structured?

* Is there documentation or examples that go with code contributions? There are additional suggestions for writing good examples in :idf:`examples` readme.

* Are comments and documentation written in clear English, with no spelling or grammar errors?

* Example contributions are also welcome. Please check the :doc:`creating-examples` guide for these.

* If the contribution contains multiple commits, are they grouped together into logical changes (one major change per pull request)? Are any commits with names like "fixed typo" `squashed into previous commits <https://eli.thegreenplace.net/2014/02/19/squashing-github-pull-requests-into-a-single-commit/>`_?

* If you're unsure about any of these points, please open the Pull Request anyhow and then ask us for feedback.

Pull Request Process
--------------------

After you open the Pull Request, there will probably be some discussion in the comments field of the request itself.

Once the Pull Request is ready to merge, it will first be merged into our internal git system for in-house automated testing.

If this process passes, it will be merged onto the public github repository.

Legal Part
----------

Before a contribution can be accepted, you will need to sign our :doc:`contributor-agreement`. You will be prompted for this automatically as part of the Pull Request process.

Related Documents
-----------------

.. toctree::
    :maxdepth: 1

    style-guide
    install-pre-commit-hook
    documenting-code
    creating-examples
    ../api-reference/template
    contributor-agreement
    copyright-guide
Renamed .md to .rst 2016-10-23 20:12:34 +00:00			`Contributions Guide`
			`===================`
Documentation: Add contributor guide, expand README & add an examples README 2016-09-21 07:25:36 +00:00
			`We welcome contributions to the esp-idf project!`

Renamed .md to .rst 2016-10-23 20:12:34 +00:00			`How to Contribute`
			`-----------------`
Documentation: Add contributor guide, expand README & add an examples README 2016-09-21 07:25:36 +00:00
docs: Fix broken URLs & permanent redirects 2020-03-22 23:27:51 +00:00			Contributions to esp-idf - fixing bugs, adding features, adding documentation - are welcome. We accept contributions via `Github Pull Requests <https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests>`_.
Documentation: Add contributor guide, expand README & add an examples README 2016-09-21 07:25:36 +00:00
Renamed .md to .rst 2016-10-23 20:12:34 +00:00			`Before Contributing`
			`-------------------`
Documentation: Add contributor guide, expand README & add an examples README 2016-09-21 07:25:36 +00:00
			`Before sending us a Pull Request, please consider this list of points:`

Docs: Add copyright header guide for contributions 2021-11-02 15:31:51 +00:00			* Is the contribution entirely your own work, or already licensed under an Apache License 2.0 compatible Open Source License? If not then we unfortunately cannot accept it. Please check the :doc:`Copyright Header Guide <copyright-guide>` for additional information.
Documentation: Add contributor guide, expand README & add an examples README 2016-09-21 07:25:36 +00:00
docs: Hyperlinks to guides 2016-11-16 19:11:32 +00:00			* Does any new code conform to the esp-idf :doc:`Style Guide <style-guide>`?

add contributing docs 2020-10-30 11:31:55 +00:00			* Have you installed the :doc:`pre-commit hook <install-pre-commit-hook>` for esp-idf project?
CI: Add pre-commit for esp-idf project. add tools/ci/python_packages/idf_ci.py for some util functions used in ci and needs multi-os solution 2020-10-21 11:30:49 +00:00
docs: Hyperlinks to guides 2016-11-16 19:11:32 +00:00			* Does the code documentation follow requirements in :doc:`documenting-code`?
Documentation: Add contributor guide, expand README & add an examples README 2016-09-21 07:25:36 +00:00
			`* Is the code adequately commented for people to understand how it is structured?`

docs: use custom roles to generate GitHub links This change replaces direct links to GitHub master branch with auto-generated links using docutils custom roles. These auto-generated links point to the tree or blob for the git commit ID (or tag) of the repository. This is needed to ensure that links don’t become broken when files in master branch are moved around or deleted. The following roles are introduced: - :idf:`path` - points to directory inside ESP-IDF - :idf_blob:`path` - points to file inside ESP-IDF - :idf_raw:`path` - points to raw view of the file inside ESP-IDF - :component:`path` - points to directory inside ESP-IDF components dir - :component_blob:`path` - points to file inside ESP-IDF components dir - :component_raw:`path` - points to raw view of the file inside ESP-IDF components dir - :example:`path` - points to directory inside ESP-IDF examples dir - :example_blob:`path` - points to file inside ESP-IDF examples dir - :example_raw:`path` - points to raw view of the file inside ESP-IDF examples dir A check is added to the CI build script, which searches RST files for presence of hard-coded links (identified by tree/master, blob/master, or raw/master part of the URL). This check can be run manually: cd docs && make gh-linkcheck Additionally, Sphinx linkcheck build type is used to create new CI test, which check for broken links. This test has to be triggered explicitly, because including it in normal build process (when the commit is not yet deployed to Github) will not work. It can be triggered in a regular fashion using a combination of cron and Curl, similar to stress tests. 2017-01-19 08:16:06 +00:00			* Is there documentation or examples that go with code contributions? There are additional suggestions for writing good examples in :idf:`examples` readme.
Documentation: Add contributor guide, expand README & add an examples README 2016-09-21 07:25:36 +00:00
			`* Are comments and documentation written in clear English, with no spelling or grammar errors?`

docs: Add "Creating Examples" docs page, template example README 2018-06-08 01:18:14 +00:00			* Example contributions are also welcome. Please check the :doc:`creating-examples` guide for these.

docs: Fix broken URLs & permanent redirects 2020-03-22 23:27:51 +00:00			* If the contribution contains multiple commits, are they grouped together into logical changes (one major change per pull request)? Are any commits with names like "fixed typo" `squashed into previous commits <https://eli.thegreenplace.net/2014/02/19/squashing-github-pull-requests-into-a-single-commit/>`_?
Documentation: Add contributor guide, expand README & add an examples README 2016-09-21 07:25:36 +00:00
			`* If you're unsure about any of these points, please open the Pull Request anyhow and then ask us for feedback.`

Renamed .md to .rst 2016-10-23 20:12:34 +00:00			`Pull Request Process`
			`--------------------`
Documentation: Add contributor guide, expand README & add an examples README 2016-09-21 07:25:36 +00:00
			`After you open the Pull Request, there will probably be some discussion in the comments field of the request itself.`

			`Once the Pull Request is ready to merge, it will first be merged into our internal git system for in-house automated testing.`

			`If this process passes, it will be merged onto the public github repository.`

Renamed .md to .rst 2016-10-23 20:12:34 +00:00			`Legal Part`
			`----------`
Documentation: Add contributor guide, expand README & add an examples README 2016-09-21 07:25:36 +00:00
Fixed broken links 2016-11-05 16:04:35 +00:00			Before a contribution can be accepted, you will need to sign our :doc:`contributor-agreement`. You will be prompted for this automatically as part of the Pull Request process.

Getting started guides 2017-03-26 22:01:52 +00:00			`Related Documents`
			`-----------------`
API template - reflected template in other DRAFT API dcouments - DRAFT of Bluetooth API - link fixes in CONTRIBUTING.rst 2016-10-26 19:08:36 +00:00
Getting started guides 2017-03-26 22:01:52 +00:00			`.. toctree::`
			`:maxdepth: 1`
API template - reflected template in other DRAFT API dcouments - DRAFT of Bluetooth API - link fixes in CONTRIBUTING.rst 2016-10-26 19:08:36 +00:00
Getting started guides 2017-03-26 22:01:52 +00:00			`style-guide`
add contributing docs 2020-10-30 11:31:55 +00:00			`install-pre-commit-hook`
Getting started guides 2017-03-26 22:01:52 +00:00			`documenting-code`
docs: Add "Creating Examples" docs page, template example README 2018-06-08 01:18:14 +00:00			`creating-examples`
Getting started guides 2017-03-26 22:01:52 +00:00			`../api-reference/template`
docs: Add "Creating Examples" docs page, template example README 2018-06-08 01:18:14 +00:00			`contributor-agreement`
Docs: Add copyright header guide for contributions 2021-11-02 15:31:51 +00:00			`copyright-guide`