Difference between revisions of "Training-guides"

Revision as of 20:28, 3 June 2014

openstack-training docs http://docs.openstack.org/training-guides
Blueprint https://blueprints.launchpad.net/openstack-manuals/+spec/training-manuals
weekly meeting agenda https://wiki.openstack.org/wiki/Meetings/training-manuals
trello storyboard https://trello.com/board/openstack-training/51d6e5fee37248fd5b003de9
sfbay-openstack hackathon https://etherpad.openstack.org/sfbay-openstack

Project Goals

• Provide a structured training program to enable skill development for maintaining, consuming, and contributing to OpenStack
• Align to the OpenStack Foundation certification program
• Increase accuracy and usability of documentation and training by engaging user groups and community members across the world
• Increase the amount of skilled engineers and developers in the hiring pool for OpenStack operators and developers
• Enable underrepresented / economically disadvantaged users groups and communities (Africa, Vietnam, Etc) to develop valuable and marketable skills.
• We will be targeting the user group and university audiences first while partnering with commercial interests like Aptira. Commercial interests are encouraged to use and contribute to the project.
• We aim to have as many commercial training programs use this project for the 'core' of their training. It will only improve the quality of the content while limiting the quantity to just the very most important bits.

Project Status

• Currently an incubated project under OpenStack Manuals (PTL = Anne Gentle)
• Currently focused - OpenStack Developer Course Launch

Project requirements

• Reuse the openstack foundation manuals with some additional training specific pages
• Target 80% doc reuse
• Same process as existing manuals
• Leave in space and time for distro specific training
• Training material and lab work would all be based on refstack https://etherpad.openstack.org/RefStackBlueprint, but this work is still evolving

Project Sub-Groups

• stable: (dguitarbite lead) keep the existing training materials up to date and tracking with the current documentation and stable release code
• development: (sarob lead) work on creating the new materials
• testing: (matjazp lead) curators of the quiz and test questions
• infrastructure: (rl, dguitarbite leads) maintain the trainer tools and testing system
• audio visual (AV): (TBD lead) create images, video, and graphics that promote and assist the training project

Project dependencies / issues

• majority of the material will be stitched together from remote github repositories and the local openstack-manuals repository through xi:include statements through the jenkins build process
• breakdown of task management

• in launchpad, the blueprint will hold status and links back to bugs,
• in launchpad bugs on the published documentation will be posted,
• on this wiki page the project status and overview will be posted
• in trello the story boards and sprints will be published and developed

• breakdown of responsibilities

• core: attend weekly IRC meets, attend core sprints when called, through gerrit review bugs and patches
• community: work on submitting bugs, fixing bugs, and suggest new material. All are welcome to participate.

RST-XML Conversion automation

Blueprint here https://blueprints.launchpad.net/openstack-manuals/+spec/rst-xml-conversion This is a one-off sub-project to support the developer guide.

This code is used to convert devref project rst documentation into xml that the openstack manuals project can use. The Training-manuals sub-project will use xi:include statements so the converted xml becomes part of the training guides during build. The conversion script will live in the ./training-guide/sources sub directory of the training-manuals sub-project. The converted xml gets placed within ./training-guide/sources/<project> directories. The conversion script will be run at the same time as when the openstack-manuals repo updates are pulled. All 8 repositories will then be in the same state. This will allow the training manuals team to find xml content and include it with the training guides. If the source RST has a bug, then the RST source will be patched, and the XML will get the bug fix through the next run of the conversion script.

Code details (also in the comments of the script): The code must executed within ./openstack-manuals/doc/training-manuals/sources/. Requirement that pandoc-1.12.0.2 is installed on the local system and that the path to pandoc is part of the user profile. Find pandoc here http://johnmacfarlane.net/pandoc/installing.html. The code will automagically create the 7 'core' openstack repositories and convert the rst docs to xml. The script has four parts: create_repo, pull_repo_updates, convert_rst, and rst_xml_cleanup.

• create_repo: clones the nova, glance, cinder, neutron, swift, keystone, oslo, and horizon repositories into the directory above openstack-manuals repository. It is assumed this is where repositories belong on the local system.
• pull_repo_updates: Intended that all the local repositories are to be pulled for updates before starting a new branch.
• convert_rst: use pandoc to convert the rst to docbook 4.5 xml. Copy over images as well.
• rst_xml_cleanup: convert docbook 4.5 xml to docbook 5.0 along with some cleanup of poorly formatted tags.

Before the rst xml conversion results are accepted in their entirety, a first patch to openstack-manuals will only include the rst files from the cinder project.

• the repo array contains only 'cinder'
• maybe use xslt plus regex to go from 4.5 to 5.0

That patch is here ....

Book structure

• each book needs goals that slightly overlap with the previous and next

• 10 question quiz and 1 scenario at the end of each chapter
• 40+ assessment broken down by each section/question representing a different chapter

• hierarchy: set -> book -> chapter -> section
• book topics

• openstack associate engineer
• openstack operator engineer
• openstack developer engineer
• openstack devOps architect

• publish to docs.openstack.org/training-guides

Book openstack associate

• training would take 1 month self paced, (2) 2 week periods with a user group meeting, or 16 hours instructor led. Some time set aside for distro specific training.
• basic knowledge of core OpenStack components (Compute, Block, Network, Dashboard)
• for the rest see the associate guide online

Book openstack operations engineer

• training would take 2.5 months self paced, (5) 2 week periods with a user group meeting, or 40 hours instructor led with 40 hours of self paced lab time. Some time set aside for distro specific training.
• for the rest see the operator guide online

Book openstack development engineer

• build on concepts from Operator training
• combine how to contribute and working with CI guides into a developers guide
• training would take 2.5 months self paced, (5) 2 week periods with a user group meeting, or 40 hours instructor led with 40 hours of self paced lab time. Some time set aside for distro specific training.
• outline is here

Book openstack devOps architect

• training would take 6 months or (12) 2 week periods with a user group meeting. 240 hours of self paced lab time.
• Meant to be very hard to complete. Public contribution must be a considerable part of the work completed.
• The Architect focuses on a specific OpenStack project as a specialization and becomes a working member of that project. The Architect training will be all about becoming a functioning member of the OpenStack open source community.
• speaking at user groups
• summit session submissions should all count towards karma/contribution
• Passing DevOps training would make the person desirable as an employee.
• Passing DevOps training would make the person desirable as a core contributor to any project

Incubation Plan

Incubation

Scope

Project must have a clear and defined scope.

https://wiki.openstack.org/wiki/Designate/Incubation_Application#Detailed_Description

Project's scope should represent a measured progression for OpenStack as a whole.

https://wiki.openstack.org/wiki/Designate/Incubation_Application#Detailed_Description

Project should not inadvertently duplicate functionality present in other OpenStack projects. If they do, they should have a clear plan and timeframe to prevent long-term scope duplication.

https://wiki.openstack.org/wiki/Designate/Incubation_Application#Why_a_new_project.3F

Mikal: What is the plan for deprecating DNS support in nova? Kiall: Ideally, nova's inbuilt DNS features will be deprecated, with a plugin provided to proxy API calls until it can be removed. The designate team commits to doing this work.

Project should leverage existing functionality in other OpenStack projects as much as possible

https://wiki.openstack.org/wiki/Designate/Incubation_Application#Detailed_Description

Maturity

Project should have an active team of contributors

https://wiki.openstack.org/wiki/Designate/Incubation_Application#Project_developers_qualifications

Project should not have a major architectural rewrite planned

No Major rewrite planned

Process

Project must be hosted under stackforge (and therefore use git as its VCS)

It is - https://git.openstack.org/cgit/stackforge/designate/

Project must obey OpenStack coordinated project interface (such as tox, pbr, global-requirements...)

We do - https://git.openstack.org/cgit/stackforge/designate/tree/tox.ini https://git.openstack.org/cgit/stackforge/designate/tree/setup.cfg

Project should use oslo libraries or oslo-incubator where appropriate

https://git.openstack.org/cgit/stackforge/designate/tree/designate/openstack/common

- not using common DB code, but ekarlso plans to migrate to it soon

If project is not part of an existing program, it needs to file for a new program concurrently with the Incubation request, and fill the corresponding requirements.

https://wiki.openstack.org/wiki/Designate/Program_Application

Project must have a well-defined core review team, with reviews distributed amongst the team (and not being primarily done by one person)

We do. We have a team of 4 cores, (marked on https://wiki.openstack.org/wiki/Designate/Incubation_Application#Project_developers_qualifications )

Reviews should follow the same criteria as OpenStack projects (2 +2s before +A)

We do

Project should use the official openstack lists for discussion

Most conversation is done in IRC, with supplimental email list discussion

API

Project APIs should be reasonably stable

Version 1 API is very stable, and is the current supported API Mikal: What is the timeline for the v2 API, and when will you deprecate v1? Kiall: No current plans to remove V1. Kiall: V2 should be complete during Juno.

Project must have a REST API with at least a JSON entity representation

Yes - the Version 1 API is a JSON/REST API

Project must have a Python client library API for its REST API

It is - https://git.openstack.org/cgit/stackforge/python-designateclient/

QA

Project must have a basic devstack-gate job set up

In progress - we currently used the 3rd party system, but https://review.openstack.org/#/c/97348/ is in progress to add the full devstack gate job

Documentation / User support

Project must have docs for developers who want to contribute to the project

http://designate.readthedocs.org/en/latest/

Project should have API documentation for devs who want to add to the API, updated when the code is updated

http://designate.readthedocs.org/en/latest/rest.html

Legal requirements

Project must be licensed under the Apache License v2

Yes - https://git.openstack.org/cgit/stackforge/designate/tree/LICENSE

Project must have no library dependencies which effectively restrict how the project may be distributed or deployed

We do not have any restricted dependancies

All contributors to the project must have signed the CLA

Yes

Project must have no known trademark issues

None Known

Discussion:    Questions:

Last edit 54757 by Sarob on 20140603202851 (year+month+day+UTC hour+seconds)

training manuals core leaders sarob and colinmcnamara