a8660a7e53
This patch set reorganizes Deckhand's documentation structure for better organization into 3 distinct categories: * developer's guide * operator's guide * user's guide This means that the RTD navigation menu on the left-hand side will have fewer links (see list above) making navigation much easier. This is similar to how Armada organizes its documentation too. This patch set also updates README section with a better overview and trims some fat from it (remove testing documentation as it doesn't really belong there -- there is a dedicated page for that already). Finally, this patch set changes the exceptions page to render as a basic list of autoexception classes because the current tabularized view is not rendering correctly on RTD [0]. [0] https://airship-deckhand.readthedocs.io/en/latest/exceptions.html Change-Id: I162383bf8e3bbd5004603c979ac7b0d760a210c4
69 lines
2.7 KiB
ReStructuredText
69 lines
2.7 KiB
ReStructuredText
..
|
|
Copyright 2017 AT&T Intellectual Property.
|
|
All Rights Reserved.
|
|
|
|
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
|
not use this file except in compliance with the License. You may obtain
|
|
a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
|
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
|
License for the specific language governing permissions and limitations
|
|
under the License.
|
|
|
|
.. _revision-history:
|
|
|
|
Revision History
|
|
================
|
|
|
|
Revision History
|
|
----------------
|
|
|
|
Documents will be ingested in batches which will be given a revision index.
|
|
This provides a common language for describing complex validations on sets of
|
|
documents.
|
|
|
|
Revisions can be thought of as commits in a linear git history, thus looking
|
|
at a revision includes all content from previous revisions.
|
|
|
|
.. _revision-diffing:
|
|
|
|
Revision Diffing
|
|
----------------
|
|
|
|
By maintaining a linear history of all the documents in each revision, Deckhand
|
|
is able to diff different revisions together to report what has changed
|
|
across revisions, allowing external services to determine whether the Deckhand
|
|
configuration undergone any changes since the service last queried the Deckhand
|
|
API.
|
|
|
|
The revision difference is calculated by comparing the `overall` difference
|
|
across all the documents in the buckets associated with the two revisions that
|
|
are diffed. For example, if a bucket shared between two revisions contains two
|
|
documents, and between the first revision and the second revision, if only
|
|
one of those two documents has been modified, the bucket itself is tagged
|
|
as ``modified``. For more information about revision diffing, please reference
|
|
the :ref:`api-ref`.
|
|
|
|
Revision DeepDiffing
|
|
--------------------
|
|
|
|
Revision DeepDiffing is an extended version of existing revision diff api.
|
|
When any bucket state gets changed to ``modified``, It shows deep difference
|
|
between revisions. DeepDiffing resultset will consist of ``document_added``,
|
|
``document_deleted`` and ``document_changed`` count and details.
|
|
For more information about revision deepdiffing, please reference the :ref:`api-ref`.
|
|
|
|
Revision Rollback
|
|
-----------------
|
|
|
|
As all the changes to documents are maintained via revisions, it is possible to
|
|
rollback the latest revision in Deckhand to a prior revision. This behavior can
|
|
be loosely compared to a ``git rebase`` in which it is possible to squash the
|
|
latest revision in order to go back to the previous revision. This behavior is
|
|
useful for undoing accidental changes and returning to a stable internal
|
|
configuration.
|