opendev/storyboard
Code Issues Proposed changes

Update documentation

Browse Source 
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 2014-01-26 21:17:17 +04:00
parent ba3d6c98e5
commit 345b1e41cf
8 changed files with 163 additions and 150 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
CONTRIBUTING.rst
View File

@ -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
View File

@ -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

39
doc/source/index.rst
View File

@ -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
==================

9
doc/source/install/development.rst Normal file
View File

@ -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

11
doc/source/install/index.rst Normal file
View File

@ -0,0 +1,11 @@
.. _install:
======================
Installing Storyboard
======================
.. toctree::
:maxdepth: 2
development
manual

53
doc/source/install/manual.rst Normal file
View File

@ -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.

12
doc/source/installation.rst
View File

@ -1,12 +0,0 @@
============
Installation
============
At the command line::
$ pip install storyboard
Or, if you have virtualenvwrapper installed::
$ mkvirtualenv storyboard
$ pip install storyboard

1
doc/source/readme.rst
View File

@ -1 +0,0 @@
.. include:: ../../README.rst