Documentation/ContentSharing

= OpenStack Content Sharing =

Requirements

 * Non-proprietary OpenStack content resides in OpenStack repository.
 * Ability to substitute variables for product name, endpoints, and so on.
 * Source remains consumable by OpenStack and non-OpenStack consumers.
 * Proprietary content resides in non-OpenStack repositories. Consumable by non-OpenStack consumers.
 * When consumers create content, they include both OpenStack and proprietary source files in their master book files, as needed. Source files can reside in different repositories.
 * Consumers enter values for substitution variables in a configuration file that Jenkins can consume. Ex: productname="Rackspace Cloud Servers"

Risks

 * OpenStack source updates break non-OpenStack books that include that content.
 * OpenStack contributors find the added abstraction layer (substitution variables) annoying to work with.
 * An OpenStack change to an API does not actually affect a non-OpenStack API implementation, how to handle?

Implementation

 * Proof of concept: Verify possibility of cross-repository communication. Work out how to implement substitution variables.
 * Content requirements: Determine which substitution variables are required. Product name? Endpoints? Version number?
 * Content development:
 * Update OpenStack source with substitution variables and publish these for public consumption.
 * Update non-OpenStack book files to include OpenStack source.
 * Content developers subscribe to OpenStack source file changes to ensure any updates do not break their content

Implementation Stakeholders

 * Proof of concept: David Cramer, Jonathan Simonoff, Anne Gentle, Pete Johnson, Diane Fleming
 * Content requirements and development: Anne Gentle, Joe Heck, David Hendler, Rose Coste, Diane Fleming

Implementation Phases

 * 1) Variable substitution
 * 2) Conditional inclusions/exclusions of sections or chapters with branding changes in a single repo
 * 3) Cross-repo inclusions/exclusions
 * 4) Public/private inclusions/exclusions where one repo is source repo (this is not necessarily ideal for OpenStack content sharing)

Workflow

 * Changes from OpenStack community contributor >>>> what does this look like?
 * Changes from non-OpenStack contributor >>>> what does this look like?