openstack
/
manila
Code Issues Proposed changes

Add new feature guidelines documentation 

Includes additional documentation to support contributors while
submitting new changes to Manila.

Change-Id: I7878f226c294c873b5086a6504b507dad574eda7
This commit is contained in:
silvacarloss 2023-10-19 15:57:08 -03:00
parent ad29f8a065
commit d1edbdbaec
7 changed files with 228 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/source/contributor/addmethod.openstackapi.rst
View File

@ -14,6 +14,8 @@
License for the specific language governing permissions and limitations
under the License.
.. _adding-a-new-api:
Adding a Method to the OpenStack Manila API
===========================================

2
doc/source/contributor/contributing.rst
View File

@ -174,6 +174,8 @@ 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.
.. _features-that-require-spefication:
Feature changes that need a specification include:
--------------------------------------------------

2
doc/source/contributor/development-environment-devstack.rst
View File

@ -12,6 +12,8 @@
License for the specific language governing permissions and limitations
under the License.
.. _setting-up-manila-devstack:
Setting up a development environment with devstack
==================================================

1
doc/source/contributor/index.rst
View File

@ -35,6 +35,7 @@ Programming HowTos and Tutorials
.. toctree::
:maxdepth: 3
new_feature_workflow
development.environment
development-environment-devstack
apache-httpd

217
doc/source/contributor/new_feature_workflow.rst Normal file
View File

@ -0,0 +1,217 @@
..
Copyright 2023 Red Hat, Inc.
All Rights Reserved.
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.
Proposing new features
======================
Planning and working on new features is a hard task. This documentation
suggests a workflow and highlights what is expected, suggested and
required when working on new features in the OpenStack Manila project.
Planning the feature
~~~~~~~~~~~~~~~~~~~~
Features should always start with planning. It is important to start by
discussing the problems and possible solutions with the community, bringing up
the use cases it will cover, corner cases and alternative approaches,
so we suggest the following process:
Registering a blueprint
-----------------------
When starting a new feature, you should file a blueprint in the
OpenStack Manila `Launchpad tracker <https://blueprints.launchpad.net/manila>`_.
This blueprint should have a brief description of the feature, and it will be
used to track all changes proposed to the implementation, including the Manila
core changes, functional tests and the OpenStack client changes. One example
blueprint would be the share server migration
`blueprint <https://blueprints.launchpad.net/manila/+spec/share-server-migration>`_.
Discussing the feature during the PTG
-------------------------------------
The OpenStack PTG is a very good timing to discuss new features, as the
upstream community is focused on planning and shaping the upcoming release.
So it is encouraged that you host a topic during the PTG to talk about the
design of the feature and have the community helping you shape it.
In case you missed the PTG deadline to bring up such features, you can also
add a topic to the Manila community weekly IRC meeting
`agenda <https://wiki.openstack.org/wiki/Manila/Meetings#Next_meeting>`_ and
request feedback from the community.
As a result, you can get different perspectives on the design of the feature
and raise awareness, so there are no surprises when the feature is being
proposed.
One other outcome of this discussion is determining the necessity of a
specification. The community will use
:ref:`pre-defined <features-that-require-spefication>` factors to decide if you
need a specification or not.
Writing a specification
-----------------------
After determining if a specification is necessary for your proposed feature,
you will need to write in more details about the problem you are trying to
solve, the use cases and all the impact this change will have in terms of API
changes, database, security and other aspects. The specification will be
reviewed by different people, and this process is crucial for hashing out
details. Please check the OpenStack Manila
`example specification <https://specs.openstack.org/openstack/manila-specs/specs/template.html>`_
and follow its guidelines. If you are working on a smaller feature, you may
submit a "lite spec". Please follow
`this example <https://github.com/openstack/manila-specs/blob/master/specs/wallaby/spec-lite-add-max-shares-on-share-server-limit.rst>`_.
Working on the implementation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is when the coding happens. You will work on the feature and the code
you write must follow the OpenStack coding
`guidelines <https://docs.openstack.org/hacking/latest/user/hacking.html>`_.
You can find examples of database migrations, driver implementations,
RPC APIs and many other changes in the Manila code base. As our code has been
worked on and improved over the years, there is a high chance that someone else
implemented something similar to what you are doing now, so keeping the
consistency with feature implementation is very important.
In case you are making changes to the API or adding new APIs, please
read the :ref:`Manila API contributor docs <adding-a-new-api>`.
Development environment
-----------------------
So you have worked on your changes and would like to test them?
:ref:`Devstack <setting-up-manila-devstack>` is likely the easiest way to go.
With devstack, you can have OpenStack installed quickly. You can chose to
install it using the Manila Dummy Driver or another backend driver of your
choice.
SDK and OpenStack client
------------------------
If the feature changes the Manila API, please ensure that support these changes
through the SDK bindings and OpenStack client in the
`python-manilaclient repository <https://github.com/openstack/python-manilaclient>`_.
Unit tests
----------
All new changes you implement must be covered by unit tests. We have a Zuul job
that will always check the coverage percentage of the changes and the reviewers
will also be actively looking at it.
.. important::
Please :ref:`run the unit tests locally <running-unit-tests>` to ensure
that your tests are passing before submitting them to the upstream gerrit.
Tempest tests
-------------
All API changes must be tested with negative and positive tests within the
`manila-tempest-plugin repository <https://github.com/openstack/python-manilaclient>`_.
You can use your development environment to
:ref:`run such tests <installing-tempest-tests>`, and ensure your changes
don't break existing functional tests.
Documenting your work
---------------------
:ref:`Documenting your work <documenting_your_work>` is very important. `API
documentation <https://docs.openstack.org/api-ref/shared-file-system/index.html>`_
and make changes where necessary. Also, you must include a release notes with
your change. On devstack you may use `tox -e reno new insert-title-here` to
generate a release note."
Collaborative review sessions
-----------------------------
`Collaborative review sessions <https://www.youtube.com/playlist?list=PLnpzT0InFrqCZB_t2B3IHEYH3_gPFEhck>`_
are a good way to speed up the review process. It is encouraged that you
propose one as early as possible. In the session, you can walk through the key
aspects of the changes you are working on and explain some decisions you took
during the implementation. It has proven to be very valuable to both change
owners and reviewers. To schedule, please bring it up during the Manila
upstream weekly meeting or send an email using the manila tag to OpenStack
discuss mailing list.
Complying to the deadlines
~~~~~~~~~~~~~~~~~~~~~~~~~~
The deadlines are defined in the official
`OpenStack release schedule <https://releases.openstack.org/>`_. The
Manila team also defines some extra project specific deadlines. Below, we have
specified what is expected from you in each of these deadlines.
Manila spec freeze
------------------
All specifications must be merged prior to this date.
Manila feature proposal freeze
------------------------------
New features must be submitted to gerrit before this deadline. The core,
client and tempest changes must be available on gerrit, but it does not mean
the changes should be merged by this deadline.
Manila new driver deadline
--------------------------
By the end of the week all new backend drivers for Manila must be substantially
complete, with unit tests, and passing 3rd party CI. Drivers do not have to
actually merge until feature freeze.
Feature freeze
--------------
The client release follows a different timeline from the core component, so the
client changes must be merged prior to this deadline, as defined in the release
schedule. The client must contain unit and functional tests.
.. important::
API changes must have the documentation updated in the same change as the
entire feature change.
All features and new drivers must be merged by the feature freeze date. In case
you need extra time for the Manila core change, please reach out to the team's
PTL during an upstream weekly meeting, and we can discuss a possible feature
freeze exception, considering if the comments were resolved in a reasonable
amount of time and if the change is already in a good shape to be merged.
Acceptance criteria
~~~~~~~~~~~~~~~~~~~
- Changes were proposed in time and module deadlines were respected
- The code introduced or changed is covered by unit tests
- New functional tests were proposed and reports are positive
- API changes are correct and not introducing backwards compatible changes
- API changes are documented
Additional tips
~~~~~~~~~~~~~~~
- Remember to join the upstream meetings often
- Make sure to use the :ref:`commit message tags <commit_message_tags>` in your
changes.
- Submit the changes upstream as early as possible.
- Remember to run pep8, unit tests and coverage locally before you submit your
changes to gerrit.
- Ensure you keep a review discipline. The best way to have reviewers
looking at your change is to also provide reviews to other people's changes.

2
doc/source/contributor/tempest_tests.rst
View File

@ -1,3 +1,5 @@
.. _installing-tempest-tests:
Tempest Tests
=============

2
doc/source/contributor/unit_tests.rst
View File

@ -1,3 +1,5 @@
.. _running-unit-tests:
Unit Tests
==========