Contributing to Storyboard

If you’re interested in contributing to the Storyboard project, the following will help get you started.

Contributor License Agreement

In order to contribute to the Storyboard project, you need to have signed OpenStack’s contributor’s agreement.

See also

Got an Issue with StoryBoard?

If you are hitting an error, there’s some new feature that you think would make StoryBoard even more amazing, or just something that could be a little different, please make a story for it! We won’t know if you don’t tell us.

After you’ve created the story (title, description, set the default task to be associated with the opendev/storyboard project, etc), you are welcome to add tags. We have a defined set of tags we use as a project listed below:

  • blocking-storyboard-migration: These stories have been called out as blocking the migration of an OpenStack project from migrating to StoryBoard from Launchpad.
  • its-storyboard: These stories are related to the gerrit plugin “its-storyboard” that pulls information from gerrit for StoryBoard to use, i.e. updating task status, linking gerrit patches to stories, etc.
  • storyboard-email: These stories relate to the email notification functionality and account settings.
  • storyboard-feature-request: Stories with this tag involve implementing some new feature, probably involving both api and webclient updates.
  • storyboard-notifications: Stories with this tag relate to work that needs to be done with the notification mechanism StoryBoard has.
  • storyboard-releases: This tag denotes that the story relates to the release of storyboard on pypi since we have started doing releases.
  • storyboard-searching-enhancements: Stories with this tag relate to work that needs to be done with the searching capabilities in StoryBoard. It could mean work on the jump-to search or to the advanced search that StoryBoard has.
  • storyboard-testing: This tag is applied to stories that are focused on StoryBoard’s testing suite- functional, integration, etc.
  • storyboard-worklists: Stories with this tag relate to work that needs to be done on StoryBoard’s worklist feature.

You’ll notice we have no storyboard-bug, this is because anything that doesn’t generally fit into one of these other categories is likely a bug and we didn’t see a need to tag EVERYTHING.

We also use a few other tags that are more widely applicable to projects other than StoryBoard that may be using StoryBoard. Below they are listed and defined with regards to how we use them:

  • low-hanging-fruit: Stories with this tag on them are good places to get started for newcomers, they are smaller bugs or new features that don’t require a lot of design or discussion.
  • dependency-upgrades: Stories with this tag discuss dependencies that are being utilized by StoryBoard (like libraries) that need to be upgraded.
  • outreachy: Stories with this tag are being worked or will be worked by interns of the outreachy program.

Its also important to note, that more than one tag can be applied to a story if more than one is relevant.

Running the Tests

Storyboard uses tox to manage its unit and functional tests. After installing tox and downloading the storyboard source the next step is to install system dependencies. Run:

$ tox -e bindep

Then take the listed packages and install them with your system package manager. For example:

$ sudo apt-get install package list here

To run the tests quickly on your local development machine you can run the tests with the sqlite backend:

$ tox -e sqlite

And to run the style-checker and static analysis tool:

$ tox -e pep8

If you would like to run the test suite with proper database backends there is one more step to follow. Note that the testsuite takes quite a bit longer to run when using the MySQL and PostgreSQL database backends.

First ensure MySQL and PostgreSQL are running (you may need to start these services). Then run the test-setup.sh helper script:

$ tools/test-setup.sh

This script needs to be run with a user that has sudo access. It will configure the databases as needed to run the unittests. You can then runt the unittests with:

$ tox -e py3

On slower systems, the database migrations may take longer than the default timeout of 120 seconds. To override the timeout, set the OS_TEST_TIMEOUT environment variable. For example, to set the timeout to 3 minutes, run:

$ OS_TEST_TIMEOUT=180 tox -e py3

For More Extensive Testing…

To set up your own local storyboard to see how your changes look in the webclient, see the Installing and Running for Developers.