Contribution Guidelines

Contribution Guidelines

In the Contribution Guide, you will find documented policies for developing with Monasca. This includes the processes we use for blueprints and specs, bugs and other procedural items.

Monasca, as with all OpenStack projects, is written with the following design guidelines in mind:

  • Component based architecture: Quickly add new behaviors
  • Highly available: Scale to very serious workloads
  • Fault tolerant: Isolated processes avoid cascading failures
  • Recoverable: Failures should be easy to diagnose, debug, and rectify
  • Open standards: Be a reference implementation for a community-driven api

Workflow

Our process is meant to allow users, developers, and operators to express their desires for new features using Storyboard stories. The workflow is very simple:

  • If something is clearly broken, submit a bug report in Storyboard.
  • If you want to change or add a feature, submit a story in Storyboard.
  • Monasca core reviewers may request that you submit a specification to gerrit to elaborate on the feature request.
  • Significant features require release notes to be included when the code is merged.

Progress on implementation of important stories in Stein release is tracked in Monasca Board on StoryBoard.

Bug Reports

All open bugs can be found in this Worklist.

Bugs triaged in Stein release can be listed here.

The progress of bug-fixing can be tracked in this board.

When filing a bug please remember to add the bug tag to the story. Please provide information on what the problem is, how to replicate it, any suggestions for fixing it, and a recommendation of the priority.

Stories

New features can be proposed in Storyboard as new Story.

The initial story primarily needs to express the intent of the idea with enough details that it can be evaluated for compatibility with the project mission and whether or not the change requires a specification. It is not expected to contain all of the implementation details. If the feature is very simple and well understood by the team, then describe it simply. The story is then used to track all the related code reviews. Team members will request more information as needed.

Specifications

We use the monasca-specs repository for specification reviews. Specifications:

  • Provide a review tool for collaborating on feedback and reviews for complex features.
  • Collect team priorities.
  • Serve as the basis for documenting the feature once implemented.
  • Ensure that the overall impact on the system is considered.

Release Notes

The release notes for a patch should be included in the patch. If not, the release notes should be in a follow-on review.

If any of the following applies to the patch, a release note is required:

  • The deployer needs to take an action when upgrading
  • A new feature is implemented
  • Plugin API function was removed or changed
  • Current behavior is changed
  • A new config option is added that the deployer should consider changing from the default
  • A security bug is fixed
  • Change may break previous versions of the client library(ies)
  • Requirement changes are introduced for important libraries like oslo, six requests, etc.
  • Deprecation period starts or code is purged

A release note is suggested if a long-standing or important bug is fixed. Otherwise, a release note is not required.

Database Migrations

As of the Rocky release, Monasca uses Alembic migrations to set up its configuration database. If you need to change the configuration database’s schema, you need to create a migration to adjust the database accordingly, as follows:

cd monasca_api/db/
alembic revision

This will create a new skeleton revision for you to edit. You will find existing revisions to use for inspiration in the /monasca_api/db/alembic/versions/ directory.

Developer reference

This documentation is generated by the Sphinx toolkit and lives in the source tree. Additional documentation on Monasca and other components of OpenStack can be found on the OpenStack wiki.

Creative Commons Attribution 3.0 License

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.