diff --git a/doc/source/cmds/mogan-dbsync.rst b/doc/source/cmds/mogan-dbsync.rst new file mode 100644 index 00000000..0967a318 --- /dev/null +++ b/doc/source/cmds/mogan-dbsync.rst @@ -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 `_ 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 + + Path to a config directory with configuration files. + +.. option:: --config-file + + 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 ` to run. + +Usage +===== + +Options for the various :ref:`commands ` 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 + + 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 + + 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 + + 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. diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst deleted file mode 100644 index 1728a61c..00000000 --- a/doc/source/contributing.rst +++ /dev/null @@ -1,4 +0,0 @@ -============ -Contributing -============ -.. include:: ../../CONTRIBUTING.rst diff --git a/doc/source/dev/code-contribution-guide.rst b/doc/source/dev/code-contribution-guide.rst new file mode 100644 index 00000000..c77f9f04 --- /dev/null +++ b/doc/source/dev/code-contribution-guide.rst @@ -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 `_. 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. diff --git a/doc/source/index.rst b/doc/source/index.rst index f63e07e7..953a924a 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -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 + Setting Up Your Development Environment + + +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` -