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

contributing

Jump to bottom
chris grzegorczyk edited this page Oct 14, 2012 · 5 revisions

Table of Contents

Specification Documents

These documents are intentional and intensional[1]:

  • 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 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.

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

Clone this wiki locally