===================================
OpenStack Architecture Design Guide
===================================

This repository contains the source files for the OpenStack Architecture Guide.

You can read this guide at `docs.openstack.org/arch-design
<https://docs.openstack.org/arch-design>`_.

Prerequisites
-------------

At a minimum, you will need git and the git-review tool installed in order to
contribute documentation. You will also need a `Gerrit account
<https://docs.openstack.org/infra/manual/developers.html#account-setup>`_ to
submit the change.

Git is available for Linux, Mac, and Windows environements. Some platforms come
with it preinstalled, but you can review the `installation instructions
<https://git-scm.com/book/en/v2/Getting-Started-Installing-Git>`_ if you
do not have it by default.

Once git is installed, you can follow the instructions for your platform to
`install git-review <https://www.mediawiki.org/wiki/Gerrit/git-review>`_.

The last step is to configure git with your name and email address used for
your Gerrit account set up so it can link you patch to your user. Run the
following to set these values:

.. code-block:: console

  git config --global user.name "First Last"
  git config --global user.email "your_email@youremail.com"


Submitting Updates
------------------
Proposing updates to the documentation is fairly straight forward once you've
done it, but there are a few steps that can appear intimidating your first
couple times through. Here is a suggested workflow to help you along the way.

.. code-block:: console

  git clone https://git.openstack.org/openstack/arch-design
  cd arch-design
  
  # it is useful to make changes on a separate branch in case you need to make
  # other changes
  git checkout -b my-topic

  # edit your files
  git add .
  git commit # Add a descriptive commit message

  # submit your changes for review
  git review

The changes will then be run through a few tests to make sure the docs build
and it will be ready for reviews. Once reviewed, if no problems are found with
the changes they will be merged to the repo and the changes will be published
to the docs.openstack.org site.

Local Testing
-------------
If you would like to build the docs locally to make sure there are no issues
with the changes, and to view locally generated HTML files, you will need to do
a couple extra steps.

The jobs are run using a tool called `tox`. You will need to install tox on
your platform first following its `installation guide
<https://tox.readthedocs.io/en/latest/install.html>`_.

You can then run the following to perform a local build with some tests:

.. code-block:: console

  tox -e docs

If you have any questions, please reach out on the #openstack-operators IRC
channel or through the openstack-discuss mailing list.