diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 1552f0e5..83f8fc36 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -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 diff --git a/README.rst b/README.rst index 19589abd..64a3a7c3 100644 --- a/README.rst +++ b/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 diff --git a/doc/source/index.rst b/doc/source/index.rst index e60822d1..be6a1c63 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -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 ================== diff --git a/doc/source/install/development.rst b/doc/source/install/development.rst new file mode 100644 index 00000000..86432865 --- /dev/null +++ b/doc/source/install/development.rst @@ -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 \ No newline at end of file diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst new file mode 100644 index 00000000..65dc4201 --- /dev/null +++ b/doc/source/install/index.rst @@ -0,0 +1,11 @@ +.. _install: + +====================== + Installing Storyboard +====================== + +.. toctree:: + :maxdepth: 2 + + development + manual diff --git a/doc/source/install/manual.rst b/doc/source/install/manual.rst new file mode 100644 index 00000000..46bcfa52 --- /dev/null +++ b/doc/source/install/manual.rst @@ -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. \ No newline at end of file diff --git a/doc/source/installation.rst b/doc/source/installation.rst deleted file mode 100644 index 89e286ad..00000000 --- a/doc/source/installation.rst +++ /dev/null @@ -1,12 +0,0 @@ -============ -Installation -============ - -At the command line:: - - $ pip install storyboard - -Or, if you have virtualenvwrapper installed:: - - $ mkvirtualenv storyboard - $ pip install storyboard diff --git a/doc/source/readme.rst b/doc/source/readme.rst deleted file mode 100644 index a6210d3d..00000000 --- a/doc/source/readme.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../README.rst