Jump to: navigation, search

PTL Guide

(Redirected from PTLguide)

This is intended to be a living document sharing the common conventions and mechanisms used in managing integrated projects in OpenStack.

What is a PTL?

PTL means Project Team Lead. Each OpenStack official project team elects a leader who has final say over all things in that specific project team (and all the code repositories within it).

What it takes to be a PTL


The PTL must be familiar with the process of contributing to OpenStack and tools related to making code updates and getting them in place. In particular:


The PTL is expected to have sufficient time to dedicate to interaction with the release team. That includes presence at the 1:1 sync points and weekly cross-project meetings, but also extra availability on milestone and release weeks. The dates for milestones and releases being known well in advance, please make sure you have sufficient free time on those special weeks. If your job doesn't give you sufficient free time to dedicate to release management, please consider stepping down and let someone with more time on their hands taking over.

Organizing the Design Summit

The PTL is responsible for selecting and scheduling proposed sessions at the Design Summit immediately following his or her election. See Summit/SchedulingForPTLs for details on the process.

Interactions with the Release team

Participating in weekly 1:1 sync points

Project status and roadmap are maintained via weekly, 15-minute 1:1 sync points between PTLs and the Release Management teams. The scheduled time for the weekly, cross-project meeting can be found at the bottom of this page.

During this sync point, the release manager will review the state of the integrated project against the current position in the release cycle. For example, during the juno-2 milestone development timeframe, the Keystone PTL will review for Keystone: https://launchpad.net/keystone/+milestone/juno-2 . PTLs may also ask questions, mention news items and add cross-project meeting topics.

Participating to the weekly cross-project IRC meeting

In addition to the 1:1 sync points, we also discuss cross-project issues potentially affecting the integrated release at the weekly cross-project release meeting.

In addition to exposing the news from the 1:1 sync points and other project teams, specific agenda topics requested by PTLs make up the meeting agenda. This meeting is the opportunity to raise issues and increase coordination between projects and ensure a successful integrated release.

The PTL should be present at the meeting, or have a delegate that can report on progress, make calls to action, and generally be prepared to answer questions about the project from the general community.

Maintaining Cycle plans

The PTL is expected to produce and maintain general objectives for the development cycle in the cycle plan. This plan contains the blueprints that are expected to be worked on during the cycle. You can find it at blueprints.launchpad.net/PROJECT/CYCLE, for example for Nova in Juno: https://blueprints.launchpad.net/nova/juno .

You can add or remove blueprints in that plan by setting a priority and a milestone target in the blueprints (an automated script will adjust the series goal to match the milestone target). Blueprints in the cycle plan should have an indicative milestone set, indicating when in the cycle the feature is expected to be completed. Blueprints in the cycle plan should also have an assignee: the person or development group that has committed to delivering the feature in OpenStack.

If you're using a -specs repository, the spec2bp.py tool can be used when a spec is approved, to automatically set the corresponding blueprint fields accordingly.

Maintaining Milestone plans

This cycle plan trickles down into milestone plans, for each milestone. Milestone plans appear at: launchpad.net/PROJECT/+milestone/MILESTONE, for example for Nova on juno-3: https://launchpad.net/nova/+milestone/juno-3 . When a milestone is in progress, it's important to keep the status of the blueprints accurate: the assignee is supposed to keep the status current, and the PTL to ensure that the status reflects reality. See the [[Blueprints blueprints field reference] for more details.

Maintaining Targeted bugs

The PTL can also target bugs that need to be fixed by a specific milestone. Those bugs will appear on the milestone plans, and be reviewed regularly during the weekly sync points.

Special actions on Milestone delivery week

Starting with Juno, development milestones are just tagged directly on the master branch. The job of the PTL is to communicate to the release manager an appropriate SHA for tagging, sometimes between Tuesday and Thursday during the milestone delivery week.

In preparation for that, it's a good idea to refine the milestone plan so that the only incomplete items are the things you are waiting for before tagging: the milestone page becomes your "remaining TODO before tag" tracker. Everything else should be deferred to the next milestone.

When the milestone SHA is determined, the milestone plan should only contain Implemented blueprints, and Fix Committed bugs: everything else should be deferred to the next development milestone.

Upon reception of this milestone SHA, the release manager pushes the tag, sets all FixCommitted bugs to FixReleased on the target milestone, generates and uploads the corresponding tarball, and marks the milestone released.

Special actions between Feature freeze and RC1

At the end of the cycle, after the last development milestone, we are under FeatureFreeze until we publish a first release candidate. During FeatureFreeze, the PTL and the core reviewers should ensure that no feature makes its way into the master branch, unless it was granted a feature freeze exception. Feature freeze exceptions are discussed between the PTL and the release manager, generally looking for consensus. In case no consensus can be reached on a feature freeze exception, the PTL has final say.

We use the RC1 milestone page to track the work that's left to do before we can issue the first release candidate. All known release blockers must be targeted to the RC milestone. Once that list is empty, we can publish the first release candidate (RC1). It is therefore important to keep that list current and reasonable. At this point we also create the release branch (for example proposed/juno for the Juno release), and the master branch is reopened for development (FeatureFreeze ends).

Special actions between RC1 and final release

The RC1 will be used as the release, unless a release-critical bug is found that warrants a release candidate respin. Release-critical bugs that may trigger a respin should be tagged series-rc-potential (for example juno-rc-potential), and are reviewed by the PTL and the release manager to see if they are worth a respin. As time passes, we get more picky about what should trigger a respin and what should be documented as a known issue. If a respin is warranted, we open a new milestone page to track the work to complete before the new RC can be published. It is recommended to only target bugs which already have a fix merged in master.

We use two different statuses for master and proposed/* merges, which allows tracking of RC bugs:

  • FixCommitted means "merged in master branch"
  • FixReleased means "merged in proposed/foo branch"

Changes proposed to proposed/* can be accepted by PTLs and the release manager. The policy for accepting those changes is to doublecheck that the fix is targeted to the milestone, and has landed in master first.

The process for backporting changes to proposed/* is described here.

Interacting with Launchpad


Each integrated project has a project page on launchpad:

  • https://launchpad.net/projectname
  • links to Code, Documentation and Community pages
  • references to bugs and blueprints
  • shows series, milestones, and links to corresponding release deliverables

Each project typically has multiple teams associated with it (the same person :

  • <projectname>-drivers (https://launchpad.net/~projectname-drivers)
    • folks responsible for maintaining the roadmap and objectives
    • can manage milestones, blueprints and blueprint settings
    • includes the PTL and anybody the PTL delegate this authority to
    • should include the Release managers team (~openstack-release) so that they can help in setting bug status
  • <projectname>-bugs (https://launchpad.net/~projectname-bugs)
    • can set importance and specific statuses to bugs
    • core devs from Gerrit and LP -drivers team are generally part of it
  • <projectname>-coresec (https://launchpad.net/~projectname-coresec)
    • will be added to private security bugs
    • core devs with interest and time for helping with security issues

There is also sometimes a generic ~projectname team (https://launchpad.net/~projectname) but it's not really used for anything anymore.



Receiving bug reports and specific, (ideally reproducible) problems from the community. Anyone can open a bug report against a project.

Bugs can be used to indicate small-sized feature additions or work tasks as well. Since bugs can be tagged (where blueprints can't), bugs can be a useful medium for triaging and working against lists of issues to achieve a specific goal.

A single bug in Launchpad can have multiple bug tasks, which can be project tasks or series tasks. Project tasks are used to track tasks necessary to fix the bug across several projects (so you can have a single bug affecting multiple OpenStack projects). Series tasks are also used to track backport work: you can nominate the bug for a given past series to track the completion of the backport of a bug to a stable/* branch. See here for an example.

Bugs are generally completely open. A special case of bug report is a security vulnerability. In general, these bugs are submitted as embargoed security bugs and only the reporter and the OpenStack VulnerabilityManagement team see these bugs initially. Access is controlled through bug "subscription". The project security team (coresec) of the affected project is quickly added to the access list, and additional folks can be subscribed from any of the people currently able to see the issue. As soon as possible, embargoed security issues are unembargoed and accessible by everyone.

Please learn the meaning of the different fields in a bug (status, importance...) at: Bugs

By default, bugs sort of importance, and then status - so setting the importance higher implies that they're more important to get solved.

Bugs (unlike blueprints) can be tagged with ad-hoc tags as well, and then those tags searched or filtered on. You can see official tags at: BugTags.

Another important field is the milestone associated with the bug. Bugs associated with a milestone mean that they're intended to be closed in that milestone. Later in a release cycle, a milestone "cut" will be blocked by open bugs associated with that milestone.


A PTL should make sure all new bugs are reviewed on a frequent basis - at least weekly:



We use blueprints to track incoming features and build a short-term roadmap. A blueprint may require one or more code commits to complete. Blueprints have a short description, link to spec, priority, delivery status, assignee, and can be targeted to a milestone. Anyone can propose a blueprint, but they should only appear in a milestone or a series plan if they are granted a priority and a target milestone by the PTL or one of the projects drivers.

Please learn the meaning of the different fields in a blueprint at: Blueprints


The milestone pages are used as a PTL communication tool, to reflect the PTL's current view on what's likely to land in the upcoming development milestones. A PTL should therefore strive to keep that view updated, by adding blueprints, setting priority and target milestones to correspond to the work being done. PTLs should also make sure that the implementation status is up to date, to accurately reflect progress.

Project-specific milestone plans are aggregated to build a single integrated release view at: [1]

As we get closer to the milestone delivery week, the PTL should review the blueprints and defer to the next milestone anything that is no longer likely to meet the milestone delivery date. Any such deferrals should be communicated as soon as possible.

Ask OpenStack

Ask OpenStack is the preferred way for community to ask for support. Anyone can open a question, and anyone can answer a question. Questions can be tagged by the project name, usually tagging is done by the person asking and/or by Ask moderators.

Answers can be linked to an existing bug report using the syntax lp:BUGNUMBER.


A PTL should make sure open questions get reviewed on a frequent basis - at least weekly: