2/1/2013
OSRB Policy Document: EDCS-639175
Document Number
EDCS-639175
Owner
OSRB
Last Revision Date
8/4/11
Based on Template
EDCS-814938 Rev 01
Open Source Documentation Process
Guidelines
Authors
Department
Engineering
Legal
Documentation
Operations
Name
Ed Warnicke; George Cravens
Adam Cohn
Carl Albers
Tom Squier
OSRB Approvals
Department
OSRB Engineer
OSRB Attorney
OSRB Operations
Documentation
OSRB Business
Name
Ed Warnicke
Adam Cohn
Dan Gardner
Helen Cavender
Michael Enescu
Modification History
Rev.
01
Date
1/13/11
Originator
Tom Squier
02
4/15/11
Tom Squier
03
04
05
7/16/11
8/4/11
1/18/12
Tom Squier
Tom Squier
Tom Squier
Cisco Systems, Inc.
Comment
First draft of revised open source
documentation guidelines. New format.
Added Flow Diagrams and made changes
from internal review.
Fixed process flow diagram errors
Added direction for multiple downloads
Removed OSDF review requirement
Page 1 of 7
Confidential
2/1/2013
OSRB Policy Document: EDCS-639175
Table of Contents
1
OVERVIEW, PURPOSE, EXECUTIVE SUMMARY, SCOPE
3
1.1 SCOPE
3
2
STATEMENT
3
3
OPEN SOURCE DOCUMENTATION PROCESS
3
3.1 GENERATE THE OPEN SOURCE DOCUMENTATION FILE (OSDF)
3.2 DETERMINE WHERE OSDF IS TO BE PROVIDED
4
5
4
6
PROCESS FLOW DIAGRAMS
4.1 OVERALL OPEN SOURCE DOCUMENTATION FLOW
4.2 DOCUMENTATION RESPONSIBLE PARTY PROCESS FLOW
6
7
5 REFERENCE SECTION RELATED POLICIES, PROCESSES, SUPPORTING
DOCUMENTS
7
6
7
DEFINITIONS
Cisco Systems, Inc.
Page 2 of 7
Confidential
2/1/2013
OSRB Policy Document: EDCS-639175
1 Overview, Purpose, Executive Summary, Scope
A core requirement of nearly every open source license is that certain information (such as license files
and copyright notices) be provided with products that contain open source code. The purpose of this
document is to provide guidelines for a clear and standardized process for generating and distributing this
information in connection with Cisco products.
1.1 Scope
This process applies to documentation prepared in conformance with Cisco policy regarding the use of
third party open-source materials whose license obligations require documentation of source code. See
“Cisco OSRB Third Party software registration & compliance policy” (EDCS-818341).
2 Statement
Cisco requires that any product including open source code include an Open Source Documentation File
(OSDF), which is a consolidated document including all of the required notices and disclosures for the
open source software used in the product.
It is important to understand that this OSDF may not be of interest to many of our customers. However,
ensuring that it is appropriately made available to our customers is an important step to fulfilling our open
source licensing obligations. Therefore, a balance must be struck so that it is always available and easy
to find for customers who want to review it, but that it is not presented to the customer in a manner that
interferes with customer experience and creates customer confusion. For example, a customer looking
for a manual on how to install software should not be required to wade through pages of OSDF
disclosures that are not of interest to that customer.
Another important thing to realize is that the OSDF is not the same thing as the End User License
Agreement. The OSDF does not need to be “accepted” or clicked by the customer. It is simply
information that we are required to make available so that it can be used by those who are interested in
the open source usage within our product.
3 Open source documentation process
The primary tool to aid in open source compliance within Cisco is called IP Central. IP Central, among
other things, aids the technical documentation teams by automatically generating the appropriate OSDF
for any given project. IP Central thus serves as a bridge between developers and writers to insure that
appropriate OSDF documentation is created and made available to documentation teams.
For each release, each unique use of open source code must be entered into the IP Central system.
Information on the purpose and use of IP Central can be found at:
http://wwwin.cisco.com/ops/ee/cosi/ipcentral.shtml
Cisco Systems, Inc.
Page 3 of 7
Confidential
2/1/2013
OSRB Policy Document: EDCS-639175
The following are the process steps to be followed for providing proper open source documentation:
3.1 Generate the Open Source Documentation File (OSDF)
DE Manager or Designate:
Log into IP Central and complete the information required after clicking on the link “Create an IP Central
Project to represent a branch on the source base for my Cisco Product.” Training and a user guide on
how to do this can be found within the tool (http://ipcentral/training and http://ipcentral/userguide/)
Note: You will need to scroll down on the page to complete the information.
Once the information has been completed, you can create your project. Before initiating project creation,
insure that you have the following information regarding your project:
PROJECT DETAILS:
Project Name, Project BU, Project Version, Project Release, BU Eng Owner, Notification Mailer, Project
Description, Executive to Sign Off, Security Contact, Security Mailer, Product Manager, Technology
Group, Product Family,
PROJECT GROUPER DETAILS:
Project Admin Grouper, Project Engineer Grouper, Project Approver Grouper, OR, Product Manager
Grouper, OR, CDETS Project
CDETS INFORMATION:
CDETS Component, CDETS Versions, CDETS Contact, CDETS Instructions
DATE/EDCS DETAILS:
EC Date, FCS Date, PRD EDCS#
RESPONSIBLE PARTIES: Open Source, Publication, Documentation, Engineering, Other
Technical Writer:
Writers (more specifically the release lead) should log into IP Central and follow the instructions to select
the appropriate registered release technology. Once selected, the writer should download the OSDF
document created by IP Central. Instructions on generating documentation can be found within the IP
Central tool Here.
In order to streamline the process of handling open source obligations, a ‘Project State’ (Red, Yellow, and
Green) to indicate the overall status of the project easily has been implemented. In order for the IP
Central Project to transition to the ‘Green’ open source state, the responsible parties must each carry out
their duties. For the documentation responsible party this consists of generating the documentation,
publishing it correctly and then attaching the final documentation to the IP Central Project. In order for a
complete OSDF to be generated the project state should be yellow (all the open source components will
be approved for the Project state to be Yellow). The OSDF can still be generated if the project state is
not yellow, but it may be necessary to update the documentation upon completion of open source
approval. When creating a documentation file to download, if the project has unapproved assets,
the filename being downloaded will be: "NOT_APPROVED_FOR_PUBLIC_POSTING<projectid>.pdf"
Cisco Systems, Inc.
Page 4 of 7
Confidential
2/1/2013
OSRB Policy Document: EDCS-639175
In cases where there are questions about open source documentation the responsible party should
submit a detail description of the issue to opensource-specialists.
3.2 Determine where OSDF is to be provided
The OSDF should be provided in a location that is easy to find for customers who want to review it. The
following is the recommended location for the OSDF depending on how the product documentation is
provided.
If CD/DVD, then publish the file as specified in Publication on Product CD. If a product CD is developed,
the CD must include the final version of the OSDF. The OSDF must be a file (not a link) on the CD.
If the product is downloaded as a tar or compressed file, then ensure that customers can easily find the
final version of the OSDF on the download page.
If posted on Cisco.com, the OSDF is to be posted alongside the Release Note link (if your release notes
are available without a login) in the software download center so that when a customer downloads an
image, the OSDF is right there next to the release notes. An example of this can be found on this
software download page. This will create a fixed universal resource locator (URL) that can be referenced
in every document created for the release. Every software download that is currently made available that
1
includes open source software must have an associated OSDF posted. If the software is no longer
available for download, the associated OSDF no longer needs to be posted.
Once the OSDF has been posted appropriately the documentation responsible party needs to attach the
final version to this project in IP Central and indicate where it is publicly posted post-FCS.
1
This only applies to downloads posted after August 15,2011.
Cisco Systems, Inc.
Page 5 of 7
Confidential
2/1/2013
OSRB Policy Document: EDCS-639175
4 Process Flow Diagrams
4.1 Overall Open Source Documentation Flow
DE creates
project and
registers third
party code
Open Source
Specialist
BU DE
Open Source Documentation Process Flow
DE completes
asset registration
and requests asset
approval
NO
Specialist
reviews open
source assets
All OS Assets
Approved
IP Central
Yes
Open Source
Project State
is Yellow
Yes
IP Central
generates open
source
documentation
file (OSDF)
upon request
No
Open Source
documentation
is validated
Documentation
Responsible
Party
Yes
Writer downloads
OSDF and follows
instructions.
Attach compeleted
open source
documentation to
IP Central Project
Open Source
documentation is
provided in
appropriate
location (CD/DVD/
Website).
Notes: “Yellow” state means all the
open source components are approved
Cisco Systems, Inc.
Page 6 of 7
Confidential
2/1/2013
OSRB Policy Document: EDCS-639175
4.2 Documentation Responsible Party Process Flow
No action required.
No
Documentation
Responsible Party
for the Project logs
into IP Central
Project
Are there any
opens source
documentation
constraints for the
project
Yes
Responsible Party
uses IP Central
feature to generate
Open Source
Documentation
File (OSDF)*
Open Source
Documentation File
(OSDF) created
following IP Central
instructions
No
Responsible Party
attaches final OSDF
to IP Central project
and indicates how/
where it was
published.
Responsible Party
publishes final OSDF
to appropriate media
for the BU (CD/DVD/
Yes
Cisco.com,etc)
Yes
OSDF is ready
to be published.
In order for a complete OSDF to be
generated the project state should be
yellow (all the open source components will
be approved for the Project state to be
Yellow).
*Note:
5 Reference Section Related Policies, Processes,
Supporting Documents
•
EDCS-818341 (Cisco OSRB Third Party software registration & compliance policy)
6 Definitions
<… Define any terms, acronyms, concepts referred to in this document …>
Cisco Systems, Inc.
Page 7 of 7
Confidential