How to work with blueprints without losing your mind
This last week was pretty tough for all OpenStack contributors. In a few days we’re reaching the last milestone of Grizzly series and all the community has been working really hard to make this version as good as the previous ones.
Beside fixing known bugs that solve problems, improve the usability and user experience, the main objective when launching a new version is to add functionality.
And today’s post is precisely about that last thing.
What is a blueprint?
A blueprint is a simple specification that describes an idea, such as a new feature or process, and tracks data to show its implementation status and who’s involved.
They are used to organize and maintain a complete record about the implementation of new features since they provide a way to manage release series in an ordered way, from the first ideas to implementation.
With minimum effort you can create a roadmap that encourages contributions and target the best ideas for future releases.
Five W (and H) to work with blueprints
Working with blueprints!
Because we all want new features :)
Anyone who feels that there is a feature that should be added and want to contribute.
Anytime within the development cycle.
OpenStack uses Launchpad as a collaborative development platform and every project has its own page. According the project you are working, you will have to access to https://blueprints.launchpad.net/-projectname-. E.g. https://blueprints.launchpad.net/horizon.
A name and a description will be needed for the new feature to be carried out. The more concise the description, the better… if necessary a link with more details can be added.
When that is ready, you proceed to set who will be the approver – the project’s Project Team Leader (PTL) -, who will be assigned for development, which is the series goal and when you think it’s going to be ready for merging.
The development designee can be setted later, and anyone can volunteer to do it.
From there, the PTL approves the proposal, assigns it to the series and sets a priority for it.
In that moment the development designee may begin implementing and making sure to keep the blueprint entry up to date. After much work and with some luck, the blueprint will be merged into the target series.
Case study: Tenant Deletion Workflow
As part of the application process for the OPW I had to point out which task I was going to work during the internship. Or at least, a good part of it.
With Julie’s (jpich) help I could find a blueprint that fits my experience as a developer and the time frame I got.
This blueprint, named Tenant Deletion Workflow, aims to implement the tenants removal from Horizon ensuring that no service remains inaccessible, consuming resources and making the system prone to errors.
If you are developers you will be able to appreciate how complicated it can be to remove an entity, even more if that entity involves lots of variables like in this case VMs instances, volumes, object containers, networks and users – just to mention a few -. One wrong move can cause the user to lose data, or leave the system in an unstable state. Anyway… You must be very careful when deleting things!
When I saw what that blueprint was about I felt like when you’re assembling a huge jigsaw puzzle. Where should I begin?
The first thing to do when embarking on a project that you know, or presage, will give you a lot of work is to investigate the context.
Analyze how is its state before and after performing an action is very important to understand what work must be done and avoid making mistakes.
In my case I had to get involved with the project from scratch, so it took longer than usual. I went from API to API, writing down those resources that were directly related to the tenants. From that, I plunged into the official documentation to understand better its functionality.
I also had the support of many contributors who passed by and left their suggestions on the whiteboard, giving me great ideas and helping me to learn more about the environment.
The result of this was a complete summary of what should be considered during the implementation. You can see more details about this at the blueprint’s whiteboard.
The information that could be obtained during the research stage will serve as a starting point, but it is always convenient to organize it and divide the progress in small steps. Divide et impera, a thumb rule that developers learn and then apply to every area of our life.
I decided to split the work by services – Nova, Swift, Glance, Keystone, Neutron and Cinder -, meeting all those matters I could glimpse during the research. In addition, I separated the implementation in two versions: V1 is a simple implementation that only performs a complete clean up and V2 adds the possibility for the user to decide what to do with each service.
Since Horizon is a user interface, I also had to deal with a mockup of how my implementation was going to look. With an excellent interaction designer help I managed to make a first version of this interface.
Following the established goals you will have to get involved with the code and start building the feature. Create a new branch for your work and name it bp/-blueprint-name-. For this particular case,
git checkout -b bp/tenant-deletion.
It’s important to implement, document and test in every step to avoid getting a monster code impossible to debug.
It’s also essential to maintain the style and neatness of the code, take your time to ensure this point. In these projects there are a lot of developers working and it’s truly important to keep the readability and comprehensibility of it.
Think about all the research work you had to do before starting to implement and write the code just as you would have liked to read it.
Now, consider all the tasks you have to perform in this stage and estimate the time that you are going to allocate to it. Ready? Ok, now add at least one more week.
In the implementation stage is very easy to encounter blockers that delays your work more than expected. Also, some tasks you thought were simple may become more complicated.
This is something I didn’t considered when I started to implement this blueprint, so unfortunately I wasn’t able to reach the G3 release :( Next goal? H1!
Once completed the implementation and obtained the desired result, you should ensure that the new feature doesn’t affect other services.
If you kept the order this stage should be relatively quick, and hopefully, require very few changes.
Wait for the reviews
Whenever you are ready you will have to upload your work to Gerrit, as you do with bugs, with
git commit -a and then
Once in there, other developers will test the new implementation and will be able to provide suggestions and ideas to further improve the work done.
Ended this process, a core developer will approve the change and you will have achieved your first major contribution to the project.
In this post I included the normal workflow for the creation and implementation of a new feature in a project. You can find more detailed information on certain points I mentioned in the following sources.
- Ballistic Release Cycles: Tracking the Trajectory of OpenStack Milestones – Awesome analysis about the OpenStack development cycle. I inspired my own G3 Release Cycle graphic considering his research.
- OpenStack Release Cycle
- OpenStack Branch Model
- Grizzly Release Schedule
- Gerrit Workflow
- Tenant Deletion Workflow