Split contributing docs to multiple files (#36969)

Following #36936 and the fact that GitHub stopped rendering big .rst
files, we also split CONTRIBUTING.rst into multiplet files. It will be
much easier to follow and it will render in GitHub.

(cherry picked from commit 8708bff)

.gitattributes

@@ -14,13 +14,10 @@ chart/charts/** export-ignore
 Dockerfile.ci export-ignore
 
 ISSUE_TRIAGE_PROCESS.rst export-ignore
-STATIC_CODE_CHECKS.rst export-ignore
-TESTING.rst export-ignore
-LOCAL_VIRTUALENV.rst export-ignore
 CONTRIBUTING.rst export-ignore
 CI.rst export-ignore
 CI_DIAGRAMS.md export-ignore
-CONTRIBUTORS_QUICK_START.rst export-ignore
+contributing_docs/ export-ignore
 
 .devcontainer export-ignore
 .github export-ignore

.github/PULL_REQUEST_TEMPLATE.md

@@ -38,7 +38,7 @@ http://chris.beams.io/posts/git-commit/
 <!-- Please keep an empty line above the dashes. -->
 ---
 **^ Add meaningful description above**
-Read the **[Pull Request Guidelines](https://github.com/apache/airflow/blob/main/CONTRIBUTING.rst#pull-request-guidelines)** for more information.
+Read the **[Pull Request Guidelines](https://github.com/apache/airflow/blob/main/contributing-docs/05_pull_requests.rst#pull-request-guidelines)** for more information.
 In case of fundamental code changes, an Airflow Improvement Proposal ([AIP](https://cwiki.apache.org/confluence/display/AIRFLOW/Airflow+Improvement+Proposals)) is needed.
 In case of a new dependency, check compliance with the [ASF 3rd Party License Policy](https://www.apache.org/legal/resolved.html#category-x).
 In case of backwards incompatible changes please leave a note in a newsfragment file, named `{pr_number}.significant.rst` or `{issue_number}.significant.rst`, in [newsfragments](https://github.com/apache/airflow/tree/main/newsfragments).

.github/SECURITY.md

@@ -17,6 +17,14 @@
  under the License.
 -->
 
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [Reporting Vulnerabilities](#reporting-vulnerabilities)
+- [How are security issues handled in Airflow](#how-are-security-issues-handled-in-airflow)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 This document contains information on how to report security vulnerabilities in Apache Airflow and
 how security issues reported to the Apache Airflow security team are handled. If you would like
 to learn more, head to the
@@ -72,7 +80,28 @@ If you wish to know more about the ASF security process, the
 how vulnerability reports are handled in general by all ASF projects, and includes PGP keys if
 you wish to use them when you report the issues.
 
-## Security vulnerabilities in Airflow and Airflow community managed providers
+
+### What happens after you report the issue ?
+
+The Airflow Security Team will get back to you after assessing the report. You will usually get
+confirmation that the issue is being worked (or that we quickly assessed it as invalid) within several
+business days. Note that this is an Open-Source projects and members of the security team are volunteers
+so please make sure to be patient. If you do not get a response within a week or so, please send a
+kind reminder to the security team. We will usually let you know the CVE number that will be assigned
+to the issue and the severity of the issue as well as release the issue is scheduled to be fixed
+after we assess the issue (which might take longer or shorter time depending on the issue complexity and
+potential impact, severity, whether we want to address a whole class issues in a single fix and a number
+of other factors). You should subscribe  and monitor the `users@airflow.apache.org` mailing
+list or `announce@apache.org` to see the announcement of the security issue - including the CVE number
+and the severity of the issue once the issue is fixed and release is public. Note that the
+`announce@apache.org` mailing list is moderated, and it might take a few hours for the announcement to
+appear there, so `users@airflow.apache.org` is the best place to monitor for the announcement.
+
+Security issues in Airflow are handled by the Airflow Security Team. Details about the Airflow Security
+Team and how members of it are chosen can be found in the
+[Contributing documentation](https://github.com/apache/airflow/blob/main/contributing-docs/01_roles_in_airflow_project.rst#security-team).
+
+### Does CVE in Airflow Providers impact Airflow core package ?
 
 Airflow core package is released separately from provider packages. While Airflow comes with ``constraints``
 which describe which version of providers have been tested when the version of Airflow was released, the

.github/boring-cyborg.yml

@@ -547,10 +547,8 @@ labelPRBasedOnFilePath:
     - dev/**/*
     - .github/**/*
     - Dockerfile.ci
-    - CONTRIBUTING.*
-    - LOCAL_VIRTUALENV.rst
-    - STATIC_CODE_CHECKS.rst
-    - TESTING.rst
+    - CONTRIBUTING.rst
+    - contributing-docs/**/*
     - yamllint-config.yml
     - .asf.yaml
     - .bash_completion
@@ -681,20 +679,20 @@ labelerFlags:
 firstPRWelcomeComment: >
   Congratulations on your first Pull Request and welcome to the Apache Airflow community!
   If you have any issues or are unsure about any anything please check our
-  Contribution Guide (https://github.com/apache/airflow/blob/main/CONTRIBUTING.rst)
+  Contributors' Guide (https://github.com/apache/airflow/blob/main/contributing-docs/README.rst)
 
   Here are some useful points:
 
   - Pay attention to the quality of your code (ruff, mypy and type annotations). Our [pre-commits](
-  https://github.com/apache/airflow/blob/main/STATIC_CODE_CHECKS.rst#prerequisites-for-pre-commit-hooks)
+  https://github.com/apache/airflow/blob/main/contributing-docs/08_static_code_checks.rst#prerequisites-for-pre-commit-hooks)
   will help you with that.
 
   - In case of a new feature add useful documentation (in docstrings or in `docs/` directory).
   Adding a new operator? Check this short
   [guide](https://github.com/apache/airflow/blob/main/docs/apache-airflow/howto/custom-operator.rst)
   Consider adding an example DAG that shows how users should use it.
 
-  - Consider using [Breeze environment](https://github.com/apache/airflow/blob/main/dev/breeze/doc/breeze.rst)
+  - Consider using [Breeze environment](https://github.com/apache/airflow/blob/main/dev/breeze/doc/README.rst)
   for testing locally, it's a heavy docker but it ships with a working Airflow and a lot of integrations.
 
   - Be patient and persistent. It might take some time to get a review or get the final approval from
@@ -704,7 +702,7 @@ firstPRWelcomeComment: >
   communication including (but not limited to) comments on Pull Requests, Mailing list and Slack.
 
   - Be sure to read the [Airflow Coding style](
-  https://github.com/apache/airflow/blob/main/CONTRIBUTING.rst#coding-style-and-best-practices).
+  https://github.com/apache/airflow/blob/main/contributing-docs/05_pull_requests.rst#coding-style-and-best-practices).
 
   - Always keep your Pull Requests rebased, otherwise your build might fail due to changes not related
   to your commits.

.pre-commit-config.yaml

@@ -33,7 +33,7 @@ repos:
       - id: doctoc
         name: Add TOC for Markdown and RST files
         files:
-          ^CONTRIBUTING\.md$|^README\.md$|^UPDATING.*\.md$|^chart/UPDATING.*\.md$|^dev/.*\.md$|^dev/.*\.rst$
+          ^README\.md$|^UPDATING.*\.md$|^chart/UPDATING.*\.md$|^dev/.*\.md$|^dev/.*\.rst$|^.github/.*\.md|^tests/system/README.md$
         exclude: ^.*/.*_vendor/
         args:
           - "--maxlevel"
@@ -440,7 +440,7 @@ repos:
         name: Update extras in documentation
         entry: ./scripts/ci/pre_commit/pre_commit_insert_extras.py
         language: python
-        files: ^setup\.py$|^CONTRIBUTING\.rst$|^INSTALL$|^airflow/providers/.*/provider\.yaml$
+        files: ^setup\.py$|^contributing-docs/12_airflow_dependencies_and_extras.rst$|^INSTALL$|^airflow/providers/.*/provider\.yaml$
         pass_filenames: false
         additional_dependencies: ['rich>=12.4.4', 'tomli']
       - id: check-extras-order
@@ -612,7 +612,7 @@ repos:
           ^.pre-commit-config\.yaml$|
           ^.*CHANGELOG\.(rst|txt)$|
           ^.*RELEASE_NOTES\.rst$|
-          ^CONTRIBUTORS_QUICK_START.rst$|
+          ^contributing-docs/03_contributors_quick_start.rst$|
           ^.*\.(png|gif|jp[e]?g|tgz|lock)$|
           git
       - id: check-base-operator-partial-arguments
@@ -818,7 +818,7 @@ repos:
         name: Sync integrations list with docs
         entry: ./scripts/ci/pre_commit/pre_commit_check_integrations_list.py
         language: python
-        files: ^scripts/ci/docker-compose/integration-.*\.yml$|^TESTING.rst$
+        files: ^scripts/ci/docker-compose/integration-.*\.yml$|^contributing-docs/testing/integration_tests.rst$
         additional_dependencies: ['black==23.10.0', 'tabulate', 'rich>=12.4.4', 'pyyaml']
         require_serial: true
         pass_filenames: false

BREEZE.rst

@@ -15,4 +15,4 @@
     specific language governing permissions and limitations
     under the License.
 
-Content of this guide has been moved to `Breeze docs internal folder <dev/breeze/doc/breeze.rst>`_
+Content of this guide has been moved to `Breeze docs internal folder <dev/breeze/doc/README.rst>`_

CI.rst

@@ -486,7 +486,7 @@ infrastructure, as a developer you should be able to reproduce and re-run any of
 locally. One part of it are pre-commit checks, that allow you to run the same static checks in CI
 and locally, but another part is the CI environment which is replicated locally with Breeze.
 
-You can read more about Breeze in `breeze.rst <dev/breeze/doc/breeze.rst>`_ but in essence it is a script that allows
+You can read more about Breeze in `README.rst <dev/breeze/doc/README.rst>`_ but in essence it is a script that allows
 you to re-create CI environment in your local development instance and interact with it. In its basic
 form, when you do development you can run all the same tests that will be run in CI - but locally,
 before you submit them as PR. Another use case where Breeze is useful is when tests fail on CI. You can
@@ -506,7 +506,7 @@ by running the sequence of corresponding ``breeze`` command. Make sure however t
 
 In the output of the CI jobs, you will find both  - the flags passed and environment variables set.
 
-You can read more about it in `Breeze <dev/breeze/doc/breeze.rst>`_ and `Testing <TESTING.rst>`_
+You can read more about it in `Breeze <dev/breeze/doc/README.rst>`_ and `Testing <contributing-docs/09_testing.rst>`_
 
 Since we store images from every CI run, you should be able easily reproduce any of the CI tests problems
 locally. You can do it by pulling and using the right image and running it with the right docker command,
@@ -520,7 +520,7 @@ For example knowing that the CI job was for commit ``cd27124534b46c9688a1d89e75f
 
 
 But you usually need to pass more variables and complex setup if you want to connect to a database or
-enable some integrations. Therefore it is easiest to use `Breeze <dev/breeze/doc/breeze.rst>`_ for that.
+enable some integrations. Therefore it is easiest to use `Breeze <dev/breeze/doc/README.rst>`_ for that.
 For example if you need to reproduce a MySQL environment in python 3.8 environment you can run:
 
 .. code-block:: bash
@@ -533,7 +533,7 @@ this case, you do not need to checkout the sources that were used for that run -
 the image - but remember that any changes you make in those sources are lost when you leave the image as
 the sources are not mapped from your host machine.
 
-Depending whether the scripts are run locally via `Breeze <dev/breeze/doc/breeze.rst>`_ or whether they
+Depending whether the scripts are run locally via `Breeze <dev/breeze/doc/README.rst>`_ or whether they
 are run in ``Build Images`` or ``Tests`` workflows they can take different values.
 
 You can use those variables when you try to reproduce the build locally (alternatively you can pass

COMMITTERS.rst

@@ -15,14 +15,37 @@
     specific language governing permissions and limitations
     under the License.
 
+Committers and PMC members
+==========================
+
+Before reading this document, you should be familiar with `Contributors' guide <contributing-docs/README.rst>`__.
+This document assumes that you are a bit familiar how Airflow's community work, but you would like to learn more
+about the rules by which we add new members.
+
 .. contents:: :local:
 
-Committers and PMC's
-====================
+Committers vs. Maintainers
+--------------------------
+
+Often you can hear two different terms about people who have write access to the Airflow repository -
+"committers" and "maintainers". This is because those two terms are used in different contexts.
+
+* "Maintainers" is term used in GitHub documentation and configuration and is a generic term referring to
+  people who have write access to the repository. They can merge PRs, push to the repository, etc.
+* "Committers" is a term used in Apache Software Foundation (ASF) and is a term referring to people who have
+  write access to the code repository and has a signed
+  [Contributor License Agreement (CLA)](https://www.apache.org/licenses/#clas) on file.  They have an
+  apache.org mail address. This is an official [role](https://www.apache.org/foundation/how-it-works/#roles)
+  defined and governed by the Apache Software Foundation.
 
-This document assumes that you know how Airflow's community work, but you would like to learn more about the rules by which we add new members.
+For all practical purposes, both terms are interchangeable because the Apache Software Foundation rule is
+the only Committers can have write access to the repositories managed by the PMC (Project Management Committee)
+and that all Committers get write access to the repository.
 
-Before reading this document, you should be familiar with `Contributor's guide <https://github.com/apache/airflow/blob/main/CONTRIBUTING.rst>`__.
+You will see both terms used in different documentation, therefore our goal is not to use one of the terms
+only - it is unavoidable to see both terms anyway. As a rule, we are using "committer" term in the context
+of the official rules concerning Apache Software Foundation and "maintainer" term in the context where
+technical GitHub access and permissions to the project are important.
 
 Guidelines to become an Airflow Committer
 ------------------------------------------
@@ -48,8 +71,7 @@ General prerequisites that we look for in all candidates:
 1.  Consistent contribution over last few months
 2.  Visibility on discussions on the dev mailing list, Slack channels or GitHub issues/discussions
 3.  Contributions to community health and project's sustainability for the long-term
-4.  Understands contributor/committer guidelines:
-    `Contributors' Guide <https://github.com/apache/airflow/blob/main/CONTRIBUTING.rst>`__
+4.  Understands contributor/committer guidelines: `Contributors' Guide <contributing-docs/README.rst>`__
 
 
 Code contribution
@@ -194,7 +216,7 @@ To be able to merge PRs, committers have to integrate their GitHub ID with Apach
 3.  Wait at least 30  minutes for an email inviting you to Apache GitHub Organization and accept invitation.
 4.  After accepting the GitHub Invitation verify that you are a member of the `Airflow committers team on GitHub <https://github.com/orgs/apache/teams/airflow-committers>`__.
 5.  Ask in ``#internal-airflow-ci-cd`` channel to be `configured in self-hosted runners <https://github.com/apache/airflow-ci-infra/blob/main/scripts/list_committers>`_
-    by the CI maintainers. Wait for confirmation that this is done and some helpful tips from the CI maintainer
+    by the CI team. Wait for confirmation that this is done and some helpful tips from the CI team
 6.  After confirming that step 5 is done, open a PR to include your GitHub ID in:
 
     * ``dev/breeze/src/airflow_breeze/global_constants.py`` (COMMITTERS variable)