OpenStack Storage (Swift) Specifications
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
OpenDev Sysadmins dded73b91d OpenDev Migration Patch 1 month ago
doc/source because spelng is hard 3 years ago
specs Merge "Symlink spec updates" 3 years ago
.coveragerc Change ignore-errors to ignore_errors 3 years ago
.gitignore Add the initial specs framework 4 years ago
.gitreview OpenDev Migration Patch 1 month ago
.mailmap Add the initial specs framework 4 years ago
.testr.conf Add the initial specs framework 4 years ago
CONTRIBUTING.rst Workflow documentation is now in infra-manual 4 years ago
LICENSE Add the initial specs framework 4 years ago
MANIFEST.in Add the initial specs framework 4 years ago
README.rst Show team and repo badges on README 2 years ago
requirements.txt Add RSS feed 4 years ago
setup.cfg Add the initial specs framework 4 years ago
setup.py Add the initial specs framework 4 years ago
template.rst Add the initial specs framework 4 years ago
test-requirements.txt Add the initial specs framework 4 years ago
tox.ini Pass environment variables of proxy to tox 3 years ago

README.rst

Team and repository tags

image

Swift Specs Repository

This archive is no longer active. Content is kept for historic purposes.

Documents in this repo are a collection of ideas. They are not necessarily a formal design for a feature, nor are they docs for a feature, nor are they a roadmap for future features.

This is a git repository for doing design review on enhancements to OpenStack Swift. This provides an ability to ensure that everyone has signed off on the approach to solving a problem early on.

Repository Structure

The structure of the repository is as follows:

specs/
    done/
    in_progress/

Implemented specs will be moved to done-directory once the associated code has landed.

The Flow of an Idea from your Head to Implementation

First propose a spec to the in_progress directory so that it can be reviewed. Reviewers adding a positive +1/+2 review in gerrit are promising that they will review the code when it is proposed. Spec documents should be approved and merged as soon as possible, and spec documents in the in_progress directory can be updated as often as needed. Iterate on it.

  1. Have an idea
  2. Propose a spec
  3. Reviewers review the spec. As soon as 2 core reviewers like something, merge it. Iterate on the spec as often as needed, and keep it updated.
  4. Once there is agreement on the spec, write the code.
  5. As the code changes during review, keep the spec updated as needed.
  6. Once the code lands (with all necessary tests and docs), the spec can be moved to the done directory. If a feature needs a spec, it needs docs, and the docs must land before or with the feature (not after).

Spec Lifecycle Rules

  1. Land quickly: A spec is a living document, and lives in the repository not in gerrit. Potential users, ops and developers will look at http://specs.openstack.org/openstack/swift-specs/ to get an idea of what's being worked on, so they need to be quick to land.
  2. Initial version is an idea not a technical design: That way the merits of the idea can be discussed and landed and not stuck in gerrit limbo land.
  3. Second version is an overview of the technical design: This will aid in the technical discussions amongst the community.
  4. Subsequent versions improve/enhance technical design: Each of these versions should be relatively small patches to the spec to keep rule #1. And keeps the spec up to date with the progress of the implementation.

How to ask questions and get clarifications about a spec

Naturally you'll want clarifications about the way a spec is written. To ask questions, propose a patch to the spec (via the normal patch proposal tools) with your question or your understanding of the confusing part. That will raise the issue in a patch review and allow everyone to answer or comment.

Learn As We Go

This is a new way of attempting things, so we're going to be low in process to begin with to figure out where we go from here. Expect some early flexibility in evolving this effort over time.