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. 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.
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 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 pre-defined 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 and follow its guidelines. If you are working on a smaller feature, you may submit a “lite spec”. Please follow this example.
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. 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 Manila API contributor docs.
Development environment¶
So you have worked on your changes and would like to test them? 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.
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 run the unit tests locally 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. You can use your development environment to run such tests, and ensure your changes don’t break existing functional tests.
Documenting your work¶
Documenting your work is very important. API documentation 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 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. 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 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.
