diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 7ac1a33050..9168ab1260 100644 --- 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://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 diff --git a/doc/source/contributor/contributing.rst b/doc/source/contributor/contributing.rst new file mode 100644 index 0000000000..84e60c2852 --- /dev/null +++ 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 `_ 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 `_ +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 +`_ +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 +`_ 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 `_. + +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 `_ 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 `_. You can +find some of them that the team used in the past `in the project Wiki +`_. To share code +snippets or logs, we use `PasteBin `_. + +.. _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") +`_. + +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. +`_ + + +New Feature Planning +~~~~~~~~~~~~~~~~~~~~ + +If you'd like to propose a new feature, do so by `creating a blueprint +on Launchpad. `_ 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 `_ repository and +are published on the `OpenStack Project Specifications website. +`_ Refer to the +`specification template +`_ +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 `_. + +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 `_ +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 `_ +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: +.. _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 diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index bd15b45b6c..68332e403b 100644 --- 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 ------------- diff --git a/doc/source/contributor/project-team-lead.rst b/doc/source/contributor/project-team-lead.rst new file mode 100644 index 0000000000..ec441832de --- /dev/null +++ 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 `_ +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 + `_ + + * Example: https://releases.openstack.org/victoria/schedule.html + +* Ensure the Manila `Cross Project Liaisons + `_ are aware of + their duties and are plugged into the respective areas + +* Acknowledge `community wide cycle 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 + `_ 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 `_ + * `Example Retrospective Etherpad `_ + * `Example PTG Discussions Etherpad `_ + +* 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 diff --git a/doc/source/index.rst b/doc/source/index.rst index 121a20b503..29d01b00b4 100644 --- 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 `_ - -Contributing to Manila -~~~~~~~~~~~~~~~~~~~~~~ - -Contents: +If you are a ``new contributor`` :doc:`start here `. .. toctree:: :maxdepth: 1