tuskar/CONTRIBUTING.rst

======================
Contributing to Tuskar
======================

Pretty soon, Tuskar will move to Stackforge, using Gerrit for reviews
and Launchpad for bugs and blueprints. We're just getting started at
this point so, in the interim, we accept pull requests via Github.

Coding Standards
----------------

We attempt to comply with the openstack coding standards, defined in
https://github.com/openstack-dev/hacking/blob/master/HACKING.rst

Before pushing your code, make sure it complies with the standards by
running::

  $ tox -e pep8

Also, before submitting your code, please make sure you have completed
the following checklist:

1. Update tools/sample\_data.py (if needed)
2. Update the API docs (if needed)
3. Update the tests (if needed)
4. Update
   `cURL commands <https://github.com/tuskar/tuskar/blob/master/docs/api/curl.md>`_
   page (if needed)

Getting Started
---------------

Setting up the Tuskar development environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This assumes you have done all the basic setup as described in
`INSTALL.rst <https://github.com/tuskar/tuskar/blob/master/INSTALL.rst>`_.
Run the following::

    # creates symlinks for installed code.  Used for dev environment.
    $ python setup.py develop
    $ cp etc/tuskar/tuskar.conf.sample etc/tuskar/tuskar.conf

The config file changes are::

    $ openstack-config --set etc/tuskar/tuskar.conf database connection sqlite:///tuskar.sqlite
    $ openstack-config --set etc/tuskar/tuskar.conf DEFAULT debug true
    $ openstack-config --set etc/tuskar/tuskar.conf heat stack_name overcloud
    $ openstack-config --set etc/tuskar/tuskar.conf heat service_type orchestration
    $ openstack-config --set etc/tuskar/tuskar.conf heat_keystone username heat
    $ openstack-config --set etc/tuskar/tuskar.conf heat_keystone password heat
    $ openstack-config --set etc/tuskar/tuskar.conf heat_keystone tenant_name admin
    $ openstack-config --set etc/tuskar/tuskar.conf heat_keystone auth_url http://10.34.32.181:35357/v2.0
    $ openstack-config --set etc/tuskar/tuskar.conf heat_keystone insecure True

The command above is part of the openstack-utils package, so you will
have to install that if you have not already.

Then::

    # if you delete tuskar.sqlite this will force creation of tables again - e.g.
    # if you added a new resource table definitions etc in an existing migration
    # file
    $ tuskar-dbsync --config-file etc/tuskar/tuskar.conf

You can verify this was successful (in addition to seeing no error
output) with::

    $ sqlite3 tuskar.sqlite .schema

Then, launch the app and try curl to see if it works::

    $ tuskar-api --config-file etc/tuskar/tuskar.conf
    $ curl -v -X GET -H 'Accept: application/json' http://0.0.0.0:6385/ | python -mjson.tool

Assuming this is your first time running with a new database, you should
simply get '[]' back from curl above. Currently the api supports only
json return type, so we request that in the example call.

Next, you can run a script to populate the DB with some sample data::

    $ python tools/sample_data.py

Finding your way around
~~~~~~~~~~~~~~~~~~~~~~~

There are various pieces of the codebase that may not be immediately
obvious to a newcomer to the project, so we attempt to explain some of
that in this section.

* Where do the tuskar commands come from? (tuskar-api, tuskar-dbsync, etc)

  The project-specific commands live in tuskar/cmd, and are
  implementations that use the oslo.config project as a base. They are
  generated and put into your venv when you run 'python setup.py
  develop'.  Adding a new one consists of:

  1. Creating a new file in tuskar/cmd
  2. Adding the appropriate name and package reference to the
     entry\_points section of setup.cfg

* How do I add a new controller?

  Controllers are contained in tuskar/api/controllers/v1.py. To add a
  new controller, you need to add an 'HTTP Representation' of whatever
  model you wish to expose with this controller. This is a simple
  python object that extends Base, and describes the key and value
  types that the object will return. For example, say there is a Foo
  model object you wish to return::

      class Foo(Base):
          id = int
          name = wtypes.text
          fred = Fred       # Fred is another object defined in this file

  Then add a controller for it (anywhere above the Controller class,
  which is the last in the file. For example::

      class FoosController(rest.RestController):
          @wsme_pecan.wsexpose([Foo])
          def get_all(self)
              result = []
              """Do some things to get your list of Foos"""
              return result

  Lastly, add a reference to the controller in the Controller class at
  the bottom of the file as so::

      class Controller(object):
          foos = FoosController()

  The name you give the controller above will be how it is accessed by
  the client, so in the above case, you could get the list of foos
  with::

      curl http://0.0.0.0:6385/v1/foos

  For doing something simple, like a poc controller that doesn't
  return any objects, you can return plain text as so::

      class FarkleController(rest.RestController):
          @wsme_pecan.wsexpose(None, wtypes.text)
          def get_all(self):
              return "Hi, I am farkle!"

* Where are my changes to the app?

  There are two possible answers:

  1. You may make a change to, say, a controller, and wonder why your
     change does not seem to happen when you call your curl command on
     that resource. This is because, at least at the current time, you
     must -c to kill the tuskar-api server, and then start it again to
     pick up your changes.
  2. You may have changed something that requires you to rerun 'python
     setup.py develop', such as changing or adding a new command in
     the cmd dir described above

* How do I create a new model?

  Models live in tuskar/db/sqlalchemy/. There are two files here of
  relevance for describing the model (we will get to defining the
  table in the next section), api.py and models.py. The models.py file
  contains the definition of the columns to expose to the client for
  the model objects, as well as a mapping of the object in this file
  to the tablename define in the migration (below). In api.py, we have
  utility methods, as well as validation rules and other custom
  methods for interacting with the models.

* How do I define the table for my new model?

  This is described in a migration file, located in
  tuskar/db/sqlalchemy/migrate\_repo/versions/. Each new table or
  change to an existing table should get a new file here with a
  descriptive name, starting with a 3 digit number. Each new file
  should increment the number to avoid collisions. The primary part of
  this file is the definition of your table, which s done via a Table
  object, and you describe the columns, using, surprisingly enough, a
  Column object. There are upgrade nd downgrade methods in these
  migrations to describe what to do for creating a given set of
  tables, as well as dropping them, or rolling back to what was done
  before the upgrade.

Writing tests
~~~~~~~~~~~~~

We use testtools for our unit tests, and mox for mock objects.

Additional details forthcoming.