[cycle-goals] Add PTL and contributor quickstart

These documents borrow from the cinder, nova and ironic guides put together painstakingly by numerous developers. Change-Id: Ida3480fd1b9cab8eeb9ad002cce7200d89e01cb6 Story: #2007236 Task: #38535 Signed-off-by: Goutham Pacha Ravi <gouthampravi@gmail.com>
1 year ago · cf83f96200
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@ -1,19 +1,23 @@
 If you would like to contribute to the development of OpenStack,
 you must follow the steps in this page:
 The source repository for this project can be found at:

   http://docs.openstack.org/infra/manual/developers.html
   https://opendev.org/openstack/manila

 Once those steps have been completed, changes to OpenStack
 should be submitted for review via the Gerrit tool, following
 the workflow documented at:
 This repository is mirrored to GitHub at:

   http://docs.openstack.org/infra/manual/developers.html#development-workflow
   https://github.com/openstack/manila

 Pull requests submitted through GitHub will be ignored.
 Pull requests submitted through GitHub are not monitored.

 Bugs should be filed on Launchpad, not GitHub:
 To start contributing to OpenStack, follow the steps in the contribution guide
 to set up and use Gerrit:

   https://bugs.launchpad.net/manila
   https://docs.openstack.org/contributors/code-and-documentation/quick-start.html

 Bugs should be filed on Launchpad:

   https://bugs.launchpad.net/manila

 For more specific information about contributing to this repository, see the
 Manila contributor guide:

   https://docs.openstack.org/manila/latest/contributor/contributing.html
--- a/doc/source/contributor/contributing.rst
+++ b/doc/source/contributor/contributing.rst
@ -0,0 +1,270 @@
 ============================
 So You Want to Contribute...
 ============================

 For general information on contributing to OpenStack, check out the
 `contributor guide <https://docs.openstack.org/contributors/>`_ to get started.
 It covers all the basics that are common to all OpenStack projects: the
 accounts you need, the basics of interacting with our Gerrit review system,
 how we communicate as a community, etc.

 Below will cover the more project specific information you need to get started
 with Manila (Shared File System service).


 Where is the code?
 ~~~~~~~~~~~~~~~~~~

 manila
    | The OpenStack Shared File System Service
    | code: https://opendev.org/openstack/manila
    | docs: https://docs.openstack.org/manila/
    | api-ref: https://docs.openstack.org/api-ref/shared-file-system
    | release model: https://releases.openstack.org/reference/release_models.html#cycle-with-rc
    | Launchpad: https://launchpad.net/manila


 python-manilaclient
    | Python client library for the OpenStack Shared File System Service API;
      includes standalone CLI shells and OpenStack client plugin and shell
    | code: https://opendev.org/openstack/python-manilaclient
    | docs: https://docs.openstack.org/python-manilaclient
    | release model: https://releases.openstack.org/reference/release_models.html#cycle-with-intermediary
    | Launchpad: https://launchpad.net/python-manilaclient


 manila-ui
    | OpenStack dashboard plugin for the Shared File System Service
    | code: https://opendev.org/openstack/manila-ui
    | docs: https://docs.openstack.org/manila-ui
    | release model: https://releases.openstack.org/reference/release_models.html#cycle-with-intermediary
    | Launchpad: https://launchpad.net/manila-ui


 manila-tempest-plugin
    | An OpenStack test integration (tempest) plugin containing API and
      scenario tests for the Shared File System Service
    | code: https://opendev.org/openstack/manila-tempest-plugin
    | release model: https://releases.openstack.org/reference/release_models.html#cycle-automatic
    | Launchpad: https://launchpad.net/manila


 manila-image-elements
    | A Disk Image Builder project with scripts to build a bootable Linux
      image for testing and use by some Shared File System Service storage
      drivers including the Generic Driver
    | code: https://opendev.org/openstack/manila-tempest-plugin
    | release model: no releases
    | Launchpad: https://launchpad.net/manila


 manila-test-image
    | A project with scripts to create a Buildroot based image to create a
      small bootable Linux image, primarily for the purposes of testing Manila
    | code: https://opendev.org/openstack/manila-image-elements
    | images: https://tarballs.opendev.org/openstack/manila-image-elements/
    | release model: no releases
    | Launchpad: https://launchpad.net/manila-image-elements


 manila-specs
    | Design Specifications for the Shared File System service
    | code: https://opendev.org/openstack/manila-specs
    | release model: no releases
    | Launchpad: https://launchpad.net/manila


 See the ``CONTRIBUTING.rst`` file in each code repository for more
 information about contributing to that specific deliverable. Additionally,
 you should look over the docs links above; most components have helpful
 developer information specific to that deliverable.

 Manila and its associated projects follow a coordinated release alongside
 other OpenStack projects. Development cycles are code named. See the
 `OpenStack Releases website`_ for names and schedules of the current, past
 and future development cycles.


 Communication
 ~~~~~~~~~~~~~

 IRC
 ---

 The team uses `IRC <https://docs.openstack.org/contributors/common/irc.html>`_
 extensively for communication and coordination of project activities. The
 IRC channel is ``#openstack-manila`` on Freenode. Contributors work in various
 timezones across the world; so many of them run IRC Bouncers and appear to be
 always online. If you ping someone, or raise a question on the IRC channel,
 someone will get back to you when they are back on their computer.
 Additionally, the IRC channel is logged, so if you ask a question
 when no one is around, you can `check the log
 <http://eavesdrop.openstack.org/irclogs/%23openstack-manila/>`_
 to see if it has been answered.


 Team Meetings
 -------------
 We host a one-hour IRC based community meeting every Thursday at 1500
 UTC on ``#openstack-meeting-alt`` channel. See the `OpenStack meetings page
 <http://eavesdrop.openstack.org/#Manila_Team_Meeting>`_ for the most
 up-to-date meeting information and for downloading the ICS file to integrate
 this slot with your calendar. The community meeting is a good opportunity to
 gather the attention of multiple contributors synchronously. If you wish to
 do so, add a meeting topic along with your IRC nick to the
 `Meeting agenda <https://wiki.openstack.org/wiki/Manila/Meetings>`_.

 Mailing List
 ------------

 In addition to IRC, the team uses the `OpenStack Discuss Mailing List`_
 for development discussions. This list is meant for communication
 about all things developing OpenStack; so we also use this list to engage with
 contributors across projects, and make any release cycle announcements.
 Since it is a wide distribution list, the use of subject line tags is
 encouraged to make sure you reach the right people. Prefix the
 subject line with ``[manila]`` when sending email that concern Manila on
 this list.


 Other Communication Avenues
 ---------------------------

 Contributors gather at least once per release at the `OpenDev Project Team
 Gathering <https://www.openstack.org/ptg>`_ to discuss plans for an upcoming
 development cycle. This is usually where developers pool ideas and
 brainstorm features and bug fixes. We have had both virtual, and in-person
 Project Technical Gathering events in the past. Before every such event, we
 gather opinions from the community via IRC Meetings and the Mailing list on
 planning these Project Technical Gatherings.

 We make extensive use of `Etherpads <https://etherpad.opendev.org>`_. You can
 find some of them that the team used in the past `in the project Wiki
 <https://wiki.openstack.org/wiki/Manila/Etherpads>`_. To share code
 snippets or logs, we use `PasteBin <http://paste.openstack.org>`_.

 .. _contacting-the-core-team:

 Contacting the Core Team
 ~~~~~~~~~~~~~~~~~~~~~~~~

 When you contribute patches, your change will need to be approved by one or
 more `maintainers (collectively known as the "Core Team")
 <https://wiki.openstack.org/wiki/Manila#People>`_.

 We're always looking for more maintainers! If you're looking to help
 maintain Manila, express your interest to the existing core team. We have
 mentored many individuals for one or more development cycles and added them to
 the core team.

 Any new core reviewer needs to be nominated to the team by an existing core
 reviewer by making a proposal on `OpenStack Discuss Mailing List`_. Other
 maintainers and contributors can then express their approval or disapproval
 by responding to the proposal. If there is a decision, the project team lead
 will add the concerned individual to the core reviewers team. An example
 proposal is `here.
 <http://lists.openstack.org/pipermail/openstack-discuss/2020-February/012677.html>`_


 New Feature Planning
 ~~~~~~~~~~~~~~~~~~~~

 If you'd like to propose a new feature, do so by `creating a blueprint
 on Launchpad. <https://blueprints.launchpad.net/manila>`_ For significant
 changes we might require a design specification.

 Feature changes that need a specification include:
 --------------------------------------------------

 - Adding new API methods
 - Substantially modifying the behavior of existing API methods
 - Adding a new database resource or modifying existing resources
 - Modifying a share back end driver interface, thereby affecting all share
  back end drivers

 What doesn't need a design specification:
 -----------------------------------------

 - Making trivial (backwards compatible) changes to the behavior of an
  existing API method. Examples include adding a new field to the response
  schema of an existing method, or introducing a new query parameter. See
  :doc:`api_microversion_dev` on how Manila APIs are versioned.
 - Adding new share back end drivers or modifying share drivers, without
  affecting the share back end driver interface
 - Adding or changing tests

 After filing a blueprint, if you're in doubt whether to create a design
 specification, contact the maintainers.

 Design specifications are tracked in the `Manila
 Specifications <https://opendev.org/openstack/manila-specs>`_ repository and
 are published on the `OpenStack Project Specifications website.
 <https://specs.openstack.org/openstack/manila-specs/>`_ Refer to the
 `specification template
 <https://specs.openstack.org/openstack/manila-specs/specs/template.html>`_
 to structure your design spec.

 Specifications and new features have deadlines. Usually, specifications for
 an upcoming release are frozen midway into the release development
 cycle. To determine the exact deadlines, see the published release calendars
 by navigating to the specific release from the `OpenStack releases website`_.


 Task Tracking
 ~~~~~~~~~~~~~

 - We track our bugs in Launchpad:

  https://bugs.launchpad.net/manila

  If you're looking for some smaller, easier work item to pick up and get
  started on, search for the 'low-hanging-fruit' tag

 - We track future features as blueprints on Launchpad:

  https://blueprints.launchpad.net/manila

 - Unimplemented specifications are tracked here:

  https://specs.openstack.org/openstack/manila-specs/#unimplemented-specs

  These specifications need a new owner. If you're interested to pick them
  up and drive them to completion, you can update the corresponding blueprint
  and get in touch with the project maintainers for help


 Reporting a Bug
 ~~~~~~~~~~~~~~~

 You found an issue and want to make sure we are aware of it? You can do so on
 `Launchpad <https://bugs.launchpad.net/manila>`_.

 Getting Your Patch Merged
 ~~~~~~~~~~~~~~~~~~~~~~~~~

 When you submit your change through Gerrit, a number of automated Continuous
 Integration tests are run on your change. A change must receive a +1 vote
 from the `OpenStack CI system <https://zuul.opendev.org/t/openstack/status>`_
 in order for it to be merge-worthy. If these tests are failing and you can't
 determine why, contact the maintainers.

 See the :doc:`manila-review-policy` to understand our code review
 conventions. Generally, reviewers look at new code submissions pro-actively;
 if you do not have sufficient attention to your change, or are looking for
 help, do not hesitate to jump into the team's IRC channel, or bring our
 attention to your issue during a community meeting. The core team would
 prefer to have an open discussion instead of a one-on-one/private chat.


 Project Team Lead Duties
 ~~~~~~~~~~~~~~~~~~~~~~~~

 A `project team lead <https://docs.openstack.org/project-team-guide/ptl.html>`_
 is elected from the project contributors each cycle. Manila Project specific
 responsibilities for a lead are listed in the :doc:`project-team-lead`.


 .. _OpenStack Releases website: <https://releases.openstack.org>
 .. _OpenStack Discuss Mailing List: http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-discuss
 .. _Manila Project Team Lead guide: ../project-team-lead.rst
 .. _API Microversions: ../api_microversion_dev.rst
--- a/doc/source/contributor/index.rst
+++ b/doc/source/contributor/index.rst
@ -21,6 +21,15 @@ Contributor/Developer Guide
 In this section you will find information helpful for contributing to manila.


 Basic Information
 -----------------

 .. toctree::
   :maxdepth: 3

   contributing


 Programming HowTos and Tutorials
 --------------------------------
 .. toctree::
@ -59,6 +68,7 @@ Other Resources
   launchpad
   gerrit
   manila-review-policy
   project-team-lead

 API Reference
 -------------
--- a/doc/source/contributor/project-team-lead.rst
+++ b/doc/source/contributor/project-team-lead.rst
@ -0,0 +1,205 @@
 ..
      Licensed under the Apache License, Version 2.0 (the "License"); you may
      not use this file except in compliance with the License. You may obtain
      a copy of the License at

          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
      License for the specific language governing permissions and limitations
      under the License.

 Manila Project Team Lead guide
 ==============================

 A `project team lead <https://docs.openstack.org/project-team-guide/ptl.html>`_
 for Manila is elected from the project contributors. A candidate for PTL
 needn't be a core reviewer on the team, but, must be a contributor,
 and be familiar with the project to lead the project through
 its release process. If you would like to be a core reviewer begin by
 :ref:`contacting-the-core-team`. All the responsibilities below help us in
 maintaining the project. A project team lead can perform any of these or
 delegate tasks to other contributors.

 General Responsibilities
 ------------------------

 * Ensure manila meetings have a chair

  * https://opendev.org/opendev/irc-meetings/src/branch/master/meetings/manila-team-meeting.yaml

 * Update the team people wiki

  * https://wiki.openstack.org/wiki/Manila#People


 Release cycle activities
 ------------------------

 * Get acquainted with the release schedule and set Project specific
  milestones in the `OpenStack Releases repository
  <https://opendev.org/openstack/releases>`_

  * Example: https://releases.openstack.org/victoria/schedule.html

 * Ensure the Manila `Cross Project Liaisons
  <https://wiki.openstack.org/wiki/CrossProjectLiaisons>`_ are aware of
  their duties and are plugged into the respective areas

 * Acknowledge `community wide cycle goals
  <https://governance.openstack.org/tc/goals/#community-goals>`_ and find
  leaders and coordinate with the goal liaisons

 * Plan team activities such as:

  * ``Documentation day/s`` to groom documentation bugs and re-write
    release cycle docs
  * ``Bug Triage day/s`` to ensure the bug backlog is well groomed
  * ``Bug Squash day/s`` to close bugs
  * ``Collaborative Review meeting/s`` to perform a high-touch review of a code
    submission over a synchronous call

 * Milestone driven work:

  * ``Milestone-1``:

    - Request a release for the python-manilaclient and manila-ui
    - Retarget any bugs whose fixes missed Milestone-1

  * ``Milestone-2``:

    - Retarget any bugs whose fixes missed Milestone-2
    - Create a review priority etherpad and share it with the community
      and have reviewers sign up

  * ``Milestone-3``:

    - Groom the release notes for python-manilaclient and add a 'prelude'
      section describing the most important changes in the release
    - Request a final cycle release for python-manilaclient
    - Retarget any bugs whose fixes missed Milestone-3
    - Grant/Deny any Feature Freeze Exception Requests
    - Update task trackers for Community Wide Goals
    - Write the cycle-highlights in marketing-friendly sentences
      and propose to the openstack/releases repo. Usually based on reno
      prelude but made more readable and friendly

      * Example: https://review.opendev.org/717801/

    - Create the launchpad series and milestones for the next cycle in
      manila, python-manilaclient and manila-ui. Examples:

      * manila: https://launchpad.net/manila/ussuri
      * python-manilaclient: https://launchpad.net/python-manilaclient/ussuri
      * manila-ui: https://launchpad.net/manila-ui/ussuri

  * ``Before RC-1``:

    - Groom the release notes for manila-ui and add a 'prelude'
      section describing the most important changes in the release
    - Request a final cycle release for manila-ui
    - Groom the release notes for manila, add a 'prelude' section
      describing the most important changes in the release
    - Mark bugs as {release}-rc-potential bugs in launchpad, ensure they
      are targeted and addressed by RC

  * ``RC-1``:

    - Request a RC-1 release for manila
    - Request a final cycle tagged release for manila-tempest-plugin
    - Ensure all blueprints for the release have been marked "Implemented"
      or are re-targeted

  * ``After RC-1``:

    - Close the currently active series on Launchpad for manila,
      python-manilaclient and manila-ui and set the "Development Focus"
      to the next release. Alternatively, you can switch this on the
      series page by setting the next release to “active development”
    - Set the last series status in each of these projects to “current
      stable branch release”
    - Set the previous release's series status to “supported”
    - Move any Unimplemented specs in `the specs repo
      <https://opendev.org/openstack/manila-specs>`_ to "Unimplemented"
    - Create a new specs directory in the specs repo for the next
      cycle so people can start proposing new specs

 * You should NOT plan to have more than one RC. RC2 should only happen
  if there was a mistake and something was missed for RC-1, or a new regression
  was discovered

 * Periodically during the release:

  * ``Every Week``:

    - Coordinate the weekly Community Meeting agenda
    - Coordinate with the Bug Czar and ensure bugs are properly triaged
    - Check whether any bug-fixes must be back-ported to older stable
      releases

  * ``Every 3 weeks``:

    - Ensure stable branch releases are proposed in case there are any
      release worthy changes. If there are only documentation or CI/test
      related fixes, no release for that branch is necessary

 * To request a release of any manila deliverable:

  * ``git checkout {branch-to-release-from}``

  * ``git log --no-merges {last tag}..``

    * Examine commits that will go into the release and use it to decide
      whether the release is a major, minor, or revision bump according to
      semver

  * Then, propose the release with version according to semver x.y.z

    * X - backward-incompatible changes

    * Y - features

    * Z - bug fixes

  * Use the ``new-release`` command to generate the release

    * https://releases.openstack.org/reference/using.html#using-new-release-command


 Project Team Gathering
 ----------------------

 * Create etherpads for PTG planning, cycle retrospective and PTG discussions
  and announce the Planning etherpad to the community members via the Manila
  community meeting as well as the `OpenStack Discuss Mailing List`

  * `Example PTG Planning Etherpad <https://etherpad.opendev.org/p/manila-shanghai-ptg-planning>`_
  * `Example Retrospective Etherpad <https://etherpad.opendev.org/p/manila-stein-retrospective>`_
  * `Example PTG Discussions Etherpad <https://etherpad.opendev.org/p/manila-ptg-train>`_

 * If the PTG is a physical event, gather an estimate of attendees and
  request the OpenDev Foundation staff for appropriate meeting space. Ensure
  the sessions are remote attendee friendly. Coordinate A/V logistics

 * Set discussion schedule and find an owner to run each proposed discussion at
  the PTG

 * All sessions must be recorded, nominate note takers for each discussion

 * Sign up for group photo at the PTG (if applicable)

 * After the event, send PTG session summaries and the meeting recording to the
  `OpenStack Discuss Mailing List`

 Summit
 ------

 * Prepare the project update presentation. Enlist help of others

 * Prepare the on-boarding session materials. Enlist help of others


 .. _OpenStack Discuss Mailing List: http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-discuss
 .. _contacting the core team: contributing#contacting-the-core-team
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@ -109,19 +109,7 @@ Additional resources
 For contributors
 ----------------

 Contributions to Manila are welcome. There is a lot of background information that
 can help you get started. Please feel free to also ask any questions in
 the **#openstack-manila** IRC channel.

 Getting started
 ~~~~~~~~~~~~~~~

 * `OpenStack Contributor Guide <https://docs.openstack.org/contributors/>`_

 Contributing to Manila
 ~~~~~~~~~~~~~~~~~~~~~~

 Contents:
 If you are a ``new contributor`` :doc:`start here <contributor/contributing>`.

 .. toctree::
   :maxdepth: 1