x/tuskar
Code Issues Proposed changes

Update Tuskar Contribution Guidelines

Browse Source 
Change-Id: I82f7a46095db6669ed0f32bc1101de560e53b06a
This commit is contained in:
Dougal Matthews 2014-10-02 14:07:56 +01:00
parent bd1fb8ec1e
commit 3f72cb5ffb
1 changed files with 103 additions and 98 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

201
doc/source/contributing.rst
View File

@ -2,19 +2,24 @@
Contributing to Tuskar Contributing to Tuskar
====================== ======================
Tuskar follows the OpenStack processes when it comes to code, communication, Tuskar follows the OpenStack development processes for code and
etc. The `repositories are hosted on git.openstack.org communication. The `repository is hosted on git.openstack.org
<http://git.openstack.org/cgit/openstack/tuskar>`_, <http://git.openstack.org/cgit/openstack/tuskar>`_, `bugs and
`bugs and blueprints are on Launchpad blueprints are on Launchpad <https://launchpad.net/tuskar>`_ and
<https://launchpad.net/tuskar>`_ and we use the openstack-dev mailing list we use the openstack-dev mailing list (subject `[tuskar]`) and
(subject `[tuskar]`) and the `#tuskar` IRC channel for communication. the `#tripleo` IRC channel for communication.
As Tuskar is under the TripleO umbrella of projects you will also
want to look at the `TripleO contributing guidelines
<http://docs.openstack.org/developer/tripleo-
incubator/CONTRIBUTING.html>`_.
Coding Standards Coding Standards
---------------- ----------------
We attempt to comply with the OpenStack coding standards, defined in We comply with the `OpenStack coding standards
http://docs.openstack.org/developer/hacking/ <http://docs.openstack.org/developer/hacking/>`_.
Be sure to familiarise yourself with `OpenStack's Gerrit Workflow Be sure to familiarise yourself with `OpenStack's Gerrit Workflow
<https://wiki.openstack.org/wiki/Gerrit_Workflow>`_. <https://wiki.openstack.org/wiki/Gerrit_Workflow>`_.
@ -22,131 +27,131 @@ Be sure to familiarise yourself with `OpenStack's Gerrit Workflow
Before submitting your code, please make sure you have completed Before submitting your code, please make sure you have completed
the following checklist: the following checklist:
1. Update tools/sample\_data.py (if needed) #. Update the API docs (if needed)
2. Update the API docs (if needed) #. Update the tests (if needed)
3. Update the tests (if needed)
4. Update
`cURL commands <docs/api/curl.rst>`_
page (if needed)
Finding your way around Finding your way around
~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~
There are various pieces of the codebase that may not be immediately There are various pieces of the codebase that may not be
obvious to a newcomer to the project, so we attempt to explain some of immediately obvious to a newcomer to the project, so we attempt
that in this section. to explain some of that in this section.
* Where do the tuskar commands come from? (tuskar-api, tuskar-dbsync, etc) Where do the tuskar commands come from? (tuskar-api, tuskar-dbsync, etc)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The project-specific commands live in tuskar/cmd, and are The project-specific commands live in tuskar/cmd, and are
implementations that use the oslo.config project as a base. They are implementations that use the oslo.config project as a base. They
generated and put into your venv when you run 'python setup.py are generated and put into your venv when you run 'python
develop'. Adding a new one consists of: setup.py develop'. Adding a new one consists of:
1. Creating a new file in tuskar/cmd #. Creating a new file in tuskar/cmd
2. Adding the appropriate name and package reference to the #. Adding the appropriate name and package reference to the
entry\_points section of setup.cfg entry\_points section of setup.cfg
* How do I add a new controller? How do I add a new controller?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Controllers are contained in tuskar/api/controllers/v1.py. To add a Controllers are contained in tuskar/api/controllers/v2.py. To add
new controller, you need to add an 'HTTP Representation' of whatever a new controller, you need to add an 'HTTP Representation' of
model you wish to expose with this controller. This is a simple whatever model you wish to expose with this controller. This is a
python object that extends Base, and describes the key and value simple python object that extends Base, and describes the key and
types that the object will return. For example, say there is a Foo value types that the object will return. For example, say there
model object you wish to return:: is a Foo model object you wish to return.
class Foo(Base): .. code-block:: python
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, class Foo(Base):
which is the last in the file. For example:: id = int
name = wtypes.text
fred = Fred # Fred is another object defined in this file
class FoosController(rest.RestController): Then add a controller for it (anywhere above the Controller class,
@wsme_pecan.wsexpose([Foo]) which is the last in the file. For example:
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 .. code-block:: python
the bottom of the file as so::
class Controller(object): class FoosController(rest.RestController):
foos = FoosController() @wsme_pecan.wsexpose([Foo])
def get_all(self)
result = []
"""Do some things to get your list of Foos"""
return result
The name you give the controller above will be how it is accessed by Lastly, add a reference to the controller in the Controller class at
the client, so in the above case, you could get the list of foos the bottom of the file as so.
with::
curl http://0.0.0.0:8585/v1/foos .. code-block:: python
For doing something simple, like a poc controller that doesn't class Controller(object):
return any objects, you can return plain text as so:: foos = FoosController()
class FarkleController(rest.RestController): The name you give the controller above will be how it is accessed by
@wsme_pecan.wsexpose(None, wtypes.text) the client, so in the above case, you could get the list of foos
def get_all(self): with.
return "Hi, I am farkle!"
* Where are my changes to the app? .. code-block:: bash
There are two possible answers: curl http://0.0.0.0:8585/v1/foos
1. You may make a change to, say, a controller, and wonder why your For doing something simple, like a poc controller that doesn't
change does not seem to happen when you call your curl command on return any objects, you can return plain text as so
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? .. code-block:: python
Models live in tuskar/db/sqlalchemy/. There are two files here of class FarkleController(rest.RestController):
relevance for describing the model (we will get to defining the @wsme_pecan.wsexpose(None, wtypes.text)
table in the next section), api.py and models.py. The models.py file def get_all(self):
contains the definition of the columns to expose to the client for return "Hi, I am farkle!"
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? Where are my changes to the app?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This is described in a migration file, located in You may make a change to, say, a controller, and wonder why your
tuskar/db/sqlalchemy/migrate\_repo/versions/. Each new table or change does not seem to happen when you call your curl command on
change to an existing table should get a new file here with a that resource. This is because, at least at the current time, you
descriptive name, starting with a 3 digit number. Each new file must ctrl+c to kill the tuskar-api server, and then restart it
should increment the number to avoid collisions. The primary part of again to pick up your changes.
this file is the definition of your table, which s done via a Table
object, and you describe the columns, using, surprisingly enough, a How do I create a new model?
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 Models live in tuskar/db/sqlalchemy/. There are two files here of
before the upgrade. 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 and Running tests Writing and Running tests
~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~
We use testtools for our unit tests, and mox for mock objects. We use testtools for our unit tests, and mox for mock objects.
You can run tests using Tox: :: You can run tests using Tox:
.. code-block:: bash
$ tox $ tox
This will run tests under Python 2.6, 2.7 and verify `PEP 8 This will run tests under Python 2.6, 2.7 and verify `PEP 8
<http://www.python.org/dev/peps/pep-0008/>`_ compliance. The identical test <http://www.python.org/dev/peps/pep-0008/>`_ compliance. The identical test
suite is run by OpenStack's Jenkins whenever you send a patch. suite is run by OpenStack's Jenkins whenever you send a patch.
PEP8 check runs ::
$ ./tools/requirements_style_check.sh requirements.txt test-requirements.txt
as last check. This can fail on Fedora 20 due to `sort bug <https://bugzilla.redhat.com/show_bug.cgi?id=1055597>`_.
Additional details forthcoming.