Home

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 three classes of documents which contribute to the definition of the system:

Specification Documents are overarching definitions of a feature.
Generational Documents specific to the context and determined by the constraints of a particular release.
Architectural documents^[1] are the final documents describing the architecture of the system combining the intensional and emergent characteristics.
For more documents see the separate architecture docs repository.

Briefly, the repository is organized as follows:

**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

Table of Contents Overview Documents Specification Documents Generational Documents Contributing Organization Feature Directory See Also References

Documents

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

Specification Documents

These documents are intentional and intensional^[2]:

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

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

Contributing

The contents of this repository are reviewed and, to that end, all changes should be submitted as a pull request: Fork & Pull.

Get a github account.
Create a fork of this repository.

Synchronize your fork with this repository.
Make your changes (NOTE: See Formats and Organization below for restrictions/expectations).
Commit to your forked repository.
Submit a pull request.
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