diff --git a/doc/source/how_to_get_involved.rst b/doc/source/how_to_get_involved.rst index 9fa839bec0f3..bc07cf60435a 100644 --- a/doc/source/how_to_get_involved.rst +++ b/doc/source/how_to_get_involved.rst @@ -11,32 +11,359 @@ License for the specific language governing permissions and limitations under the License. +.. _getting_involved: + ===================================== How to get (more) involved with Nova ===================================== -So you want to get more involved with Nova. Welcome! +So you want to get more involved with Nova? Or you are new to Nova and +wondering where to start? +We are working on building easy ways for you to get help and ideas on +how to learn more about Nova and how the Nova community works. -New to OpenStack? -================== +Any questions, please ask! If you are unsure who to ask, then please +contact the `Mentoring Czar`__. -If you are new to OpenStack, please read the general guides on how you can -get more involved with OpenStack: +__ `Nova People`_ -* http://www.openstack.org/assets/welcome-guide/OpenStackWelcomeGuide.pdf -* https://wiki.openstack.org/wiki/How_To_Contribute -* http://www.openstack.org/community/ +How do I get started? +===================== -New to Nova? -============ +There are quite a few global docs on this: -So you are new to Nova. We are currently working on some docs so its easy -to get more involved. Please see the drafts that are available here: +- http://www.openstack.org/assets/welcome-guide/OpenStackWelcomeGuide.pdf +- https://wiki.openstack.org/wiki/How_To_Contribute +- http://www.openstack.org/community/ + +There is more general info, non Nova specific info here: + +- https://wiki.openstack.org/wiki/Mentors +- https://wiki.openstack.org/wiki/OpenStack_Upstream_Training + +What should I work on? +~~~~~~~~~~~~~~~~~~~~~~ + +So you are starting out your Nova journey, where is a good place to +start? + +Bugs are a great way to cut your Nova teeth: +https://bugs.launchpad.net/nova/+bugs?field.tag=low-hanging-fruit + +Also, we guess that you probably want to understand how Nova works +before changing anything ? Good news, we have a solution for you! Code +reviews are usually the best way for ramping up on a project and get and +compare feedback on what's bad or what's cool. For that, you can help +us. We have a list of trivial bugs that are waiting reviews : +https://etherpad.openstack.org/p/mitaka-nova-priorities-tracking L56 and +below + +We also have a list of low hanging fruit work available: +https://etherpad.openstack.org/p/nova-low-hanging-fruit + +How do I get my feature in? +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The best way of getting your feature in is... well it depends. + +First concentrate on solving your problem and/or use case, don't fixate +on getting the code you have working merged. Its likely things will need +significant re-work after you discuss how your needs match up with all +the existing ways Nova is currently being used. The good news, is this +process should leave you with a feature thats more flexible and doesn't +lock you into your current way of thinking. + +A key part of getting code merged, is helping with reviewing other +people's code. Great reviews of others code will help free up more core +reviewer time to look at your own patches. In addition, you will +understand how the review is thinking when they review your code. + +Also, work out if any on going efforts are blocking your feature and +helping out speeding those up. The spec review process should help with +this effort. + +For more details on our process, please see: :ref:`process`. + +What is expected of a good contributor? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +TODO - need more info on this + +Top Tips for working with the Nova community +============================================ + +Here are some top tips around engaging with the Nova community: + +- IRC + + - we talk a lot in #openstack-nova + - do ask us questions in there, and we will try to help you + - not sure about asking questions? feel free to listen in around + other people's questions + - we recommend you setup an IRC bouncer: + https://wiki.openstack.org/wiki/IRC + +- Email + + - Use the [nova] tag in the mailing lists + - Filtering on [nova] and [all] can help tame the list + +- Be Open + + - i.e. don't review your teams code in private, do it publicly in + gerrit + - i.e. be ready to talk about openly about problems you are having, + not "theoretical" issues + - that way you can start to gain the trust of the wider community + +- Got a problem? Please ask! + + - Please raise any problems and ask questions early + - we want to help you before you are frustrated or annoyed + - unsure who to ask? Just ask in IRC, or check out the list of `Nova + people`_. + +- Talk about problems first, then solutions + + - Nova is a big project. At first, it can be hard to see the big + picture + - Don't think about "merging your patch", instead think about + "solving your problem" + - conversations are more productive that way + +- Its not the decision thats important, it's the reason behind it thats + important + + - Don't like the way the community is going? + - Please ask why we ware going that way, and please engage with the + debate + - If you don't, we are unable to learn from what you have to offer + +- No one will decide, this is stuck, who can help me? + + - it's rare, but it happens + - it's the `Nova PTL`__'s job to help you + - ...but if you don't ask, it's hard for them to help you + +__ `Nova People`_ + +Process +======= + +It can feel like you are faced with a wall of process. We are a big +community, to make sure the right communication happens, we do use a +minimal amount of process. + +If you find something that doesn't make sense, please: + +- ask questions to find out \*why\* it happens +- if you know of a better way to do it, please speak up +- one "better way" might be to remove the process if it no longer helps + +To learn more about Nova's process, please read :ref:`process`. + +Why bother with any process? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Why is it worth creating a bug or blueprint to track your code review? +This may seem like silly process, but there is usually a good reason +behind it. + +We have lots of code to review, and we have tools to try and get to +really important code reviews first. If yours is really important, but +not picked up by our tools, it's possible you just get lost in the bottom +of a big queue. + +If you have a bug fix, you have done loads of work to identify the +issue, and test out your fix, and submit it. By adding a bug report, you +are making it easier for other folks who hit the same problem to find +your work, possibly saving them the hours of pain you went through. With +any luck that gives all those people the time to fix different bugs, all +that might have affected you, if you had not given them the time go fix +it. + +Its similar with blueprints. You have worked out how to scratch your +itch, lets tell others about that great new feature you have added, so +they can use that. Also, it stops someone with a similar idea going +through all the pain of creating a feature only to find you already have +that feature ready and up for review, or merged into the latest release. + +Hopefully this gives you an idea why we have applied a small layer of +process to what we are doing. Having said all this, we need to unlearn +old habits to move forward, there may be better ways to do things, and +we are open to trying them. Please help be part of the solution. + +.. _why_plus1: + +Why do code reviews if I am not in nova-core? +============================================= + +Code reviews are the life blood of the Nova developer community. + +There is a good discussion on how you do good reviews, and how anyone +can be a reviewer: +http://docs.openstack.org/infra/manual/developers.html#peer-review + +In the draft process guide, I discuss how doing reviews can help get +your code merged faster: :ref:`process`. + +Lets look at some of the top reasons why participating with code reviews +really helps you: + +- Doing more reviews, and seeing what other reviewers notice, will help + you better understand what is expected of code that gets merged into + master +- Having more non-core people do great reviews, leaves less review work + for the core reviewers to do, so we are able get more code merged +- Empathy is one of the keys to a happy community. If you are used to + doing code reviews, you will better understand the comments you get + when people review your code. As you do more code reviews, and see + what others notice, you will get a better idea of what people are + looking for when then apply a +2 to your code. +- TODO - needs more detail + +What are the most useful types of code review comments? Well here are a +few to the top ones: + +- Fundamental flaws are the biggest thing to spot. Does the patch break + a whole set of existing users, or an existing feature? +- Consistency of behaviour is really important. Does this bit of code + do things differently to where similar things happen else where in + Nova? +- Is the code easy to maintain, well tested and easy to read? Code is + read order of magnitude times more than it is written, so optimise + for the reader of the code, not the writer. +- TODO - what others should go here? + +Let's look at some problems people hit when starting out doing code +reviews: + +- My +1 doesn't mean anything, why should I bother? + + - So your +1 really does help. Some really useful -1 votes that lead + to a +1 vote helps get code into a position + +- When to use -1 vs 0 vs +1 + + - Please see the guidelines here: + http://docs.openstack.org/infra/manual/developers.html#peer-review + +- I have already reviewed this code internally, no point in adding a +1 + externally? + + - Please talk to your company about doing all code reviews in the + public, that is a much better way to get involved. showing how the + code has evolved upstream, is much better than trying to 'perfect' + code internally, before uploading for public review. You can use + Draft mode, and mark things as WIP if you prefer, but please do + the reviews upstream. + +- Where do I start? What should I review? + + - There are various tools, but a good place to start is: + https://etherpad.openstack.org/p/ -nova-priorities-tracking + - Depending on the time in the cycle, it's worth looking at + NeedsCodeReview blueprints: + https://blueprints.launchpad.net/nova/ + - Maybe take a look at things you want to see merged, bug fixes and + features, or little code fixes + - Look for things that have been waiting a long time for a review: + http://5885fef486164bb8596d-41634d3e64ee11f37e8658ed1b4d12ec.r44.cf3.rackcdn.com/nova-openreviews.html + - If you get through the above lists, try other tools, such as: + http://status.openstack.org/reviews + +- TODO - I think there is more to add here + +How to do great code reviews? +============================= + +http://docs.openstack.org/infra/manual/developers.html#peer-review + +For more tips, please see: `Why do code reviews if I am not in nova-core?`_ + +How do I become nova-core? +========================== + +You don't have to be nova-core to be a valued member of the Nova +community. There are many, many ways you can help. Every quality review +that helps someone get their patch closer to being ready to merge helps +everyone get their code merged faster. + +The first step to becoming nova-core is learning how to be an active +member of the Nova community, including learning how to do great code +reviews. For more details see: +https://wiki.openstack.org/wiki/Nova/CoreTeam#Membership_Expectations + +If you feel like you have the time to commit to all the nova-core +membership expectations, reach out to the Nova PTL who will be +able to find you an existing member of nova-core to help mentor you. If +all goes well, and you seem like a good candidate, your mentor will +contact the rest of the nova-core team to ask them to start looking at +your reviews, so they are able to vote for you, if you get nominated for +join nova-core. + +We encourage all mentoring, where possible, to occur on #openstack-nova +so everyone can learn and benefit from your discussions. + +The above mentoring is available to every one who wants to learn how to +better code reviews, even if you don't ever want to commit to becoming +nova-core. If you already have a mentor, that's great, the process is +only there for folks who are still trying to find a mentor. Being +admitted to the mentoring program no way guarantees you will become a +member of nova-core eventually, it's here to help you improve, and help +you have the sort of involvement and conversations that can lead to +becoming a member of nova-core. + +How to do great nova-spec reviews? +================================== + +http://specs.openstack.org/openstack/nova-specs/specs/mitaka/template.html + +http://docs.openstack.org/developer/nova/devref/kilo.blueprints.html#when-is-a-blueprint-needed + +Spec reviews are always a step ahead of the normal code reviews. Follow +the above links for some great information on specs/reviews. + +The following could be some important tips: + +1. The specs are published as html documents. Ensure that the author has +a proper render of the same via the .rst file. + +2. More often than not, it's important to know that there are no +overlaps across multiple specs. + +3. Ensure that a proper dependency of the spec is identified. For +example - a user desired feature that requires a proper base enablement +should be a dependent spec. + +4. Ask for clarity on changes that appear ambiguous to you. + +5. Every release nova gets a huge set of spec proposals and that's a +huge task for the limited set of nova cores to complete. Helping the +cores with additional reviews is always a great thing. + +How to do great bug triage? +=========================== + +https://wiki.openstack.org/wiki/Nova/BugTriage + +More details coming soon... + +How to step up into a project leadership role? +============================================== + +There are many ways to help lead the Nova project: * Mentoring efforts, and getting started tips: https://wiki.openstack.org/wiki/Nova/Mentoring * Info on process, with a focus on how you can go from an idea to getting code merged Nova: https://wiki.openstack.org/wiki/Nova/Mitaka_Release_Schedule +* Consider leading an existing `Nova subteam`_ or forming a new one. +* Consider becoming a `Bug tag owner`_. +* Contact the PTL about becoming a Czar `Nova People`_. +.. _`Nova people`: https://wiki.openstack.org/wiki/Nova#People +.. _`Nova subteam`: https://wiki.openstack.org/wiki/Nova#Nova_subteams +.. _`Bug tag owner`: https://wiki.openstack.org/wiki/Nova/BugTriage#Step_2:_Triage_Tagged_Bugs diff --git a/doc/source/image_src/Nova_spec_process.graphml b/doc/source/image_src/Nova_spec_process.graphml new file mode 100644 index 000000000000..988aaab4877a --- /dev/null +++ b/doc/source/image_src/Nova_spec_process.graphml @@ -0,0 +1,738 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + API Cell + + + + + + + + + + Folder 1 + + + + + + + + + + + + + + + + + nova-cells + + + + + + + + + + + + + + + + + nova-cells + + + + + + + + + + + + + + + + + rabbit + + + + + + + + + + + + + + + + + cell slots + + + + + + + + + + + + + + + + + + + + + cell slots + + + + + + + + + + + + + + + + + + + + + nova-api + + + + + + + + + + + + + + + + + + + + + + child cell + + + + + + + + + + Folder 2 + + + + + + + + + + + + + + + + + rabbit + + + + + + + + + + + + + + + + + nova-scheduler + + + + + + + + + + + + + + + + + mysql - hoststate + + + + + + + + + + + + + + + + + + + + + hoststate + + + + + + + + + + + + + + + + + + + + + nova-cells + + + + + + + + + + + + + + + + + nova-compute + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + <?xml version="1.0" encoding="utf-8"?> +<svg version="1.1" + xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" + x="0px" y="0px" width="40px" height="48px" viewBox="0 0 40 48" enable-background="new 0 0 40 48" xml:space="preserve"> +<defs> +</defs> +<linearGradient id="SVGID_1_" gradientUnits="userSpaceOnUse" x1="370.2002" y1="655.0938" x2="409.4502" y2="655.0938" gradientTransform="matrix(1 0 0 1 -370.2002 -614.5742)"> + <stop offset="0" style="stop-color:#4D4D4D"/> + <stop offset="0.0558" style="stop-color:#5F5F5F"/> + <stop offset="0.2103" style="stop-color:#8D8D8D"/> + <stop offset="0.3479" style="stop-color:#AEAEAE"/> + <stop offset="0.4623" style="stop-color:#C2C2C2"/> + <stop offset="0.5394" style="stop-color:#C9C9C9"/> + <stop offset="0.6247" style="stop-color:#C5C5C5"/> + <stop offset="0.7072" style="stop-color:#BABABA"/> + <stop offset="0.7885" style="stop-color:#A6A6A6"/> + <stop offset="0.869" style="stop-color:#8B8B8B"/> + <stop offset="0.9484" style="stop-color:#686868"/> + <stop offset="1" style="stop-color:#4D4D4D"/> +</linearGradient> +<path fill="url(#SVGID_1_)" d="M19.625,37.613C8.787,37.613,0,35.738,0,33.425v10c0,2.313,8.787,4.188,19.625,4.188 + c10.839,0,19.625-1.875,19.625-4.188v-10C39.25,35.738,30.464,37.613,19.625,37.613z"/> +<linearGradient id="SVGID_2_" gradientUnits="userSpaceOnUse" x1="370.2002" y1="649.0938" x2="409.4502" y2="649.0938" gradientTransform="matrix(1 0 0 1 -370.2002 -614.5742)"> + <stop offset="0" style="stop-color:#B3B3B3"/> + <stop offset="0.0171" style="stop-color:#B6B6B6"/> + <stop offset="0.235" style="stop-color:#D7D7D7"/> + <stop offset="0.4168" style="stop-color:#EBEBEB"/> + <stop offset="0.5394" style="stop-color:#F2F2F2"/> + <stop offset="0.6579" style="stop-color:#EEEEEE"/> + <stop offset="0.7724" style="stop-color:#E3E3E3"/> + <stop offset="0.8853" style="stop-color:#CFCFCF"/> + <stop offset="0.9965" style="stop-color:#B4B4B4"/> + <stop offset="1" style="stop-color:#B3B3B3"/> +</linearGradient> +<path fill="url(#SVGID_2_)" d="M19.625,37.613c10.839,0,19.625-1.875,19.625-4.188l-1.229-2c0,2.168-8.235,3.927-18.396,3.927 + c-9.481,0-17.396-1.959-18.396-3.927l-1.229,2C0,35.738,8.787,37.613,19.625,37.613z"/> +<linearGradient id="SVGID_3_" gradientUnits="userSpaceOnUse" x1="371.4297" y1="646" x2="408.2217" y2="646" gradientTransform="matrix(1 0 0 1 -370.2002 -614.5742)"> + <stop offset="0" style="stop-color:#C9C9C9"/> + <stop offset="1" style="stop-color:#808080"/> +</linearGradient> +<ellipse fill="url(#SVGID_3_)" cx="19.625" cy="31.425" rx="18.396" ry="3.926"/> +<linearGradient id="SVGID_4_" gradientUnits="userSpaceOnUse" x1="370.2002" y1="641.0938" x2="409.4502" y2="641.0938" gradientTransform="matrix(1 0 0 1 -370.2002 -614.5742)"> + <stop offset="0" style="stop-color:#4D4D4D"/> + <stop offset="0.0558" style="stop-color:#5F5F5F"/> + <stop offset="0.2103" style="stop-color:#8D8D8D"/> + <stop offset="0.3479" style="stop-color:#AEAEAE"/> + <stop offset="0.4623" style="stop-color:#C2C2C2"/> + <stop offset="0.5394" style="stop-color:#C9C9C9"/> + <stop offset="0.6247" style="stop-color:#C5C5C5"/> + <stop offset="0.7072" style="stop-color:#BABABA"/> + <stop offset="0.7885" style="stop-color:#A6A6A6"/> + <stop offset="0.869" style="stop-color:#8B8B8B"/> + <stop offset="0.9484" style="stop-color:#686868"/> + <stop offset="1" style="stop-color:#4D4D4D"/> +</linearGradient> +<path fill="url(#SVGID_4_)" d="M19.625,23.613C8.787,23.613,0,21.738,0,19.425v10c0,2.313,8.787,4.188,19.625,4.188 + c10.839,0,19.625-1.875,19.625-4.188v-10C39.25,21.738,30.464,23.613,19.625,23.613z"/> +<linearGradient id="SVGID_5_" gradientUnits="userSpaceOnUse" x1="370.2002" y1="635.0938" x2="409.4502" y2="635.0938" gradientTransform="matrix(1 0 0 1 -370.2002 -614.5742)"> + <stop offset="0" style="stop-color:#B3B3B3"/> + <stop offset="0.0171" style="stop-color:#B6B6B6"/> + <stop offset="0.235" style="stop-color:#D7D7D7"/> + <stop offset="0.4168" style="stop-color:#EBEBEB"/> + <stop offset="0.5394" style="stop-color:#F2F2F2"/> + <stop offset="0.6579" style="stop-color:#EEEEEE"/> + <stop offset="0.7724" style="stop-color:#E3E3E3"/> + <stop offset="0.8853" style="stop-color:#CFCFCF"/> + <stop offset="0.9965" style="stop-color:#B4B4B4"/> + <stop offset="1" style="stop-color:#B3B3B3"/> +</linearGradient> +<path fill="url(#SVGID_5_)" d="M19.625,23.613c10.839,0,19.625-1.875,19.625-4.188l-1.229-2c0,2.168-8.235,3.926-18.396,3.926 + c-9.481,0-17.396-1.959-18.396-3.926l-1.229,2C0,21.738,8.787,23.613,19.625,23.613z"/> +<linearGradient id="SVGID_6_" gradientUnits="userSpaceOnUse" x1="371.4297" y1="632" x2="408.2217" y2="632" gradientTransform="matrix(1 0 0 1 -370.2002 -614.5742)"> + <stop offset="0" style="stop-color:#C9C9C9"/> + <stop offset="1" style="stop-color:#808080"/> +</linearGradient> +<ellipse fill="url(#SVGID_6_)" cx="19.625" cy="17.426" rx="18.396" ry="3.926"/> +<linearGradient id="SVGID_7_" gradientUnits="userSpaceOnUse" x1="370.2002" y1="627.5938" x2="409.4502" y2="627.5938" gradientTransform="matrix(1 0 0 1 -370.2002 -614.5742)"> + <stop offset="0" style="stop-color:#4D4D4D"/> + <stop offset="0.0558" style="stop-color:#5F5F5F"/> + <stop offset="0.2103" style="stop-color:#8D8D8D"/> + <stop offset="0.3479" style="stop-color:#AEAEAE"/> + <stop offset="0.4623" style="stop-color:#C2C2C2"/> + <stop offset="0.5394" style="stop-color:#C9C9C9"/> + <stop offset="0.6247" style="stop-color:#C5C5C5"/> + <stop offset="0.7072" style="stop-color:#BABABA"/> + <stop offset="0.7885" style="stop-color:#A6A6A6"/> + <stop offset="0.869" style="stop-color:#8B8B8B"/> + <stop offset="0.9484" style="stop-color:#686868"/> + <stop offset="1" style="stop-color:#4D4D4D"/> +</linearGradient> +<path fill="url(#SVGID_7_)" d="M19.625,10.113C8.787,10.113,0,8.238,0,5.925v10c0,2.313,8.787,4.188,19.625,4.188 + c10.839,0,19.625-1.875,19.625-4.188v-10C39.25,8.238,30.464,10.113,19.625,10.113z"/> +<linearGradient id="SVGID_8_" gradientUnits="userSpaceOnUse" x1="370.2002" y1="621.5938" x2="409.4502" y2="621.5938" gradientTransform="matrix(1 0 0 1 -370.2002 -614.5742)"> + <stop offset="0" style="stop-color:#B3B3B3"/> + <stop offset="0.0171" style="stop-color:#B6B6B6"/> + <stop offset="0.235" style="stop-color:#D7D7D7"/> + <stop offset="0.4168" style="stop-color:#EBEBEB"/> + <stop offset="0.5394" style="stop-color:#F2F2F2"/> + <stop offset="0.6579" style="stop-color:#EEEEEE"/> + <stop offset="0.7724" style="stop-color:#E3E3E3"/> + <stop offset="0.8853" style="stop-color:#CFCFCF"/> + <stop offset="0.9965" style="stop-color:#B4B4B4"/> + <stop offset="1" style="stop-color:#B3B3B3"/> +</linearGradient> +<path fill="url(#SVGID_8_)" d="M19.625,10.113c10.839,0,19.625-1.875,19.625-4.188l-1.229-2c0,2.168-8.235,3.926-18.396,3.926 + c-9.481,0-17.396-1.959-18.396-3.926L0,5.925C0,8.238,8.787,10.113,19.625,10.113z"/> +<linearGradient id="SVGID_9_" gradientUnits="userSpaceOnUse" x1="371.4297" y1="618.5" x2="408.2217" y2="618.5" gradientTransform="matrix(1 0 0 1 -370.2002 -614.5742)"> + <stop offset="0" style="stop-color:#C9C9C9"/> + <stop offset="1" style="stop-color:#808080"/> +</linearGradient> +<ellipse fill="url(#SVGID_9_)" cx="19.625" cy="3.926" rx="18.396" ry="3.926"/> +<path opacity="0.24" fill="#FFFFFF" enable-background="new " d="M31.291,46.792c0,0-4.313,0.578-7.249,0.694 + C20.917,47.613,15,47.613,15,47.613l-2.443-10.279l-0.119-2.283l-1.231-1.842L9.789,23.024l-0.082-0.119L9.3,20.715l-1.45-1.44 + L5.329,8.793c0,0,5.296,0.882,7.234,1.07s8.375,0.25,8.375,0.25l3,9.875l-0.25,1.313l1.063,2.168l2.312,9.644l-0.375,1.875 + l1.627,2.193L31.291,46.792z"/> +</svg> + + <?xml version="1.0" encoding="utf-8"?> +<svg version="1.1" + xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" + x="0px" y="0px" width="41px" height="48px" viewBox="-0.875 -0.887 41 48" enable-background="new -0.875 -0.887 41 48" + xml:space="preserve"> +<defs> +</defs> +<linearGradient id="SVGID_1_" gradientUnits="userSpaceOnUse" x1="642.8008" y1="-979.1445" x2="682.0508" y2="-979.1445" gradientTransform="matrix(1 0 0 -1 -642.8008 -939.4756)"> + <stop offset="0" style="stop-color:#3C89C9"/> + <stop offset="0.1482" style="stop-color:#60A6DD"/> + <stop offset="0.3113" style="stop-color:#81C1F0"/> + <stop offset="0.4476" style="stop-color:#95D1FB"/> + <stop offset="0.5394" style="stop-color:#9CD7FF"/> + <stop offset="0.636" style="stop-color:#98D4FD"/> + <stop offset="0.7293" style="stop-color:#8DCAF6"/> + <stop offset="0.8214" style="stop-color:#79BBEB"/> + <stop offset="0.912" style="stop-color:#5EA5DC"/> + <stop offset="1" style="stop-color:#3C89C9"/> +</linearGradient> +<path fill="url(#SVGID_1_)" d="M19.625,36.763C8.787,36.763,0,34.888,0,32.575v10c0,2.313,8.787,4.188,19.625,4.188 + c10.839,0,19.625-1.875,19.625-4.188v-10C39.25,34.888,30.464,36.763,19.625,36.763z"/> +<linearGradient id="SVGID_2_" gradientUnits="userSpaceOnUse" x1="642.8008" y1="-973.1445" x2="682.0508" y2="-973.1445" gradientTransform="matrix(1 0 0 -1 -642.8008 -939.4756)"> + <stop offset="0" style="stop-color:#9CD7FF"/> + <stop offset="0.0039" style="stop-color:#9DD7FF"/> + <stop offset="0.2273" style="stop-color:#BDE5FF"/> + <stop offset="0.4138" style="stop-color:#D1EEFF"/> + <stop offset="0.5394" style="stop-color:#D9F1FF"/> + <stop offset="0.6155" style="stop-color:#D5EFFE"/> + <stop offset="0.6891" style="stop-color:#C9E7FA"/> + <stop offset="0.7617" style="stop-color:#B6DAF3"/> + <stop offset="0.8337" style="stop-color:#9AC8EA"/> + <stop offset="0.9052" style="stop-color:#77B0DD"/> + <stop offset="0.9754" style="stop-color:#4D94CF"/> + <stop offset="1" style="stop-color:#3C89C9"/> +</linearGradient> +<path fill="url(#SVGID_2_)" d="M19.625,36.763c10.839,0,19.625-1.875,19.625-4.188l-1.229-2c0,2.168-8.235,3.927-18.396,3.927 + c-9.481,0-17.396-1.959-18.396-3.927l-1.229,2C0,34.888,8.787,36.763,19.625,36.763z"/> +<path fill="#3C89C9" d="M19.625,26.468c10.16,0,19.625,2.775,19.625,2.775c-0.375,2.721-5.367,5.438-19.554,5.438 + c-12.125,0-18.467-2.484-19.541-4.918C-0.127,29.125,9.465,26.468,19.625,26.468z"/> +<linearGradient id="SVGID_3_" gradientUnits="userSpaceOnUse" x1="642.8008" y1="-965.6948" x2="682.0508" y2="-965.6948" gradientTransform="matrix(1 0 0 -1 -642.8008 -939.4756)"> + <stop offset="0" style="stop-color:#3C89C9"/> + <stop offset="0.1482" style="stop-color:#60A6DD"/> + <stop offset="0.3113" style="stop-color:#81C1F0"/> + <stop offset="0.4476" style="stop-color:#95D1FB"/> + <stop offset="0.5394" style="stop-color:#9CD7FF"/> + <stop offset="0.636" style="stop-color:#98D4FD"/> + <stop offset="0.7293" style="stop-color:#8DCAF6"/> + <stop offset="0.8214" style="stop-color:#79BBEB"/> + <stop offset="0.912" style="stop-color:#5EA5DC"/> + <stop offset="1" style="stop-color:#3C89C9"/> +</linearGradient> +<path fill="url(#SVGID_3_)" d="M19.625,23.313C8.787,23.313,0,21.438,0,19.125v10c0,2.313,8.787,4.188,19.625,4.188 + c10.839,0,19.625-1.875,19.625-4.188v-10C39.25,21.438,30.464,23.313,19.625,23.313z"/> +<linearGradient id="SVGID_4_" gradientUnits="userSpaceOnUse" x1="642.8008" y1="-959.6948" x2="682.0508" y2="-959.6948" gradientTransform="matrix(1 0 0 -1 -642.8008 -939.4756)"> + <stop offset="0" style="stop-color:#9CD7FF"/> + <stop offset="0.0039" style="stop-color:#9DD7FF"/> + <stop offset="0.2273" style="stop-color:#BDE5FF"/> + <stop offset="0.4138" style="stop-color:#D1EEFF"/> + <stop offset="0.5394" style="stop-color:#D9F1FF"/> + <stop offset="0.6155" style="stop-color:#D5EFFE"/> + <stop offset="0.6891" style="stop-color:#C9E7FA"/> + <stop offset="0.7617" style="stop-color:#B6DAF3"/> + <stop offset="0.8337" style="stop-color:#9AC8EA"/> + <stop offset="0.9052" style="stop-color:#77B0DD"/> + <stop offset="0.9754" style="stop-color:#4D94CF"/> + <stop offset="1" style="stop-color:#3C89C9"/> +</linearGradient> +<path fill="url(#SVGID_4_)" d="M19.625,23.313c10.839,0,19.625-1.875,19.625-4.188l-1.229-2c0,2.168-8.235,3.926-18.396,3.926 + c-9.481,0-17.396-1.959-18.396-3.926l-1.229,2C0,21.438,8.787,23.313,19.625,23.313z"/> +<path fill="#3C89C9" d="M19.476,13.019c10.161,0,19.625,2.775,19.625,2.775c-0.375,2.721-5.367,5.438-19.555,5.438 + c-12.125,0-18.467-2.485-19.541-4.918C-0.277,15.674,9.316,13.019,19.476,13.019z"/> +<linearGradient id="SVGID_5_" gradientUnits="userSpaceOnUse" x1="642.8008" y1="-952.4946" x2="682.0508" y2="-952.4946" gradientTransform="matrix(1 0 0 -1 -642.8008 -939.4756)"> + <stop offset="0" style="stop-color:#3C89C9"/> + <stop offset="0.1482" style="stop-color:#60A6DD"/> + <stop offset="0.3113" style="stop-color:#81C1F0"/> + <stop offset="0.4476" style="stop-color:#95D1FB"/> + <stop offset="0.5394" style="stop-color:#9CD7FF"/> + <stop offset="0.636" style="stop-color:#98D4FD"/> + <stop offset="0.7293" style="stop-color:#8DCAF6"/> + <stop offset="0.8214" style="stop-color:#79BBEB"/> + <stop offset="0.912" style="stop-color:#5EA5DC"/> + <stop offset="1" style="stop-color:#3C89C9"/> +</linearGradient> +<path fill="url(#SVGID_5_)" d="M19.625,10.113C8.787,10.113,0,8.238,0,5.925v10c0,2.313,8.787,4.188,19.625,4.188 + c10.839,0,19.625-1.875,19.625-4.188v-10C39.25,8.238,30.464,10.113,19.625,10.113z"/> +<linearGradient id="SVGID_6_" gradientUnits="userSpaceOnUse" x1="642.8008" y1="-946.4946" x2="682.0508" y2="-946.4946" gradientTransform="matrix(1 0 0 -1 -642.8008 -939.4756)"> + <stop offset="0" style="stop-color:#9CD7FF"/> + <stop offset="0.0039" style="stop-color:#9DD7FF"/> + <stop offset="0.2273" style="stop-color:#BDE5FF"/> + <stop offset="0.4138" style="stop-color:#D1EEFF"/> + <stop offset="0.5394" style="stop-color:#D9F1FF"/> + <stop offset="0.6155" style="stop-color:#D5EFFE"/> + <stop offset="0.6891" style="stop-color:#C9E7FA"/> + <stop offset="0.7617" style="stop-color:#B6DAF3"/> + <stop offset="0.8337" style="stop-color:#9AC8EA"/> + <stop offset="0.9052" style="stop-color:#77B0DD"/> + <stop offset="0.9754" style="stop-color:#4D94CF"/> + <stop offset="1" style="stop-color:#3C89C9"/> +</linearGradient> +<path fill="url(#SVGID_6_)" d="M19.625,10.113c10.839,0,19.625-1.875,19.625-4.188l-1.229-2c0,2.168-8.235,3.926-18.396,3.926 + c-9.481,0-17.396-1.959-18.396-3.926L0,5.925C0,8.238,8.787,10.113,19.625,10.113z"/> +<linearGradient id="SVGID_7_" gradientUnits="userSpaceOnUse" x1="644.0293" y1="-943.4014" x2="680.8223" y2="-943.4014" gradientTransform="matrix(1 0 0 -1 -642.8008 -939.4756)"> + <stop offset="0" style="stop-color:#9CD7FF"/> + <stop offset="1" style="stop-color:#3C89C9"/> +</linearGradient> +<ellipse fill="url(#SVGID_7_)" cx="19.625" cy="3.926" rx="18.396" ry="3.926"/> +<path opacity="0.24" fill="#FFFFFF" enable-background="new " d="M31.04,45.982c0,0-4.354,0.664-7.29,0.781 + c-3.125,0.125-8.952,0-8.952,0l-2.384-10.292l0.044-2.108l-1.251-1.154L9.789,23.024l-0.082-0.119L9.5,20.529l-1.65-1.254 + L5.329,8.793c0,0,4.213,0.903,7.234,1.07s8.375,0.25,8.375,0.25l3,9.875l-0.25,1.313l1.063,2.168l2.312,9.645l-0.521,1.416 + l1.46,1.834L31.04,45.982z"/> +</svg> + + + + diff --git a/doc/source/images/Nova_spec_process.svg b/doc/source/images/Nova_spec_process.svg new file mode 100644 index 000000000000..7d50b38b02d9 --- /dev/null +++ b/doc/source/images/Nova_spec_process.svg @@ -0,0 +1,340 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + launchpad + + + + + + + + + + create a bug + + + + + + + + + create a blueprint + + + + + + + + + create a blueprint + + + + + + + End states + + + + + + + + + + out of scope + + + + + + + + + code merged + + + + + + bug fix? + + + + + + + + + + idea + + + + + + REST API change? + + + + + + + + + + submit spec for review + + + + + + a feature? + + + + + + + + + + spec merged + + + + + + + + + blueprint approved for release + + + + + + spec required? + + + + + + + + + + add link on nova meeting agenda + + + + + + + + + blueprint hit by feature freeze + + + + + + + + + re-submit for next release + + + + + + + + + blueprint unapproved + + + + + + + + + apply procedural -2 + + + + + + + + + upload code for review + + + + + + + + + remove procedural -2 + + + + + + + + + review blueprint in nova meeting + + + + + + + + + no + + + yes + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/source/index.rst b/doc/source/index.rst index af8fa4070a8d..e46843ad75e7 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -104,6 +104,7 @@ actually does, and why. :maxdepth: 1 how_to_get_involved + process architecture project_scope development.environment @@ -229,4 +230,3 @@ Indices and tables * :ref:`genindex` * :ref:`modindex` * :ref:`search` - diff --git a/doc/source/process.rst b/doc/source/process.rst index 6378ab675830..650aa8341f6b 100644 --- a/doc/source/process.rst +++ b/doc/source/process.rst @@ -11,17 +11,19 @@ License for the specific language governing permissions and limitations under the License. -===================== -Development Process -===================== +.. _process: -Nova is always evolving its processes, but its import to explain why we have -this process, so we all work to ensure the interactions we need to happen do -happen. The process we have should always be there to make it easier for good -communication between all members of our community. +================= +Nova team process +================= + +Nova is always evolving its processes, but it's important to explain why we +have them: so that we can all work to ensure the interactions we need to +happen do happen. The process we have should always be there to make good +communication between all members of our community easier. OpenStack Wide Patterns -======================== +======================= Nova follows most of the generally adopted norms for OpenStack projects. You can get more details here: @@ -29,10 +31,978 @@ You can get more details here: * http://docs.openstack.org/infra/manual/developers.html * http://git.openstack.org/cgit/openstack/project-team-guide -Nova Process -============= +If you are new to Nova, please read this first: :ref:`getting_involved`. -This documentation is still a work in progress. -There is some draft information available on the wiki: +Dates overview +============== + +For Mitaka, please see: +https://wiki.openstack.org/wiki/Nova/Mitaka_Release_Schedule + +For Liberty, please see: +https://wiki.openstack.org/wiki/Nova/Liberty_Release_Schedule + +Feature Freeze +~~~~~~~~~~~~~~ + +This effort is primarily to help the horizontal teams help prepare their +items for release, while at the same time giving developers time to +focus on stabilising what is currently in master, and encouraging users +and packages to perform tests (automated, and manual) on the release, to +spot any major bugs. + +As such we have the following processes: + +- https://wiki.openstack.org/wiki/FeatureProposalFreeze + + - make sure all code is up for review + - so we can optimise for completed features, not lots of half + completed features + +- https://wiki.openstack.org/wiki/FeatureFreeze + + - make sure all feature code is merged + +- https://wiki.openstack.org/wiki/StringFreeze + + - give translators time to translate all our strings + - Note: debug logs are no longer translated + +- https://wiki.openstack.org/wiki/DepFreeze + + - time to co-ordinate the final list of deps, and give packagers + time to package them + - generally it is also quite destabilising to take upgrades (beyond + bug fixes) this late + +We align with this in Nova and the dates for this release are stated +above. + +As with all processes here, there are exceptions. But the exceptions at +this stage need to be discussed with the horizontal teams that might be +affected by changes beyond this point, and as such are discussed with +one of the OpenStack release managers. + +Spec and Blueprint Approval Freeze +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is a (mostly) Nova specific process. + +Why do we have a Spec Freeze: + +- specs take a long time to review, keeping it open distracts from code + reviews +- keeping them "open" and being slow at reviewing the specs (or just + ignoring them) really annoys the spec submitters +- we generally have more code submitted that we can review, this time + bounding is a way to limit the number of submissions + +By the freeze date, we expect this to also be the complete list of +approved blueprints for liberty: +https://blueprints.launchpad.net/nova/liberty + +The date listed above is when we expect all specifications for Liberty +to be merged and displayed here: +http://specs.openstack.org/openstack/nova-specs/specs/liberty/approved/ + +New in Liberty, we will keep the backlog open for submission at all +times. Note: the focus is on accepting and agreeing problem statements +as being in scope, rather than queueing up work items for the next +release. We are still working on a new lightweight process to get our of +the backlog and approved for a particular release. For more details on +backlog specs, please see: +http://specs.openstack.org/openstack/nova-specs/specs/backlog/index.html + +Also new in Liberty, we will allow people to submit Mitaka specs from +liberty-2 (rather than liberty-3 as normal). + +There can be exceptions, usually it's an urgent feature request that +comes up after the initial deadline. These will generally be discussed +at the weekly Nova meeting, by adding the spec or blueprint to discuss +in the appropriate place in the meeting agenda here (ideally make +yourself available to discuss the blueprint, or alternatively make your +case on the ML before the meeting): +https://wiki.openstack.org/wiki/Meetings/Nova + +Non-priority Feature Freeze +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is a Nova specific process. + +This only applies to low priority blueprints in this list: +https://blueprints.launchpad.net/nova/liberty + +We currently have a very finite amount of review bandwidth. In order to +make code review time for the agreed community wide priorities, we have +to not do some other things. To this end, we are reserving liberty-3 for +priority features and bug fixes. As such, we intend not to merge any +non-priority things during liberty-3, so around liberty-2 is the +"Feature Freeze" for blueprints that are not a priority for liberty. + +For liberty, we are not aligning the Non-priority Feature Freeze with +the tagging of liberty-2. That means the liberty-2 tag will not include +some features that merge later in the week. This means, we only require +the code to be approved before the end of July 30th, we don't require it +to be merged by that date. This should help stop any gate issues +disrupting our ability to merge all the code that we have managed to get +reviewed in time. Ideally all code should be merged by the end of July +31st, but the state of the gate will determine how possible that is. + +You can see the list of priorities for each release: +http://specs.openstack.org/openstack/nova-specs/#priorities + +For things that are very close to merging, it's possible it might get an +exception for one week after the freeze date, given the patches get +enough +2s from the core team to get the code merged. But we expect this +list to be zero, if everything goes to plan (no massive gate failures, +etc). For details, process see: +http://lists.openstack.org/pipermail/openstack-dev/2015-July/070920.html + +Exception process: + +- Please add request in here: + https://etherpad.openstack.org/p/liberty-nova-non-priority-feature-freeze + (ideally with core reviewers to sponsor your patch, normally the + folks who have already viewed those patches) +- make sure you make your request before the end of Wednesday 5th + August +- nova-drivers will meet to decide what gets an exception (just like + they did last release: + http://lists.openstack.org/pipermail/openstack-dev/2015-February/056208.html) +- an initial list of exceptions (probably just a PTL compiled list at + that point) will be available for discussion during the Nova meeting + on Thursday 6th August +- the aim is to merge the code for all exceptions by the end of Monday + 10th August + +Alternatives: + +- It was hoped to make this a continuous process using "slots" to + control what gets reviewed, but this was rejected by the community + when it was last discussed. There is hope this can be resurrected to + avoid the "lumpy" nature of this process. +- Currently the runways/kanban ideas are blocked on us adopting + something like phabricator that could support such workflows + +String Freeze +~~~~~~~~~~~~~ + +NOTE: this is still a provisional idea + +There are general guidelines here: +https://wiki.openstack.org/wiki/StringFreeze + +But below is an experiment for Nova during liberty, to trial a new +process. There are four views onto this process. + +First, the user point of view: + +- Would like to see untranslated strings, rather than hiding + error/info/warn log messages as debug + +Second, the translators: + +- Translators will start translation without string freeze, just after + feature freeze. +- Then we have a strict string freeze date (around RC1 date) +- After at least 10 days to finish up the translations before the final + release + +Third, the docs team: + +- Config string updates often mean there is a DocImpact and docs need + updating +- best to avoid those during feature freeze, where possible + +Fourth, the developer point of view: + +- Add any translated strings before Feature Freeze +- Post Feature Freeze, allow string changes where an untranslated + string is better than no string + + - i.e. allow new log message strings, until the hard freeze + +- Post Feature Freeze, have a soft string freeze, try not to change + existing strings, where possible + + - Note: moving a string and re-using a existing string is fine, as + the tooling deals with that automatically + +- Post Hard String Freeze, there should be no extra strings to + translate + + - Assume any added strings will not be translated + - Send email about the string freeze exception in this case only, + but there should be zero of these + +So, what has changed from https://wiki.openstack.org/wiki/StringFreeze, +well: + +- no need to block new strings until much later in the cycle + + - should stop the need to rework bug fixes to remove useful log + messages + +- instead, just accept the idea of untranslated strings being better + than no strings in those cases + +So for Liberty, 21st September, so we will call 21st September the hard +freeze date, as we expect RC1 to be cut sometime after 21st September. +Note the date is fixed, it's not aligned with the cutting of RC1. + +This means we must cut another tarball (RC2 or higher) at some point +after 5th October to include new translations, even if there are no more +bug fixes, to give time before the final release on 13th-16th October. + +How do I get my code merged? +============================ + +OK, so you are new to Nova, and you have been given a feature to +implement. How do I make that happen? + +You can get most of your questions answered here: + +- http://docs.openstack.org/infra/manual/developers.html + +But let's put a Nova specific twist on things... + +Overview +~~~~~~~~ + +.. image:: ./images/Nova_spec_process.svg + :alt: Flow chart showing the Nova bug/feature process + +Where do you track bugs? +~~~~~~~~~~~~~~~~~~~~~~~~ + +We track bugs here: + +- http://bugs.launchpad.net/nova + +If you fix an issue, please raise a bug so others who spot that issue +can find the fix you kindly created for them. + +Also before submitting your patch it's worth checking to see if someone +has already fixed it for you (Launchpad helps you with that, at little, +when you create the bug report). + +When do I need a blueprint vs a spec? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For more details see: + +- http://docs.openstack.org/developer/nova/devref/kilo.blueprints.html#when-is-a-blueprint-needed + +To understand this question, we need to understand why blueprints and +specs are useful. + +But here is the rough idea: + +- if it needs a spec, it will need a blueprint. +- if it's an API change, it needs a spec. +- if it's a single small patch that touches a small amount of code, + with limited deployer and doc impact, it probably doesn't need a + spec. + +If you are unsure, please ask johnthetubaguy on IRC, or one of the other +nova-drivers. + +How do I get my blueprint approved? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +So you need your blueprint approved? Here is how: + +- if you don't need a spec, please add a link to your blueprint to the + agenda for the next nova meeting: + https://wiki.openstack.org/wiki/Meetings/Nova + + - be sure your blueprint description has enough context for the + review in that meeting. + - As of Mitaka, this list is stored in an etherpad: + https://etherpad.openstack.org/p/mitaka-nova-spec-review-tracking + +- if you need a spec, then please submit a nova-spec for review, see: + http://docs.openstack.org/infra/manual/developers.html + +Got any more questions? Contact johnthetubaguy or one of the other +nova-specs-core who are awake at the same time as you. IRC is best as +you will often get an immediate response, if they are too busy send +him/her an email. + +How do I get a procedural -2 removed from my patch? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When feature freeze hits, any patches for blueprints that are still in review +get a procedural -2 to stop them merging. In Nova a blueprint is only approved +for a single release. To have the -2 removed, you need to get the blueprint +approved for the current release (see `How do I get my blueprint approved?`_). + +Why are the reviewers being mean to me? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Code reviews take intense concentration and a lot of time. This tends to +lead to terse responses with very little preamble or nicety. That said, +there's no excuse for being actively rude or mean. OpenStack has a Code +of Conduct (https://www.openstack.org/legal/community-code-of-conduct/) +and if you feel this has been breached please raise the matter +privately. Either with the relevant parties, the PTL or failing those, +the OpenStack Foundation. + +That said, there are many objective reasons for applying a -1 or -2 to a +patch: + +- Firstly and simply, patches must address their intended purpose + successfully. +- Patches must not have negative side-effects like wiping the database + or causing a functional regression. Usually removing anything, + however tiny, requires a deprecation warning be issued for a cycle. +- Code must be maintainable, that is it must adhere to coding standards + and be as readable as possible for an average OpenStack developer + (acknowledging this person is ill-defined). +- Patches must respect the direction of the project, for example they + should not make approved specs substantially more difficult to + implement. +- Release coordinators need the correct process to be followed so scope + can be tracked accurately. Bug fixes require bugs, features require + blueprints and all but the simplest features require specs. If there + is a blueprint, it must be approved for the release/milestone the + patch is attempting to merge into. + +Please particularly bear in mind that a -2 does not mean "never ever" +nor does it mean "your idea is bad and you are dumb". It simply means +"do not merge today". You may need to wait some time, rethink your +approach or even revisit the problem definition but there is almost +always some way forward. The core who applied the -2 should tell you +what you need to do. + +My code review seems stuck, what can I do? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +First and foremost - address any -1s and -2s! The review load on Nova is +high enough that patches with negative reviews often get filtered out +entirely. A few tips: + +- Be precise. Ensure you're not talking at cross purposes. +- Try to understand where the reviewer is coming from. They may have a + very different perspective and/or use-case to you. +- If you don't understand the problem, ask them to explain - this is + common and helpful behaviour. +- Be positive. Everyone's patches have issues, including core + reviewers. No-one cares once the issues are fixed. +- Try not to flip-flop. When two reviewers are pulling you in different + directions, stop pushing code and negotiate the best way forward. +- If the reviewer does not respond to replies left on the patchset, + reach out to them on IRC or email. If they still don't respond, you + can try to ask their colleagues if they're on holiday (or simply + wait). Finally, you can ask for mediation in the Nova meeting by + adding it to the agenda + (https://wiki.openstack.org/wiki/Meetings/Nova). This is also what + you should do if you are unable to negotiate a resolution to an + issue. + +Secondly, Nova is a big project, be aware of the average wait times: +http://russellbryant.net/openstack-stats/nova-openreviews.html + +Eventually you should get some +1s from people working through the +review queue. Expect to get -1s as well. You can ask for reviews within +your company, 1-2 are useful (not more), especially if those reviewers +are known to give good reviews. You can spend some time while you wait +reviewing other people's code - they may reciprocate and you may learn +something (:ref:`Why do code reviews when I'm not core? `). + +If you've waited an appropriate amount of time and you haven't had any ++1s, you can ask on IRC for reviews. Please don't ask for core review +straight away, especially not directly (IRC or email). Core reviewer +time is very valuable and gaining some +1s is a good way to show your +patch meets basic quality standards. + +Once you have a few +1s, be patient. Remember the average wait times. +You can ask for reviews each week in IRC, it helps to ask when cores are +awake. + +Bugs +^^^^ + +It helps to apply correct tracking information. + +- Put "Closes-Bug", "Partial-Bug" or "Related-Bug" in the commit + message tags as necessary. +- If you have to raise a bug in Launchpad first, do it - this helps + someone else find your fix. +- Make sure the bug has the correct priority and tag set: + https://wiki.openstack.org/wiki/Nova/BugTriage#Step_2:_Triage_Tagged_Bugs +- If it's a trivial fix (<100 lines as a rule of thumb), add it to: + https://etherpad.openstack.org/p/liberty-nova-priorities-tracking + +Features +^^^^^^^^ + +Again, it helps to apply correct tracking information. For +blueprint-only features: + +- Put your blueprint in the commit message, EG "blueprint + simple-feature". +- Mark the blueprint as NeedsCodeReview if you are finished. +- Maintain the whiteboard on the blueprint so it's easy to understand + which patches need reviews. +- Use a single topic for all related patches. All patches for one + blueprint should share a topic. + +For blueprint and spec features, do everything for blueprint-only +features and also: + +- If it's a project or subteam priority, add it to: + https://etherpad.openstack.org/p/liberty-nova-priorities-tracking +- Ensure your spec is approved for the current release cycle. + +If your code is a project or subteam priority, the cores interested in +that priority might not mind a ping after it has sat with +1s for a +week. If you abuse this privilege, you'll lose respect. + +If it's not a priority, your blueprint/spec has been approved for the +cycle and you have been patient, you can raise it during the Nova +meeting. The outcome may be that your spec gets unapproved for the +cycle, so that priority items can take focus. If this happens to you, +sorry - it should not have been approved in the first place, Nova team +bit off more than they could chew, it is their mistake not yours. You +can re-propose it for the next cycle. + +If it's not a priority and your spec has not been approved, your code +will not merge this cycle. Please re-propose your spec for the next +cycle. + +Nova Process Mission +==================== + +This section takes a high level look at the guiding principles behind +the Nova process. + +Open +~~~~ + +Our mission is to have: + +- Open Source +- Open Design +- Open Development +- Open Community + +We have to work out how to keep communication open in all areas. We need +to be welcoming and mentor new people, and make it easy for them to +pickup the knowledge they need to get involved with OpenStack. For more +info on Open, please see: https://wiki.openstack.org/wiki/Open + +Interoperable API, supporting a vibrant ecosystem +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +An interoperable API that gives users on-demand access to compute +resources is at the heart of Nova's mission: +http://docs.openstack.org/developer/nova/project_scope.html#mission + +Nova has a vibrant ecosystem of tools built on top of the current Nova +API. All features should be designed to work with all technology +combinations, so the feature can be adopted by our ecosystem. If a new +feature is not adopted by the ecosystem, it will make it hard for your +users to make use of those features, defeating most of the reason to add +the feature in the first place. The microversion system allows users to +isolate themselves + +This is a very different aim to being "pluggable" or wanting to expose +all capabilities to end users. At the same time, it is not just a +"lowest common denominator" set of APIs. It should be discoverable which +features are available, and while no implementation details should leak +to the end users, purely admin concepts may need to understand +technology specific details that back the interoperable and more +abstract concepts that are exposed to the end user. This is a hard goal, +and one area we currently don't do well is isolating image creators from +these technology specific details. + +Smooth Upgrades +~~~~~~~~~~~~~~~ + +As part of our mission for a vibrant ecosystem around our APIs, we want +to make it easy for those deploying Nova to upgrade with minimal impact +to their users. Here is the scope of Nova's upgrade support: + +- upgrade from any commit, to any future commit, within the same major + release +- only support upgrades between N and N+1 major versions, to reduce + technical debt relating to upgrades + +Here are some of the things we require developers to do, to help with +upgrades: + +- when replacing an existing feature or configuration option, make it + clear how to transition to any replacement +- deprecate configuration options and features before removing them + + - i.e. continue to support and test features for at least one + release before they are removed + - this gives time for operator feedback on any removals + +- End User API will always be kept backwards compatible + +Interaction goals +~~~~~~~~~~~~~~~~~ + +When thinking about the importance of process, we should take a look at: +http://agilemanifesto.org + +With that in mind, let's look at how we want different members of the +community to interact. Let's start with looking at issues we have tried +to resolve in the past (currently in no particular order). We must: + +- have a way for everyone to review blueprints and designs, including + allowing for input from operators and all types of users (keep it + open) +- take care to not expand Nova's scope any more than absolutely + necessary +- ensure we get sufficient focus on the core of Nova so that we can + maintain or improve the stability and flexibility of the overall + codebase +- support any API we release approximately for ever. We currently + release every commit, so we're motivate to get the API right first + time +- avoid low priority blueprints slowing work on high priority work, + without blocking those forever +- focus on a consistent experience for our users, rather than ease of + development +- optimise for completed blueprints, rather than more half completed + blueprints, so we get maximum value for our users out of our review + bandwidth +- focus efforts on a subset of patches to allow our core reviewers to + be more productive +- set realistic expectations on what can be reviewed in a particular + cycle, to avoid sitting in an expensive rebase loop +- be aware of users that do not work on the project full time +- be aware of users that are only able to work on the project at + certain times that may not align with the overall community cadence +- discuss designs for non-trivial work before implementing it, to avoid + the expense of late-breaking design issues + +FAQs +==== + +Why bother with all this process? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We are a large community, spread across multiple timezones, working with +several horizontal teams. Good communication is a challenge and the +processes we have are mostly there to try and help fix some +communication challenges. + +If you have a problem with a process, please engage with the community, +discover the reasons behind our current process, and help fix the issues +you are experiencing. + +Why don't you remove old process? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We do! For example, in Liberty we stopped trying to predict the +milestones when a feature will land. + +As we evolve, it is important to unlearn new habits and explore if +things get better if we choose to optimise for a different set of +issues. + +Why are specs useful? +~~~~~~~~~~~~~~~~~~~~~ + +Spec reviews allow anyone to step up and contribute to reviews, just +like with code. Before we used gerrit, it was a very messy review +process, that felt very "closed" to most people involved in that +process. + +As Nova has grown in size, it can be hard to work out how to modify Nova +to meet your needs. Specs are a great way of having that discussion with +the wider Nova community. + +For Nova to be a success, we need to ensure we don't break our existing +users. The spec template helps focus the mind on the impact your change +might have on existing users and gives an opportunity to discuss the +best way to deal with those issues. + +However, there are some pitfalls with the process. Here are some top +tips to avoid them: + +- keep it simple. Shorter, simpler, more decomposed specs are quicker + to review and merge much quicker (just like code patches). +- specs can help with documentation but they are only intended to + document the design discussion rather than document the final code. +- don't add details that are best reviewed in code, it's better to + leave those things for the code review. + +If we have specs, why still have blueprints? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We use specs to record the design agreement, we use blueprints to track +progress on the implementation of the spec. + +Currently, in Nova, specs are only approved for one release, and must be +re-submitted for each release you want to merge the spec, although that +is currently under review. + +Why do we have priorities? +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To be clear, there is no "nova dev team manager", we are an open team of +professional software developers, that all work for a variety of (mostly +competing) companies that collaborate to ensure the Nova project is a +success. + +Over time, a lot of technical debt has accumulated, because there was a +lack of collective ownership to solve those cross-cutting concerns. +Before the Kilo release, it was noted that progress felt much slower, +because we were unable to get appropriate attention on the architectural +evolution of Nova. This was important, partly for major concerns like +upgrades and stability. We agreed it's something we all care about and +it needs to be given priority to ensure that these things get fixed. + +Since Kilo, priorities have been discussed at the summit. This turns in +to a spec review which eventually means we get a list of priorities +here: http://specs.openstack.org/openstack/nova-specs/#priorities + +Allocating our finite review bandwidth to these efforts means we have to +limit the reviews we do on non-priority items. This is mostly why we now +have the non-priority Feature Freeze. For more on this, see below. + +Blocking a priority effort is one of the few widely acceptable reasons +to block someone adding a feature. One of the great advantages of being +more explicit about that relationship is that people can step up to help +review and/or implement the work that is needed to unblock the feature +they want to get landed. This is a key part of being an Open community. + +Why is there a Feature Freeze (and String Freeze) in Nova? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The main reason Nova has a feature freeze is that it gives people +working on docs and translations to sync up with the latest code. +Traditionally this happens at the same time across multiple projects, so +the docs are synced between what used to be called the "integrated +release". + +We also use this time period as an excuse to focus our development +efforts on bug fixes, ideally lower risk bug fixes, and improving test +coverage. + +In theory, with a waterfall hat on, this would be a time for testing and +stabilisation of the product. In Nova we have a much stronger focus on +keeping every commit stable, by making use of extensive continuous +testing. In reality, we frequently see the biggest influx of fixes in +the few weeks after the release, as distributions do final testing of +the released code. + +It is hoped that the work on Feature Classification will lead us to +better understand the levels of testing of different Nova features, so +we will be able to reduce and dependency between Feature Freeze and +regression testing. It is also likely that the move away from +"integrated" releases will help find a more developer friendly approach +to keep the docs and translations in sync. + +Why is there a non-priority Feature Freeze in Nova? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We have already discussed why we have priority features. + +The rate at which code can be merged to Nova is primarily constrained by +the amount of time able to be spent reviewing code. Given this, +earmarking review time for priority items means depriving it from +non-priority items. + +The simplest way to make space for the priority features is to stop +reviewing and merging non-priority features for a whole milestone. The +idea being developers should focus on bug fixes and priority features +during that milestone, rather than working on non-priority features. + +A known limitation of this approach is developer frustration. Many +developers are not being given permission to review code, work on bug +fixes or work on priority features, and so feel very unproductive +upstream. An alternative approach of "slots" or "runways" has been +considered, that uses a kanban style approach to regulate the influx of +work onto the review queue. We are yet to get agreement on a more +balanced approach, so the existing system is being continued to ensure +priority items are more likely to get the attention they require. + +Why do you still use Launchpad? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We are actively looking for an alternative to Launchpad's bugs and +blueprints. + +Originally the idea was to create Storyboard. However the development +has stalled. A more likely front runner is this: +http://phabricator.org/applications/projects/ + +When should I submit my spec? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Ideally we want to get all specs for a release merged before the summit. +For things that we can't get agreement on, we can then discuss those at +the summit. There will always be ideas that come up at the summit and +need to be finalised after the summit. This causes a rush which is best +avoided. + +How can I get my code merged faster? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +So no-one is coming to review your code, how do you speed up that +process? + +Firstly, make sure you are following the above process. If it's a +feature, make sure you have an approved blueprint. If it's a bug, make +sure it is triaged, has its priority set correctly, it has the correct +bug tag and is marked as in progress. If the blueprint has all the code +up for review, change it from Started into NeedsCodeReview so people +know only reviews are blocking you, make sure it hasn't accidentally got +marked as implemented. + +Secondly, if you have a negative review (-1 or -2) and you responded to +that in a comment or uploading a new change with some updates, but that +reviewer hasn't come back for over a week, it's probably a good time to +reach out to the reviewer on IRC (or via email) to see if they could +look again now you have addressed their comments. If you can't get +agreement, and your review gets stuck (i.e. requires mediation), you can +raise your patch during the Nova meeting and we will try to resolve any +disagreement. + +Thirdly, is it in merge conflict with master or are any of the CI tests +failing? Particularly any third-party CI tests that are relevant to the +code you are changing. If you're fixing something that only occasionally +failed before, maybe recheck a few times to prove the tests stay +passing. Without green tests, reviews tend to move on and look at the +other patches that have the tests passing. + +OK, so you have followed all the process (i.e. your patches are getting +advertised via the project's tracking mechanisms), and your patches +either have no reviews, or only positive reviews. Now what? + +Have you considered reviewing other people's patches? Firstly, +participating in the review process is the best way for you to +understand what reviewers are wanting to see in the code you are +submitting. As you get more practiced at reviewing it will help you to +write "merge-ready" code. Secondly, if you help review other peoples +code and help get their patches ready for the core reviewers to add a ++2, it will free up a lot of non-core and core reviewer time, so they +are more likely to get time to review your code. For more details, +please see: :ref:`Why do code reviews when I'm not core? ` + +Please note, I am not recommending you go to ask people on IRC or via +email for reviews. Please try to get your code reviewed using the above +process first. In many cases multiple direct pings generate frustration +on both sides and that tends to be counter productive. + +Now you have got your code merged, lets make sure you don't need to fix +this bug again. The fact the bug exists means there is a gap in our +testing. Your patch should have included some good unit tests to stop +the bug coming back. But don't stop there, maybe its time to add tempest +tests, to make sure your use case keeps working? Maybe you need to set +up a third party CI so your combination of drivers will keep working? +Getting that extra testing in place should stop a whole heap of bugs, +again giving reviewers more time to get to the issues or features you +want to add in the future. + +Process Evolution Ideas +======================= + +We are always evolving our process as we try to improve and adapt to the +changing shape of the community. Here we discuss some of the ideas, +along with their pros and cons. + +Splitting out the virt drivers (or other bits of code) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Currently, Nova doesn't have strong enough interfaces to split out the +virt drivers, scheduler or REST API. This is seen as the key blocker. +Let's look at both sides of the debate here. + +Reasons for the split: + +- can have separate core teams for each repo + + - this leads to quicker turn around times, largely due to focused + teams + +- splitting out things from core means less knowledge required to + become core in a specific area + +Reasons against the split: + +- loss of interoperability between drivers + + - this is a core part of Nova's mission, to have a single API across + all deployments, and a strong ecosystem of tools and apps built on + that + - we can overcome some of this with stronger interfaces and + functional tests + +- new features often need changes in the API and virt driver anyway + + - the new "depends-on" can make these cross-repo dependencies easier + +- loss of code style consistency across the code base +- fear of fragmenting the nova community, leaving few to work on the + core of the project +- could work in subteams within the main tree + +TODO - need to complete analysis + +Subteam recommendation as a +2 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are groups of people with great knowledge of particular bits of +the code base. It may be a good idea to give their recommendation of a +merge. In addition, having the subteam focus review efforts on a subset +of patches should help concentrate the nova-core reviews they get, and +increase the velocity of getting code merged. + +The first part is for subgroups to show they can do a great job of +recommending patches. This is starting in here: +https://etherpad.openstack.org/p/liberty-nova-priorities-tracking + +Ideally this would be done with gerrit user "tags" rather than an +etherpad. There are some investigations by sdague in how feasible it +would be to add tags to gerrit. + +Stop having to submit a spec for each release +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +As mentioned above, we use blueprints for tracking, and specs to record +design decisions. Targeting specs to a specific release is a heavyweight +solution and blurs the lines between specs and blueprints. At the same +time, we don't want to lose the opportunity to revise existing +blueprints. Maybe there is a better balance? + +What about this kind of process: + +- backlog has these folders: + + - backlog/incomplete - merge a partial spec + - backlog/complete - merge complete specs (remove tracking details, + such as assignee part of the template) + - ?? backlog/expired - specs are moved here from incomplete or + complete when no longer seem to be given attention (after 1 year, + by default) + - /implemented - when a spec is complete it gets moved into the + release directory and possibly updated to reflect what actually + happened + - there will no longer be a per-release approved spec list + +To get your blueprint approved: + +- add it to the next nova meeting + + - if a spec is required, update the URL to point to the spec merged + in a spec to the blueprint + - ensure there is an assignee in the blueprint + +- a day before the meeting, a note is sent to the ML to review the list + before the meeting +- discuss any final objections in the nova-meeting + + - this may result in a request to refine the spec, if things have + changed since it was merged + +- trivial cases can be approved in advance by a nova-driver, so not all + folks need to go through the meeting + +This still needs more thought, but should decouple the spec review from +the release process. It is also more compatible with a runway style +system, that might be less focused on milestones. + +Runways +~~~~~~~ + +Runways are a form of Kanban, where we look at optimising the flow +through the system, by ensure we focus our efforts on reviewing a +specific subset of patches. + +The idea goes something like this: + +- define some states, such as: design backlog, design review, code + backlog, code review, test+doc backlog, complete +- blueprints must be in one of the above state + + - large or high priority bugs may also occupy a code review slot + +- core reviewer member moves item between the slots + + - must not violate the rules on the number of items in each state + - states have a limited number of slots, to ensure focus + - certain percentage of slots are dedicated to priorities, depending + on point in the cycle, and the type of the cycle, etc + +Reasons for: + +- more focused review effort, get more things merged more quickly +- more upfront about when your code is likely to get reviewed +- smooth out current "lumpy" non-priority feature freeze system + +Reasons against: + +- feels like more process overhead +- control is too centralised + +Replacing Milestones with SemVer Releases +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can deploy any commit of Nova and upgrade to a later commit in that +same release. Making our milestones versioned more like an official +release would help signal to our users that people can use the +milestones in production, and get a level of upgrade support. + +It could go something like this: + +- 14.0.0 is milestone 1 +- 14.0.1 is milestone 2 (maybe, because we add features, it should be + 14.1.0?) +- 14.0.2 is milestone 3 +- we might do other releases (once a critical bug is fixed?), as it + makes sense, but we will always be the time bound ones +- 14.0.3 two weeks after milestone 3, adds only bug fixes (and updates + to RPC versions?) + + - maybe a stable branch is created at this point? + +- 14.1.0 adds updated translations and co-ordinated docs + + - this is released from the stable branch? + +- 15.0.0 is the next milestone, in the following cycle + + - not the bump of the major version to signal an upgrade + incompatibility with 13.x + +We are currently watching Ironic to see how their use of semver goes, +and see what lessons need to be learnt before we look to maybe apply +this technique during M. + +Feature Classification +~~~~~~~~~~~~~~~~~~~~~~ + +This is a look at moving forward this effort: + +- http://docs.openstack.org/developer/nova/support-matrix.html + +The things we need to cover: + +- note what is tested, and how often that test passes (via 3rd party + CI, or otherwise) + + - link to current test results for stable and master (time since + last pass, recent pass rate, etc) + - TODO - sync with jogo on his third party CI audit and getting + trends, ask infra + +- include experimental features (untested feature) +- get better at the impact of volume drivers and network drivers on + available features (not just hypervisor drivers) + +Main benefits: + +- users get a clear picture of what is known to work +- be clear about when experimental features are removed, if no tests + are added +- allows a way to add experimental things into Nova, and track either + their removal or maturation * https://wiki.openstack.org/wiki/Nova/Mitaka_Release_Schedule