x/mogan
Code Issues Proposed changes

Reorganize Mogan docs

Browse Source 
Change-Id: I7d9986a231e33e65bf364ae1f028c9b58bb075a1
This commit is contained in:
Zhenguo Niu 2017-02-13 17:41:28 +08:00
parent c4fa5931b5
commit 068ba7e5cc
4 changed files with 341 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

187
doc/source/cmds/mogan-dbsync.rst Normal file
View File

@ -0,0 +1,187 @@
============
mogan-dbsync
============
The :command:`mogan-dbsync` utility is used to create the database schema
tables that the mogan services will use for storage. It can also be used to
upgrade existing database tables when migrating between
different versions of mogan.
The `Alembic library <http://alembic.readthedocs.org>`_ is used to perform
the database migrations.
Options
=======
This is a partial list of the most useful options. To see the full list,
run the following::
mogan-dbsync --help
.. program:: mogan-dbsync
.. option:: -h, --help
Show help message and exit.
.. option:: --config-dir <DIR>
Path to a config directory with configuration files.
.. option:: --config-file <PATH>
Path to a configuration file to use.
.. option:: -d, --debug
Print debugging output.
.. option:: --version
Show the program's version number and exit.
.. option:: upgrade, stamp, revision, version, create_schema
The :ref:`command <dbsync_cmds>` to run.
Usage
=====
Options for the various :ref:`commands <dbsync_cmds>` for
:command:`mogan-dbsync` are listed when the :option:`-h` or :option:`--help`
option is used after the command.
For example::
mogan-dbsync create_schema --help
Information about the database is read from the mogan configuration file
used by the API server and conductor services. This file must be specified
with the :option:`--config-file` option::
mogan-dbsync --config-file /path/to/mogan.conf create_schema
The configuration file defines the database backend to use with the
*connection* database option::
[database]
connection=mysql+pymysql://root@localhost/mogan
If no configuration file is specified with the :option:`--config-file` option,
:command:`mogan-dbsync` assumes an SQLite database.
.. _dbsync_cmds:
Command Options
===============
:command:`mogan-dbsync` is given a command that tells the utility what actions
to perform. These commands can take arguments. Several commands are available:
.. _create_schema:
create_schema
-------------
.. program:: create_schema
.. option:: -h, --help
Show help for create_schema and exit.
This command will create database tables based on the most current version.
It assumes that there are no existing tables.
An example of creating database tables with the most recent version::
mogan-dbsync --config-file=/etc/mogan/mogan.conf create_schema
revision
--------
.. program:: revision
.. option:: -h, --help
Show help for revision and exit.
.. option:: -m <MESSAGE>, --message <MESSAGE>
The message to use with the revision file.
.. option:: --autogenerate
Compares table metadata in the application with the status of the database
and generates migrations based on this comparison.
This command will create a new revision file. You can use the
:option:`--message` option to comment the revision.
This is really only useful for mogan developers making changes that require
database changes. This revision file is used during database migration and
will specify the changes that need to be made to the database tables. Further
discussion is beyond the scope of this document.
stamp
-----
.. program:: stamp
.. option:: -h, --help
Show help for stamp and exit.
.. option:: --revision <REVISION>
The revision number.
This command will 'stamp' the revision table with the version specified with
the :option:`--revision` option. It will not run any migrations.
upgrade
-------
.. program:: upgrade
.. option:: -h, --help
Show help for upgrade and exit.
.. option:: --revision <REVISION>
The revision number to upgrade to.
This command will upgrade existing database tables to the most recent version,
or to the version specified with the :option:`--revision` option.
If there are no existing tables, then new tables are created, beginning
with the oldest known version, and successively upgraded using all of the
database migration files, until they are at the specified version. Note
that this behavior is different from the :ref:`create_schema` command
that creates the tables based on the most recent version.
An example of upgrading to the most recent table versions::
mogan-dbsync --config-file=/etc/mogan/mogan.conf upgrade
.. note::
This command is the default if no command is given to
:command:`mogan-dbsync`.
.. warning::
The upgrade command is not compatible with SQLite databases since it uses
ALTER TABLE commands to upgrade the database tables. SQLite supports only
a limited subset of ALTER TABLE.
version
-------
.. program:: version
.. option:: -h, --help
Show help for version and exit.
This command will output the current database version.

4
doc/source/contributing.rst
View File

@ -1,4 +0,0 @@
============
Contributing
============
.. include:: ../../CONTRIBUTING.rst

99
doc/source/dev/code-contribution-guide.rst Normal file
View File

@ -0,0 +1,99 @@
.. _code-contribution-guide:
=======================
Code Contribution Guide
=======================
This document provides some necessary points for developers to consider when
writing and reviewing Mogan code. The checklist will help developers get
things right.
Getting Started
===============
If you're completely new to OpenStack and want to contribute to the mogan
project, please start by familiarizing yourself with the `Infra Team's Developer
Guide <http://docs.openstack.org/infra/manual/developers.html>`_. This will help
you get your accounts set up in Launchpad and Gerrit, familiarize you with the
workflow for the OpenStack continuous integration and testing systems, and help
you with your first commit.
LaunchPad Project
-----------------
Most of the tools used for OpenStack require a launchpad.net ID for
authentication.
.. seealso::
* https://launchpad.net
* https://launchpad.net/mogan
Related Projects
----------------
There are several projects that are tightly integrated with mogan and which are
developed by the same community.
.. seealso::
* https://launchpad.net/python-moganclient
Project Hosting Details
-----------------------
Bug tracker
http://launchpad.net/mogan
Mailing list (prefix Subject line with ``[mogan]``)
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Wiki
http://wiki.openstack.org/Mogan
Code Hosting
https://git.openstack.org/cgit/openstack/mogan
Code Review
https://review.openstack.org/#/q/status:open+project:openstack/mogan,n,z
Mogan API RPC Versions
----------------------
* When the signature(arguments) of an RPC method is changed, the following things
need to be considered:
- The RPC version must be incremented and be the same value for both the client
(engine/rpcapi.py, used by mogan-api) and the server (engine/manager.py,
used by mogan-engine).
- New arguments of the method can only be added as optional. Existing arguments cannot be
removed or changed in incompatible ways (with the method in older RPC versions).
- Client-side can pin a version cap by passing ``version_cap`` to the constructor
of oslo_messaging.RPCClient. Methods which change arguments should run
client.can_send_version() to see if the version of the request is compatible with the
version cap of RPC Client, otherwise the request needs to be created to work with a
previous version that is supported.
- Server-side should tolerate the older version of requests in order to keep
working during the progress of live upgrade. The behavior of server-side should
depend on the input parameters passed from the client-side.
Object Versions
---------------
* When Object classes (subclasses of mogan.objects.base.MoganObject) are modified, the
following things need to be considered:
- The change of fields and the signature of remotable method needs a bump of object
version.
- The arguments of methods can only be added as optional, they cannot be
removed or changed in an incompatible way.
- Fields types cannot be changed. If it is a must, create a new field and
deprecate the old one.
- When new version objects communicate with old version objects,
obj_make_compatible() will be called to convert objects to the target version during
serialization. So objects should implement their own obj_make_compatible() to
remove/alter attributes which was added/changed after the target version.
- There is a test (object/test_objects.py) to generate the hash of object fields and the
signatures of remotable methods, which helps developers to check if the change of
objects need a version bump. The object fingerprint should only be updated with a
version bump.

66
doc/source/index.rst
View File

@ -1,18 +1,63 @@
.. mogan documentation master file, created by
sphinx-quickstart on Tue Jul 9 22:26:36 2013.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
===========================================
Welcome to Mogan's developer documentation!
===========================================
Welcome to mogan's documentation!
========================================================
Introduction
============
Contents:
Mogan is an OpenStack project dedicated for bare metal computing management,
which is designed specifically for bare metals, so compared with Nova, we can
provide a more lightweight and convenient platform with more advanced features
by leveraging Ironic. Besides this, we also plan to support RSD, then we can
not only provide Pre-set Configuration Servers, but also Custom Servers.
Site Notes
----------
This site is primarily intended to provide documentation for developers
interested in contributing to or working with mogan. It *also* contains
references and guides for administrators which are not yet hosted elsewhere on
the OpenStack documentation sites.
Developer's Guide
=================
Getting Started
---------------
If you are new to mogan, this section contains information that should help
you get started as a developer working on the project or contributing to the
project.
.. toctree::
:maxdepth: 2
:maxdepth: 1
contributing
dev/dev-quickstart
Developer Contribution Guide <dev/code-contribution-guide>
Setting Up Your Development Environment <dev/dev-quickstart>
Administrator's Guide
=====================
Configuration
-------------
There are many aspects of the Bare Metal Compute service which are environment
specific. The following pages will be helpful in configuring specific aspects
of mogan that may or may not be suitable to every situation.
You can use `tox -egenconfig` to generate the sample config file.
Command References
==================
Here are references for commands not elsewhere documented.
.. toctree::
:maxdepth: 1
cmds/mogan-dbsync
Indices and tables
==================
@ -20,4 +65,3 @@ Indices and tables
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`