Skip to content
This repository has been archived by the owner on Aug 30, 2024. It is now read-only.

Home

Jump to bottom
chris grzegorczyk edited this page Oct 12, 2012 · 60 revisions

Overview

This repository is for handling the architectural documents related to specification and design of Eucalyptus features. Notably, it is not the source for functional requirements: those are in JIRA. Relatedly, the contents here will be reflected in JIRA.

The organization of the repository reflects the long-lived nature of a features true specification. That is, the specification and design work related to a feature's implementation for a particular release often corresponds with only a portion of the entire feature's implementation. Moreover, feature's specification evolves over time as the requirements, architecture, and upstream specifications evolve.

We have four classes of documents which contribute to the definition of the system:

  1. Requirements Documents [1]detail the functionality as drawn from various stakeholders.
  2. Specification Documents are overarching definitions of a feature's architecture and functionality.
  3. Generational Documents specific to the context and determined by the constraints of a particular release.
  4. Architectural documents[2] describe the overall realized design and architecture of the system as released.
    For more documents see the:
    Architecture Docs repository.
    JIRA bug tracker.

Table of Contents

Documents

There are two kinds of documents for which this repository is the canonical reference: specification and generational documents.

Document Categories

Documents By Category
Release 3.0
pending 		3.1
pending 		3.2 3.3
pending
Feature pending
Component pending

Specification Documents

These documents are intentional and intensional[3]:

  • are "timeless" in that they are overarching and meant to be definitive of the feature overall.
  • evolve over time independent of the features current implementation status.
  • reflect our current understanding of the features definition in the broadest sense.
Specification documents consist of:
  • Specification: overall technical specification of the functional and architectural/quality characteristics.
  • High level design/Architecture: definition of fundamental components, interfaces, behaviours including information, control, and concurrency models.
  • Supporting Documents: API/Service specifications, client tool chains, WSDLs, TCKs.

Generational Documents

These documents are specific to a release and meant to serve the tasks surrounding the planning, design, implementation, and delivery of a feature.

  • support the scoping, design, and implementation effort of the feature during that release.
  • defining the design and implementation objectives and details for a particular version of a feature.
  • specific to the context and determined by the constraints of a particular release time frame.
  • change as needed to support the above objectives and are quiesced after those tasks are completed.
Generational documents consist of:
  • Functional requirements: as identified by a corresponding epic in JIRA
  • Specification: release-specific technical interpretation of functional requirements

Contributing

The contents of this repository are reviewed and, to that end, all changes should be submitted as a pull request: Fork & Pull.
  1. Synchronize your fork with this repository.
  2. Make your changes (NOTE: See Formats and Organization below for restrictions/expectations).
  3. Commit to your forked repository.
  4. Submit a pull request.
  5. Be patient and contented.
Formats Broadly, this repository should have version-able source materials except when not available (e.g., third party PDF documentation).
  • Text: must be renderable through the github interface
  • Graphics: must be text-based so a compile step is not only acceptable, but required.
  • Binary files: may be committed in the cases that:
    1. A binary output format (e.g., images) is needed: In this case, it has to be compilable from a text-based and versioned file.
    2. A reference document or tool is included: These belong in specific places noted below.
  • Auto-generated: A number of files in this repo are automatically generated **DO NOT EDIT THEM DIRECTLY**
    1. Any binary file is either auto-generated or 3rd-party.
    2. Surely more of them go here...
Text Format Note
The remainder of this document uses the suffix .wiki to identify a generic file which can be rendered using github-markup.

To use github-markup see the directions at the github-markup repository.

The currently supported and seemingly reasonable formats are:

  • .markdown, .mdown, .md -- gem install redcarpet (https://github.com/vmg/redcarpet)
  • .textile -- gem install RedCloth
  • .mediawiki -- gem install wikicloth
  • .asciidoc -- brew install asciidoc

Organization

The following table describes the organization of the top-level of the repository.
Top-level Directory Structure
features/ this is where all content goes
bin/, lib/ Ignore these. Contain helpers and their libraries
releases/ Ignore these. Contain auto-generated xref of features to releases

Feature Directory

Each feature is contained in its own directory. The organization of the features/${feature} directory, for some imagined ${feature}, is described in the following table:

Feature Directory Structure (e.g., features/${feature}/)
/overview.wiki Top-level document aggregating all the sub documents
/xref xref's to the JIRA epic(s) and confluence pages
/spec.wiki High level architecture document
/diagrams Source materials for diagrams and their generated documents (images)
/X.Y Documents specific to the work done (or going on during) the X.Y release. For example features/${feature}/3.3/ contains documents for the 3.3 release.
/overview.wiki Overview document aggregating all the release specific feature information
/spec.wiki Release specific feature specification
/design Release specific design documents
/xref xref's to the JIRA epic for the current release

See Also

References

  1. ^ https://eucalyptus.atlassian.net/secure/Dashboard.jspa
  2. ^ https://github.com/eucalyptus/architecture-docs
  3. ^ http://en.wikipedia.org/wiki/Intensional_definition
Clone this wiki locally