Update documentation
The goal of this patch is to setup infrastructure and organization of docs in the project. Changes: * Modified README to be similar to other OS projects * Added project description to the index page * Added install and run guide Note(1): These docs will be auto-published to http://ci.openstack.org/storyboard after each merge very soon. Note(2): To build docs locally run in console: $ tox -e docs and open doc/build/html/index.html Change-Id: I08b57117f90f3e4614bfa5c47020e40a6c26ff65
This commit is contained in:
Ruslan Kamaldinov
parent
ba3d6c98e5
commit
345b1e41cf
|
|
@ -1,17 +1,46 @@
|
|||
If you would like to contribute to the development of OpenStack,
|
||||
you must follow the steps in the "If you're a developer, start here"
|
||||
section of this page:
|
||||
.. _contributing:
|
||||
|
||||
http://wiki.openstack.org/HowToContribute
|
||||
==========================
|
||||
Contributing to Storyboard
|
||||
==========================
|
||||
|
||||
Once those steps have been completed, changes to OpenStack
|
||||
should be submitted for review via the Gerrit tool, following
|
||||
the workflow documented at:
|
||||
If you're interested in contributing to the Storyboard project,
|
||||
the following will help get you started.
|
||||
|
||||
http://wiki.openstack.org/GerritWorkflow
|
||||
Contributor License Agreement
|
||||
-----------------------------
|
||||
|
||||
Pull requests submitted through GitHub will be ignored.
|
||||
.. index::
|
||||
single: license; agreement
|
||||
|
||||
Storyboard uses itself for bug tracking. Bugs should be filed at:
|
||||
In order to contribute to the Storyboard project, you need to have
|
||||
signed OpenStack's contributor's agreement.
|
||||
|
||||
https://stories.openstack.org
|
||||
.. seealso::
|
||||
|
||||
* http://wiki.openstack.org/HowToContribute
|
||||
* http://wiki.openstack.org/CLA
|
||||
|
||||
Project Hosting Details
|
||||
-------------------------
|
||||
|
||||
Bug tracker
|
||||
http://storyboard.openstack.org
|
||||
|
||||
Mailing list (prefix subjects with ``[storyboard]`` for faster responses)
|
||||
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-infra
|
||||
|
||||
Wiki
|
||||
https://wiki.openstack.org/wiki/StoryBoard
|
||||
|
||||
Code Hosting
|
||||
* https://git.openstack.org/cgit/openstack-infra/storyboard/
|
||||
|
||||
* https://git.openstack.org/cgit/openstack-infra/storyboard-webclient
|
||||
|
||||
Code Review
|
||||
https://review.openstack.org/#/q/status:open+AND+(project:openstack-infra/storyboard+OR+project:openstack-infra/storyboard-webclient),n,z
|
||||
|
||||
Please read `GerritWorkflow`_ before sending your first patch for review.
|
||||
|
||||
.. _GerritWorkflow: https://wiki.openstack.org/wiki/GerritWorkflow
|
||||
|
|
|
|||
137
README.rst
137
README.rst
|
|
@ -1,132 +1,35 @@
|
|||
==============================================================
|
||||
StoryBoard - A task tracking system for inter-related projects
|
||||
==============================================================
|
||||
Storyboard
|
||||
==========
|
||||
|
||||
StoryBoard is the Django app (leveraging Bootstrap at the presentation layer)
|
||||
for task tracking across inter-related projects. It is meant to be suitable
|
||||
for OpenStack task tracking.
|
||||
|
||||
Features
|
||||
========
|
||||
|
||||
At this stage, StoryBoard is just a proof-of-concept to see if it's worth
|
||||
investing more into developing it.
|
||||
|
||||
Current features
|
||||
----------------
|
||||
|
||||
*Project views*
|
||||
Basic project views that let you retrieve the list of tasks for a given
|
||||
project, as well as an example of a workflow-oriented view (the 'Triage
|
||||
bugs' view). The current POC is is also just a minimal stub of the project
|
||||
view feature set.
|
||||
|
||||
*Bug tracking*
|
||||
Like Launchpad Bugs, StoryBoard implements bugs as stories, with tasks that
|
||||
may affect various project/branch combinations. You can currently create
|
||||
bugs, tasks for bugs, edit their status, comment on them, etc. The current
|
||||
POC is incomplete: it does not do any sort of form client-side validation,
|
||||
and is missing search features, pagination, results ordering. This should
|
||||
definitely be improved if we go forward with this.
|
||||
Storyboard is a task tracker for OpenStack.
|
||||
|
||||
|
||||
*Feature tracking*
|
||||
The equivalent of Launchpad Blueprints, they inherit the same 'story'
|
||||
framework as bugs. That means they don't have most of the limitations of
|
||||
LP blueprints: you can comment in them, you can have tasks affecting multiple
|
||||
projects, you can even have multiple tasks affecting the same project and
|
||||
order them !
|
||||
-----------------
|
||||
Project Resources
|
||||
-----------------
|
||||
|
||||
*Project groups*
|
||||
Projects can be grouped together arbitrarily, and all 'project' views can
|
||||
be reused by project groups. That makes it easy to triage or track all
|
||||
tasks for projects within a given OpenStack program.
|
||||
Project status, bugs, and blueprints are tracked at:
|
||||
|
||||
*Markdown descriptions and comments*
|
||||
Story descriptions and comments can use markdown for richer interaction.
|
||||
http://storyboard.openstack.org
|
||||
|
||||
Source code can be found at:
|
||||
|
||||
Questionable features
|
||||
---------------------
|
||||
https://git.openstack.org/cgit/openstack-infra/storyboard/
|
||||
|
||||
Some current design choices are questionable and open to discussion:
|
||||
Documentation can be found here:
|
||||
|
||||
Priority is set for the whole story
|
||||
Instead of each task having their own priority, the story itself has a
|
||||
priority. It makes triaging easier, however we may want to be able to have
|
||||
tasks with various priorities within a single story...
|
||||
http://ci.openstack.org/storyboard/
|
||||
|
||||
No invalid/wontfix/opinion status
|
||||
We delete tasks rather than marking them invalid. On the benefits side, that
|
||||
means there is only one way to do it, on the drawbacks side you have to look
|
||||
into history to see if a given project task was considered and abandoned...
|
||||
Additional resources are linked from the project wiki page:
|
||||
|
||||
https://wiki.openstack.org/wiki/StoryBoard
|
||||
|
||||
Future features
|
||||
---------------
|
||||
Anyone wishing to contribute to an OpenStack project should
|
||||
find plenty of helpful resources here:
|
||||
|
||||
*Subscription*
|
||||
Users should be able to subscribe to tasks (and get them in a specific view)
|
||||
as well as subscribe to projects (have their own customized project group).
|
||||
This lets you easily get customized views for the stuff that happens to
|
||||
matters to you, personally.
|
||||
https://wiki.openstack.org/wiki/HowToContribute
|
||||
|
||||
*Gerrit integration*
|
||||
StoryBoard should reuse the projects and groups defined for Gerrit. It should
|
||||
reflect merges with deeper integration than with LP... potentially forcing
|
||||
a 1:1 relationship between tasks and merges (one merge = one task marked
|
||||
'Landed')
|
||||
All OpenStack projects use Gerrit for code reviews.
|
||||
A good reference for that is here:
|
||||
|
||||
*Development cycle tracking*
|
||||
A new tab for StoryBoard, giving you per-cycle and per-milestone views of
|
||||
progress. Would replace the need for status.o.o/releasestatus. Cycles and
|
||||
milestones could be specified per project, although having a default, common
|
||||
set would avoid duplication (and allow cross-project milestone views).
|
||||
|
||||
See https://github.com/ttx/storyboard/issues for more feature backlog.
|
||||
|
||||
|
||||
Install, test and run
|
||||
=====================
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
You'll need the following Python modules installed:
|
||||
- django (1.4+)
|
||||
- django-openid-auth
|
||||
- markdown
|
||||
- python-openid
|
||||
|
||||
You can get them by running::
|
||||
|
||||
pip install -r requirements.txt
|
||||
|
||||
Configuration and DB creation
|
||||
-----------------------------
|
||||
|
||||
Copy storyboard/local_settings.py.sample to storyboard/local_settings.py
|
||||
and change settings there.
|
||||
|
||||
Create empty database, create default admin user:
|
||||
./manage.py syncdb
|
||||
|
||||
|
||||
Basic test using Django development server
|
||||
------------------------------------------
|
||||
|
||||
Run Django development server:
|
||||
./manage.py runserver
|
||||
|
||||
Create basic data via the admin interface: http://127.0.0.1:8000/admin,
|
||||
using the admin credentials above.
|
||||
|
||||
At least:
|
||||
* a master branch
|
||||
* a release branch
|
||||
* a milestone associated with the master branch
|
||||
- the milestone also has to have the undefined box checked
|
||||
* a project
|
||||
|
||||
Then log out and access the application at:
|
||||
http://127.0.0.1:8000/
|
||||
https://wiki.openstack.org/wiki/GerritWorkflow
|
||||
|
|
|
|||
|
|
@ -1,20 +1,41 @@
|
|||
.. storyboard 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 Storyboard's documentation!
|
||||
======================================
|
||||
|
||||
Welcome to storyboard's documentation!
|
||||
========================================================
|
||||
Introduction
|
||||
============
|
||||
|
||||
Contents:
|
||||
StoryBoard is a web application for task tracking across inter-related projects.
|
||||
It is meant to be suitable for OpenStack task tracking.
|
||||
|
||||
StoryBoard consists of two components:
|
||||
* `Storyboard API service`_ - is a Python application leveraging
|
||||
`Pecan`_/`WSME`_ for REST API layer
|
||||
* `Storyboard Web Client`_ - is an all-javascript webclient for the
|
||||
Storyboard API
|
||||
|
||||
|
||||
.. _Pecan: http://pecan.readthedocs.org/en/latest/
|
||||
.. _WSME: http://wsme.readthedocs.org/en/latest/
|
||||
.. _Storyboard API service: https://git.openstack.org/cgit/openstack-infra/storyboard/
|
||||
.. _Storyboard Web Client: https://git.openstack.org/cgit/openstack-infra/storyboard-webclient
|
||||
|
||||
|
||||
|
||||
This documentation offers information on how Storyboard works and how to
|
||||
contribute to the project.
|
||||
|
||||
|
||||
Table of contents
|
||||
=================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
readme
|
||||
installation
|
||||
install/index
|
||||
contributing
|
||||
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,9 @@
|
|||
================================================
|
||||
Installing and Running the Development Version
|
||||
================================================
|
||||
|
||||
See `webclient readme file`_ for details.
|
||||
|
||||
More details will be added later...
|
||||
|
||||
.. _webclient readme file: https://git.openstack.org/cgit/openstack-infra/storyboard-webclient/tree/README.md
|
||||
|
|
@ -0,0 +1,11 @@
|
|||
.. _install:
|
||||
|
||||
======================
|
||||
Installing Storyboard
|
||||
======================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
development
|
||||
manual
|
||||
|
|
@ -0,0 +1,53 @@
|
|||
=====================
|
||||
Installing Manually
|
||||
=====================
|
||||
|
||||
Installing the API service
|
||||
==========================
|
||||
|
||||
1. At the command line::
|
||||
|
||||
$ pip install storyboard
|
||||
|
||||
|
||||
Or, if you have virtualenvwrapper installed::
|
||||
|
||||
$ mkvirtualenv storyboard
|
||||
$ pip install storyboard
|
||||
|
||||
2. By default Storyboard will use SQLite driver which is suitable only for
|
||||
development mode. Storyboard supports MySQL and PostgreSQL backends.
|
||||
To install MySQL driver execute::
|
||||
|
||||
$ pip install MySQL-python
|
||||
|
||||
To install PostgreSQL driver execute::
|
||||
|
||||
$ pip install psycopg2
|
||||
|
||||
3. Edit ``/etc/storyboard/storyboard.conf``. You'll need to modify ``connection``
|
||||
parameter in the ``[database]`` section.
|
||||
|
||||
For MySQL it will look like::
|
||||
|
||||
connection = mysql://root:pass@127.0.0.1:3306/storyboard
|
||||
|
||||
4. Migrate database to current state::
|
||||
|
||||
$ storyboard-db-manage --config-file /etc/storyboard/storyboard.conf upgrade head
|
||||
|
||||
5. Launch API service::
|
||||
|
||||
$ storyboard-api --config-file /etc/storyboard/storyboard.conf
|
||||
|
||||
.. note::
|
||||
|
||||
Is is recommended to use Apache+mod_wsgi for production installation.
|
||||
|
||||
|
||||
Installing the Web Client
|
||||
=========================
|
||||
|
||||
Web Client is an all-javascript application. It doesn't require any software to
|
||||
run. Just grab tarball from http://tarballs.openstack.org/storyboard-webclient,
|
||||
unpack it and serve as static files.
|
||||
|
|
@ -1,12 +0,0 @@
|
|||
============
|
||||
Installation
|
||||
============
|
||||
|
||||
At the command line::
|
||||
|
||||
$ pip install storyboard
|
||||
|
||||
Or, if you have virtualenvwrapper installed::
|
||||
|
||||
$ mkvirtualenv storyboard
|
||||
$ pip install storyboard
|
||||
|
|
@ -1 +0,0 @@
|
|||
.. include:: ../../README.rst
|
||||
Loading…
Reference in New Issue