diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
new file mode 100644
index 0000000000..fb329f3b0c
--- /dev/null
+++ b/CONTRIBUTING.rst
@@ -0,0 +1,19 @@
+The source repository for this project can be found at:
+
+ https://opendev.org/openstack/kolla-ansible
+
+Pull requests submitted through GitHub are **not** monitored.
+
+To start contributing to OpenStack, follow the steps in the contribution guide
+to set up and use Gerrit:
+
+ https://docs.openstack.org/contributors/code-and-documentation/quick-start.html
+
+Bugs should be filed on Launchpad:
+
+ https://bugs.launchpad.net/kolla-ansible
+
+For more specific information about contributing to this repository, see the
+Kolla Ansible contributor guide:
+
+ https://docs.openstack.org/kolla-ansible/latest/contributor/contributing.html
diff --git a/doc/source/contributor/CONTRIBUTING.rst b/doc/source/contributor/CONTRIBUTING.rst
deleted file mode 100644
index 0638c70937..0000000000
--- a/doc/source/contributor/CONTRIBUTING.rst
+++ /dev/null
@@ -1,182 +0,0 @@
-.. _CONTRIBUTING:
-
-=================
-How To Contribute
-=================
-
-Basics
-======
-
-#. Our source code is hosted on `OpenDev Kolla-Ansible Git
- <https://opendev.org/openstack/kolla-ansible/>`_. Bugs should be
- filed on `launchpad <https://bugs.launchpad.net/kolla-ansible>`_.
-
-#. Please follow OpenStack `Gerrit Workflow
- <https://docs.openstack.org/infra/manual/developers.html#development-workflow>`__
- to contribute to Kolla-ansible.
-
-#. Note the branch you're proposing changes to. ``master`` is the current focus
- of development. Kolla project has a strict policy of only allowing backports
- in ``stable/branch``, unless when not applicable. A bug in a
- ``stable/branch`` will first have to be fixed in ``master``.
-
-#. Please file a `blueprint of kolla-ansible <https://blueprints.launchpad.net/kolla-ansible>`__
- for any significant code change and a bug for any significant bug fix,
- or add a ``TrivialFix`` tag to commit message for simple changes.
- See how to reference a bug or a blueprint in the `commit message
- <https://wiki.openstack.org/wiki/GitCommitMessages>`_.
-
-#. TrivialFix tags or bugs are not required for documentation changes.
-
-#. We use a `whiteboard <https://etherpad.openstack.org/p/KollaWhiteBoard>`__
- to keep track of CI gate status, release status, stable backports, planning
- and feature development status.
-
-Development Environment
-=======================
-
-Please follow our :doc:`/user/quickstart` to deploy your environment and test
-your changes.
-
-Please use the existing sandbox repository, available at `sandbox
-<https://opendev.org/openstack-dev/sandbox>`_, for learning, understanding
-and testing the `Gerrit Workflow
-<https://docs.openstack.org/infra/manual/developers.html#development-workflow>`_.
-
-Adding a release note
-=====================
-
-Kolla Ansible (just like Kolla) uses the following release notes sections:
-
-- ``features`` --- for new features or functionality; these should ideally
- refer to the blueprint being implemented;
-- ``fixes`` --- for fixes closing bugs; these must refer to the bug being
- closed;
-- ``upgrade`` --- for notes relevant when upgrading from previous version;
- these should ideally be added only between major versions; required when
- the proposed change affects behaviour in a non-backwards compatible way or
- generally changes something impactful;
-- ``deprecations`` --- to track deprecated features; relevant changes may
- consist of only the commit message and the release note;
-- ``prelude`` --- filled in by the PTL before each release or RC.
-
-Other release note types may be applied per common sense.
-Each change should include a release note unless being a ``TrivialFix``
-change or affecting only docs or CI. Such changes should `not` include
-a release note to avoid confusion.
-Remember release notes are mostly for end users which, in case of Kolla,
-are OpenStack administrators/operators.
-In case of doubt, the core team will let you know what is required.
-
-To add a release note, run the following command:
-
-.. code-block:: console
-
- tox -e venv -- reno new <summary-line-with-dashes>
-
-All release notes can be inspected by browsing ``releasenotes/notes``
-directory.
-
-To generate release notes in HTML format in ``releasenotes/build``, run:
-
-.. code-block:: console
-
- tox -e releasenotes
-
-Note this requires the release note to be tracked by ``git`` so you
-have to at least add it to the ``git``'s staging area.
-
-Adding a new service
-====================
-
-Kolla aims to both containerise and deploy all services within the OpenStack
-ecosystem. This is a constantly moving target as the ecosystem grows, so these
-guidelines aim to help make adding a new service to Kolla a smooth experience.
-
-When adding a role for a new service in Ansible, there are couple of patterns
-that Kolla uses throughout that should be followed.
-
-* The sample inventories
-
- Entries should be added for the service in each of
- ``ansible/inventory/multinode`` and ``ansible/inventory/all-in-one``.
-
-* The playbook
-
- The main playbook that ties all roles together is in ``ansible/site.yml``,
- this should be updated with appropriate roles, tags, and conditions. Ensure
- also that supporting hosts such as haproxy are updated when necessary.
-
-* The common role
-
- A ``common`` role exists which sets up logging, ``kolla-toolbox`` and other
- supporting components. This should be included in all services within
- ``meta/main.yml`` of your role.
-
-* Common tasks
-
- All services should include the following tasks:
-
- - ``deploy.yml`` : Used to bootstrap, configure and deploy containers
- for the service.
-
- - ``reconfigure.yml`` : Used to push new configuration files to the host
- and restart the service.
-
- - ``pull.yml`` : Used to pre fetch the image into the Docker image cache
- on hosts, to speed up initial deploys.
-
- - ``upgrade.yml`` : Used for upgrading the service in a rolling fashion. May
- include service specific setup and steps as not all services can be
- upgraded in the same way.
-
-* Logrotation
-
- - For OpenStack services there should be a ``cron-logrotate-PROJECT.conf.j2``
- template file in ``ansible/roles/common/templates`` with the following
- content:
-
- .. path ansible/roles/common/templates/cron-logrotate-PROJECT.conf.j2
- .. code-block:: console
-
- "/var/log/kolla/PROJECT/*.log"
- {
- }
-
- - For OpenStack services there should be an entry in the ``services`` list
- in the ``cron.json.j2`` template file in ``ansible/roles/common/templates``.
-
-* Log delivery
-
- - For OpenStack services the service should add a new ``rewriterule`` in the
- ``match`` element in the ``01-rewrite.conf.j2`` template file in
- ``ansible/roles/common/templates/conf/filter`` to deliver log messages to
- Elasticsearch.
-
-* Documentation
-
- - For OpenStack services there should be an entry in the list
- ``OpenStack services`` in the ``README.rst`` file.
-
- - For infrastructure services there should be an entry in the list
- ``Infrastructure components`` in the ``README.rst`` file.
-
-* Syntax
-
- - All YAML data files should start with three dashes (``---``).
-
-Other than the above, most service roles abide by the following pattern:
-
-- ``Register``: Involves registering the service with Keystone, creating
- endpoints, roles, users, etc.
-
-- ``Config``: Distributes the config files to the nodes to be pulled into
- the container on startup.
-
-- ``Bootstrap``: Creating the database (but not tables), database user for
- the service, permissions, etc.
-
-- ``Bootstrap Service``: Starts a one shot container on the host to create
- the database tables, and other initial run time config.
-
-Ansible handlers are used to create or restart containers when necessary.
diff --git a/doc/source/contributor/adding-a-new-service.rst b/doc/source/contributor/adding-a-new-service.rst
new file mode 100644
index 0000000000..6f6a64a0eb
--- /dev/null
+++ b/doc/source/contributor/adding-a-new-service.rst
@@ -0,0 +1,91 @@
+====================
+Adding a new service
+====================
+
+When adding a role for a new service in Ansible, there are couple of patterns
+which Kolla uses throughout and which should be followed.
+
+* The sample inventories
+
+ Entries should be added for the service in each of
+ ``ansible/inventory/multinode`` and ``ansible/inventory/all-in-one``.
+
+* The playbook
+
+ The main playbook that ties all roles together is in ``ansible/site.yml``,
+ this should be updated with appropriate roles, tags, and conditions. Ensure
+ also that supporting hosts such as haproxy are updated when necessary.
+
+* The common role
+
+ A ``common`` role exists which sets up logging, ``kolla-toolbox`` and other
+ supporting components. This should be included in all services within
+ ``meta/main.yml`` of your role.
+
+* Common tasks
+
+ All services should include the following tasks:
+
+ - ``deploy.yml`` : Used to bootstrap, configure and deploy containers
+ for the service.
+
+ - ``reconfigure.yml`` : Used to push new configuration files to the host
+ and restart the service.
+
+ - ``pull.yml`` : Used to pre fetch the image into the Docker image cache
+ on hosts, to speed up initial deploys.
+
+ - ``upgrade.yml`` : Used for upgrading the service in a rolling fashion. May
+ include service specific setup and steps as not all services can be
+ upgraded in the same way.
+
+* Log rotation
+
+ - For OpenStack services there should be a ``cron-logrotate-PROJECT.conf.j2``
+ template file in ``ansible/roles/common/templates`` with the following
+ content:
+
+ .. path ansible/roles/common/templates/cron-logrotate-PROJECT.conf.j2
+ .. code-block:: console
+
+ "/var/log/kolla/PROJECT/*.log"
+ {
+ }
+
+ - For OpenStack services there should be an entry in the ``services`` list
+ in the ``cron.json.j2`` template file in ``ansible/roles/common/templates``.
+
+* Log delivery
+
+ - For OpenStack services the service should add a new ``rewriterule`` in the
+ ``match`` element in the ``01-rewrite.conf.j2`` template file in
+ ``ansible/roles/common/templates/conf/filter`` to deliver log messages to
+ Elasticsearch.
+
+* Documentation
+
+ - For OpenStack services there should be an entry in the list
+ ``OpenStack services`` in the ``README.rst`` file.
+
+ - For infrastructure services there should be an entry in the list
+ ``Infrastructure components`` in the ``README.rst`` file.
+
+* Syntax
+
+ - All YAML data files should start with three dashes (``---``).
+
+Other than the above, most service roles abide by the following pattern:
+
+- ``Register``: Involves registering the service with Keystone, creating
+ endpoints, roles, users, etc.
+
+- ``Config``: Distributes the config files to the nodes to be pulled into
+ the container on startup.
+
+- ``Bootstrap``: Creating the database (but not tables), database user for
+ the service, permissions, etc.
+
+- ``Bootstrap Service``: Starts a one shot container on the host to create
+ the database tables, and other initial run time config.
+
+Ansible handlers are used to create or restart containers when necessary.
diff --git a/doc/source/contributor/contributing.rst b/doc/source/contributor/contributing.rst
new file mode 100644
index 0000000000..c4ede81de0
--- /dev/null
+++ b/doc/source/contributor/contributing.rst
@@ -0,0 +1,130 @@
+============================
+So You Want to Contribute...
+============================
+
+For general information on contributing to OpenStack, please check out the
+`contributor guide <https://docs.openstack.org/contributors/>`_ to get started.
+It covers all the basics that are common to all OpenStack projects: the
+accounts you need, the basics of interacting with our Gerrit review system,
+how we communicate as a community, etc.
+
+Below will cover the more project specific information you need to get started
+with Kolla Ansible.
+
+Basics
+~~~~~~
+
+The source repository for this project can be found at:
+
+ https://opendev.org/openstack/kolla-ansible
+
+Communication
+~~~~~~~~~~~~~
+
+Kolla Ansible shares communication channels with Kolla.
+
+IRC Channel
+ ``#openstack-kolla`` (`channel logs`_) on Freenode
+
+Weekly Meetings
+ On Wednesdays at 15:00 UTC in the IRC channel (`meetings logs`_)
+
+Mailing list (prefix subjects with ``[kolla]``)
+ http://lists.openstack.org/pipermail/openstack-discuss/
+
+Meeting Agenda
+ https://wiki.openstack.org/wiki/Meetings/Kolla
+
+Whiteboard (etherpad)
+ Keeping track of CI gate status, release status, stable backports,
+ planning and feature development status.
+ https://etherpad.openstack.org/p/KollaWhiteBoard
+
+.. _channel logs: http://eavesdrop.openstack.org/irclogs/%23openstack-kolla/
+.. _meetings logs: http://eavesdrop.openstack.org/meetings/kolla/
+
+Contacting the Core Team
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The list in alphabetical order (on first name):
+
++-----------------------+---------------+------------------------------------+
+| Name | IRC nick | Email address |
++=======================+===============+====================================+
+| `Chason Chan`_ | chason | chason.chan@foxmail.com |
++-----------------------+---------------+------------------------------------+
+| `Christian Berendt`_ | berendt | berendt@betacloud-solutions.de |
++-----------------------+---------------+------------------------------------+
+| `Dincer Celik`_ | osmanlicilegi | hello@dincercelik.com |
++-----------------------+---------------+------------------------------------+
+| `Eduardo Gonzalez`_ | egonzalez | dabarren@gmail.com |
++-----------------------+---------------+------------------------------------+
+| `Jeffrey Zhang`_ | Jeffrey4l | jeffrey.zhang@99cloud.net |
++-----------------------+---------------+------------------------------------+
+| `Marcin Juszkiewicz`_ | hrw | marcin.juszkiewicz@linaro.org |
++-----------------------+---------------+------------------------------------+
+| `Mark Goddard`_ | mgoddard | mark@stackhpc.com |
++-----------------------+---------------+------------------------------------+
+| `Michał Nasiadka`_ | mnasiadka | mnasiadka@gmail.com |
++-----------------------+---------------+------------------------------------+
+| `Radosław Piliszek`_ | yoctozepto | radoslaw.piliszek@gmail.com |
++-----------------------+---------------+------------------------------------+
+| `Surya Prakash`_ | spsurya | singh.surya64mnnit@gmail.com |
++-----------------------+---------------+------------------------------------+
+| `Cao Yuan`_ | caoyuan | cao.yuan@99cloud.net |
++-----------------------+---------------+------------------------------------+
+
+.. _Chason Chan: https://launchpad.net/~chen-xing
+.. _Christian Berendt: https://launchpad.net/~berendt
+.. _Dincer Celik: https://launchpad.net/~osmanlicilegi
+.. _Eduardo Gonzalez: https://launchpad.net/~egonzalez90
+.. _Jeffrey Zhang: https://launchpad.net/~jeffrey4l
+.. _Marcin Juszkiewicz: https://launchpad.net/~hrw
+.. _Mark Goddard: https://launchpad.net/~mgoddard
+.. _Michał Nasiadka: https://launchpad.net/~mnasiadka
+.. _Radosław Piliszek: https://launchpad.net/~yoctozepto
+.. _Surya Prakash: https://launchpad.net/~confisurya
+.. _Cao Yuan: https://launchpad.net/~caoi-yuan
+
+The current effective list is also available from Gerrit:
+https://review.opendev.org/#/admin/groups/1637,members
+
+New Feature Planning
+~~~~~~~~~~~~~~~~~~~~
+
+New features are discussed via IRC or mailing list (with [kolla] prefix).
+Kolla project keeps blueprints in `Launchpad <https://blueprints.launchpad.net/kolla-ansible>`__.
+Specs are welcome but not strictly required.
+
+Task Tracking
+~~~~~~~~~~~~~
+
+Kolla project tracks tasks in `Launchpad <https://bugs.launchpad.net/kolla-ansible>`__.
+Note this is the same place as for bugs.
+
+If you're looking for some smaller, easier work item to pick up and get started
+on, search for the 'low-hanging-fruit' tag.
+
+A more lightweight task tracking is done via etherpad - `Whiteboard <https://etherpad.openstack.org/p/KollaWhiteBoard>`__.
+
+Reporting a Bug
+~~~~~~~~~~~~~~~
+
+You found an issue and want to make sure we are aware of it? You can do so
+on `Launchpad <https://bugs.launchpad.net/kolla-ansible>`__.
+Note this is the same place as for tasks.
+
+Getting Your Patch Merged
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Most changes proposed to Kolla Ansible require two +2 votes from core reviewers
+before +W. A release note is required on most changes as well. Release notes
+policy is described in :ref:`its own section <release-notes>`.
+
+Significant changes should have documentation and testing provided with them.
+
+Project Team Lead Duties
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+All common PTL duties are enumerated in the `PTL guide <https://docs.openstack.org/project-team-guide/ptl.html>`_.
+Kolla-Ansible-specific PTL duties are listed in `Kolla Ansible PTL guide <https://docs.openstack.org/kolla-ansible/latest/contributor/ptl-guide.html>`_.
diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst
index c0cfdb8a58..9681dc966a 100644
--- a/doc/source/contributor/index.rst
+++ b/doc/source/contributor/index.rst
@@ -12,7 +12,9 @@ We welcome everyone to join our project!
.. toctree::
:maxdepth: 1
- CONTRIBUTING
+ contributing
+ adding-a-new-service
+ release-notes
vagrant-dev-env
running-tests
kolla-for-openstack-development
diff --git a/doc/source/contributor/release-notes.rst b/doc/source/contributor/release-notes.rst
new file mode 100644
index 0000000000..739d3a0b56
--- /dev/null
+++ b/doc/source/contributor/release-notes.rst
@@ -0,0 +1,45 @@
+.. _release-notes:
+
+=============
+Release notes
+=============
+
+Kolla Ansible (just like Kolla) uses the following release notes sections:
+
+- ``features`` --- for new features or functionality; these should ideally
+ refer to the blueprint being implemented;
+- ``fixes`` --- for fixes closing bugs; these must refer to the bug being
+ closed;
+- ``upgrade`` --- for notes relevant when upgrading from previous version;
+ these should ideally be added only between major versions; required when
+ the proposed change affects behaviour in a non-backwards compatible way or
+ generally changes something impactful;
+- ``deprecations`` --- to track deprecated features; relevant changes may
+ consist of only the commit message and the release note;
+- ``prelude`` --- filled in by the PTL before each release or RC.
+
+Other release note types may be applied per common sense.
+Each change should include a release note unless being a ``TrivialFix``
+change or affecting only docs or CI. Such changes should `not` include
+a release note to avoid confusion.
+Remember release notes are mostly for end users which, in case of Kolla,
+are OpenStack administrators/operators.
+In case of doubt, the core team will let you know what is required.
+
+To add a release note, run the following command:
+
+.. code-block:: console
+
+ tox -e venv -- reno new <summary-line-with-dashes>
+
+All release notes can be inspected by browsing ``releasenotes/notes``
+directory.
+
+To generate release notes in HTML format in ``releasenotes/build``, run:
+
+.. code-block:: console
+
+ tox -e releasenotes
+
+Note this requires the release note to be tracked by ``git`` so you
+have to at least add it to the ``git``'s staging area.