 So I guess it's time to start. Welcome everybody. I'm Rossella's Blandido. I'm a software engineer for SUSE, and I've been contributing to Neutron for the last year and a half. Today I'm going to guide you through the process of writing your first Neutron patch. So usually when I talk to people and I mention Neutron to people that are not very familiar with it, that's the kind of reaction that I get. It's kind of known that Neutron is a very challenging project and you know, some people, really most people believe that it's really hard to contribute to it. So what I'm trying to do today with this talk is to get you more familiar with Neutron and to get you to successfully merge your first patch so that when you hear the word Neutron, your personal reaction will be like mine, but it's more like this one. Okay, so Let's start with getting a little bit more familiar with Neutron, which is the prerequisite to be able to contribute to it. So what's Neutron? I guess most of you, if you're here, you already know it. It's the OpenStack project that takes care of networking as a service. It means that it handles the network connectivity between the several virtual interfaces that are connected to VMs. And it also provides a very powerful API to be able to configure this connectivity and the API can be used by human operators or by some software that it's orchestrating the cloud. Let's go a little bit more into detail in Neutron architecture. Neutron architecture is modular. It's composed by several pieces and maybe that's one of the reasons why it's so challenging, but it's also very interesting. Between the components, let's start with the Neutron server, that it's the one that exposes the API. Then we have a plugin. Neutron uses plugins to allow more flexibility. You can pick your networking back-end and the plugin accordingly, which supports this network back-end. The default plugin is ML2, but there are also lots of vendor plugins like Cisco, Rista, MidoNet, really a lot. Then Neutron uses several agents. The main one are the plugin agent, that is the one that resides on the compute host and configures the local virtual switch. Then there's the DHCP agent that as the name says is the one that configures the DHCP services. Then there's the L3 agent, that it's the one that provides L3 connectivity netting and it also takes care of the connectivity to the external world. So it makes the cloud accessible from the external world and vice versa enables the cloud to access the external world, the internet, so to say. I'm sure that these two slides are not enough for you and that you want to know more. So what I'm trying to do with this presentation, since I don't have hours, I only have 40 minutes, I am adding links that you can read afterwards or that you can read when you start writing your patch so that you can acquire more knowledge on your own. A very good place to start is the Networking Admin Guide. There you can learn more about Neutron internals and also you can learn how to configure Neutron. I guess most of the people here are software developers like me and I know that we like to go straight to the code and I suggest you to do that. So please clone the Git repo for Neutron and start navigating through the code. My personal suggestion is if you don't know it, just try PyCharm. I use it and it's very handy when you have to go through code that you don't know so well. There are three shortcuts that I use a lot and there's the control N that lets you navigate directly to a class, control shift N that lets you open directly a file and then if you're going through the code and you see a class that you don't know what it is, you can just do control B and you will jump to the declaration. Then another good way for you to acquire more knowledge is to see Neutron in action and that's like the way I prefer, usually when I don't know much about a project, I just install it, launch it and see how it works and you can do it very easily with DevStack. DevStack is a script that lets you install the entire stack and it's very easy, like you just need to clone the DevStack repo and then you launch the stacker Sage script. All the components of OpenStack will run in a screen session that you can resume doing ScreenDashX and you can see the screenshot here and every component has its own window. You can navigate through the windows with the usual screen shortcuts that is control A quote and then you can just use the arrow to pick a window and a very good thing about DevStack is that it runs all the services from source, so you can just modify the code at break points and it will stop. You can use the Python debugger and in my screenshot here I just set a break point for the create port function in Neutron and then in DevStack, the break point was hit and then the debugger stops there and you can go line by line, you can expect the variables so you can really discover a lot and this is also very useful if you are debugging a problem and this is basically the configuration that I use for DevStack and that I recommend you to use. The first lines are simply to enable Neutron instead of Nova Network. This is not gonna be needed anymore soon because Neutron is becoming the default for DevStack but now you need that. Then the following lines are simply hardcoding the password for several services and I do that because I don't want the stacker stage to stop and prompt me input a password. I just want it to go straight till the end and complete the installation of the stack and the very last line is a flag that if it's true DevStack will install also the test-only dependencies while by default it doesn't do that and if you're planning of using DevStack to run the unit test for example, this is very useful because you will get all the dependency installed and you don't have to install it manually yourself. Here is a list of some comments that I think can be very useful to inspect the networking configuration. First of all, IP link, I guess many of you know it, it's the tool that we use to display all the interfaces that are on the machine. Also, the virtual interfaces are displayed and you can use that to check if an interface is up or simply to check what's on the machine. For example, after you boot a VM, you can check what, if there's a new interface, what kind of interface and you can keep track of the changes. Then IP Net-N-S list, it's the tool to list all the networking namespaces on the machine. Neutron uses network namespaces a lot, basically mostly to ensure network isolation. I suggest you to become more familiar with this and learn how Neutron uses the namespaces, you can check that in the admin guide. And so with this comment, you can list them, then if you want to run a comment inside a namespace, you can use IP Net-N-S exec. Then you specify the name of the namespace and the comment that you want to run. For example, if you want to know the list, the interfaces that are on the namespace, let's say namespace1, you just do IP Net-N-S exec, namespace1, IP link. Then we have OVS, VS CTL show, which is a very useful tool if you're using ML 2 with OpenV switch, which is a very common configuration, and this comment will dump all the switches that are on the machine and will also list all the ports. So if you want to keep track of how Neutron configures the virtual bridges, you can do that calling this comment. The last one is in case you're curious about security groups. Security groups in Neutron are a kind of firewall, so if you want to dig more into the implementation, you can just use this IP table dash capital S that will dump all the IP table rows that are on the machines. Okay. Then I'm sure that, you know, just looking at the code or seeing Neutron in action, you will have questions. What's the best place to ask your questions? For sure, IRC is a very good place. There's a, on three note, there's a Neutron-specific channel that it's OpenSack Neutron. I got everybody who's more or less contributing to Neutron is there, and people are very nice, so I suggest you just go there and ask your question. I'm sure you'll get a reply. I'm also there if you want to ping me. Then if your question is a bit more elaborated and you want or you prefer to use an email, there are several mailing lists that you can use. There's the OpenSack mailing list that is for general questions. There's the OpenSack Dev mailing list for development-related questions, which is the one that you want to use, I guess. And then there's the OpenSack operators for questions specifically to deploy OpenSack. And then when you write your email, please follow the mailing list etiquette. There's a nice link there where you can have all the information. Okay, so now we have gone through a little bit through what Neutron is. Let's say you have enough knowledge and you want now to write your patch. There are two ways that you can take. You can start fixing a bug or you can try to implement a new feature for Neutron. Implementing a new feature is for sure a little bit more challenging, but I want to go through that process too, because I'm pretty confident that after fixing some bugs, many of you will want to do something bigger and add a new feature. So the tool that we are going to use is Launchpad. This is a screenshot for the Launchpad page for Neutron. And we use Launchpad mostly for backtracking, also for the blueprints. For those of you who don't know blueprints, blueprints is a description of a feature that you want to add to a project. So you register a blueprint to propose a new feature. And also Launchpad keeps track of releases and milestones. In OpenStack, we have two releases per year and each release contains four or five milestones. And also Launchpad, it has authentication for other websites, like for example, Gary, that I will explain later. So to become a contributor, you need a Launchpad account. If you don't have one, please create one. So you want to fix a bug for Neutron. So the best place to start is the bug page in Launchpad. This is a screenshot. So let me go through some details. So the first column that you see show the bug importance. So when a bug is triaged, it gets assigned an importance. It can be critical, it can be high or low, depends. Then the next column is the status of a bug. So if a bug was just filed, it's new. Then if somebody, somebody else different from the one that filed the bug, confirms that the bug really is an issue, then it can set the bug to confirmed. Then there are like, there's in progress when somebody is working on the bug and fix-committed when the fix for that bug was already committed. Another thing are tags that you can see at your right, at the bottom right. A tag is basically a word that we use to group bugs that have something in common. Like you can use the DB tag to identify all the bugs that have something to do with the DB. And I suggest you look for a very specific tag that it's the low-hanging fruit tag. That is the tag that we use to identify bugs that are easy to fix. So that are okay for somebody that is not so familiar with neutron. So you look for that tag and you will have a list of bugs. You can pick one and assign it to you. It's very important that you assign it to you because it means that you're working on it. So somebody else wants to work on the same bug. It's a way of avoiding a race condition. So here let's go through the process of fixing a bug. So basically here I'm just describing what I'm usually doing. First of all, you should try to reproduce the bug. If it's not a trivial bug, like if it's a type of course, you don't need to reproduce it. But if it's a bug, you should try first to reproduce it. In that way, then you will be able to debug it. If you can use DevStack, like if you can reproduce it on DevStack, then that's probably the best because it's an isolated environment and you have more control. You can set breakpoints. So it's it's gonna be easier to find the problem. But if you can't reproduce it on DevStack because maybe you have to use some kind of hardware, specific hardware to reproduce it, then you can just use log statement and try to try to understand what's the problem. Then once you have an idea of what's going on, you can start writing your patch. After that, you can test it. Since you know how to reproduce the bug, you can test it and verify that with your patch, the bug doesn't appear anymore. Of course, it can happen that you didn't really fix the bug and your test fails. So you have to go back, rework a little bit your patch and then test it again and so on. It's a kind of iterative process, especially for hard bugs. So when you're writing a bug fix, write also unit test. This is required for Neutron and there's a very good reason to do that. It's to avoid regression. Like if you fix a bug and you add a unit test, then if somebody in the future, some part of the code will be changed and the same bug will be introduced, then your unit test will fail and so the regression will be avoided. And also, I'll tell you that sometimes unit tests can be very handy, at least for me, especially when you have like that iterative process of fixing, because if you write a unit test, it's easier to tackle those lines of the code that contain the bug. So you don't have to manually reproduce the bug. You can just run the unit test and finding a fix is gonna be quicker. So now, like you're brave enough and you want to propose a new feature for Neutron, this is like the workflow that you should follow. As I was telling you before, you need to register a blueprint in Launchpad, but that's not enough for Neutron. You also have to add a design specification. So as the name says, the design specification is something that goes more in depth. You can, you have to use a template. You can have a look at the template. I put the link there and you'll see it's very detailed, like you have to explain what, so your change, what tests are gonna be needed to add, what's the impact on the developer, what's the impact on the user, so that you can really think through the change that you're proposing. And then when you're ready, you upload your design spec in Garrett and design spec, they will follow the same workflow as normal patches and I will explain it to you in the next slides. Then what happens? There's a special group called Project Drivers that for Neutron is a subset of core reviewers. And these people, they know a lot about the project and the direction that the project will take. So they are in charge of approving the blueprints or not approving them and they will also set a priority for your blueprint. So now you have your patch ready and I suggest you to run some tests before submitting it. Just to make sure that your patch is working and is okay. And anyway tests are gonna be run in Garrett, so it's better if you run it before. So let's go and speak a little bit about what you should run. So the first kind of test that I run is a style check. This is performed using Flake8 and it's based on the hacking document that I linked here. Basically the hacking document is the style guide that the community uses. And to run the style check, you just do run tests that it's a script that you find in the Neutron root and you specify the flag-p. If it's fine like in the screenshot, you will just see that. If there's a problem it will be displayed so that you will be able to fix it and then run Flake8 again and make sure that you really fixed it. Then unit tests. To run unit tests, you can use the same script run tests without any argument. It will run all the unit tests in the Neutron repo or you can use TOX directly. And if you want to run just one test, what you can do is to use the run test script and then specify the path of the test. You can use also TOX, you do TOX dashi to specify an environment, in this case Python 2.7, and then the path of the test. And these will run only that test. Then if you want to debug the unit test or if you just want to be able to use the debugger when you launch the unit test, you have to specify a flag, otherwise it won't work. So for run tests, you just do run test dashi and then the model that you want to test. And if you want to use TOX, it's a little bit longer. Anyway, that's the way to do that. And if you want to know more about testing for Neutron, there's a link there that you can follow. So now, like, you've run the test, so you're ready to submit your first patch. And so we are going through the process of the submission. So first of all, let's talk briefly about Git, which is a very important tool and it's the tool that we use to manage the code. If you're not familiar with it, try to get familiar because it's really important that there are lots of tutorials online, I'm sure you'll find a way. And so to recap a bit what we've been doing, so the starting point is to clone the Neutron repo. Then we want to fix a bug or we want to add a feature and a good developer would create a topic branch for that. So git checkout dash b and the name of the topic branch. Then we write our patch, we modify the code, we maybe add some new files that you need to add to Git using Git add. And then we are ready to commit. So we do git commit and our patch is ready. So at this point we want to submit it so that the patch can be reviewed and it can be finally merged. The tool that we use is Git review. You can install it using pip and so you just type git review and this will upload your patch upstream and send it to Garrett. Then in Garrett people will review it, tests are gonna be run so you might have to modify a little bit your code to address some comment or fix some tests. And in this case you modify your code and you use git commit amend to amend your commit and then git review again to update your patch upstream. So some words about Garrett Garrett is the tool that we use for code review. This is a screenshot of the OpenStack Garrett and I'm gonna explain you more in detail the column that you see on the right. Those values and what they are. So Garrett is also very important because it's the automatic gatekeeper. I don't know if you're familiar with this concept. Anyway Garrett will run the test every time a patch is submitted. And then when the patch is approved by reviewers before merging the patch tests are gonna be run again and the merge happens only if tests successfully pass. So this is a way of making sure that the code quality stays steady. And that's why it's called automatic gatekeeper. There's no human merging code in OpenStack. This is done automatically through Garrett and Jenkins. Jenkins is the tool that runs the test. Okay, you can see here a screenshot of our review. Like you can see that there's a comment there and you can see patch set number eight. It means that I updated my review eight times. Anyway, if you just go to the Garrett website, I think the UI is pretty straightforward, so I'm not spending more words on it. What I want to talk about is those columns that you saw in the previous slides. Like there's the code review column that it's the column that shows the result of the review of the people. Everybody can review code and can assign a plus one or a minus one. A plus one means that the patch is good, means it looks good to me. Minus one, it means that there's some problem in the patch that should be addressed before merging. Then there's the group of core reviewers that can also give plus two and minus two. Plus two, it means that the patch is approved. Minus two, it's a strong veto. It means that there's some real problem with the patch that it's maybe introducing a very dangerous bug. Minus two, it means don't merge it at any cost. Then there's the workflow column. It can be plus one or minus one. Workflow plus one is given by core reviewers again, and it means this patch can be merged. Merged this patch and the plus one is given when two core reviewers have given plus two to that patch. Workflow minus one is usually given by the submitter of the patch. It simply means that the patch is a work in progress. So when you want to share your code, you want to get some feedback, but you know that it's not ready to be merged. You just set workflow minus one and people will know. They will give you feedback, but they will be aware that it's not a finished patch. Then there's the last column, the verified column, that it's for CI, continuous integration tools. So this column can be plus one. That means verified. So it means all the tests are passing or minus one when some test is failing. Lots of tests are run by the CI. Unit tests, style check, integration tests, using Tempest, that it's the official testing project for OpenStack and upgrade tests using Granade. So it's really a lot of tests. Also for Neutron, since I was selling you at the beginning, the Neutron uses plugins. So a plugin to be in the Neutron 3 is obliged to have a CI vendor CI. So for Neutron, we have the OpenStack CI that is common with the other project and then the vendor CI that it's that it's by the vendor that provides the plugin. This is to make sure that change in Neutron doesn't affect the plugin. And logs are accessible, like all these CI, they are obliged to publish the logs. So in case of failures, you can just have a look at the log and check what what didn't work. So now finally, you have submitted your patch and you're just waiting for get through reviews or you already got reviews. And here I'm just giving you some suggestion about the review process. So every time you update your patch, like every time you get a comment or some test is failing and you have to upload a new patch set to update your patch, this is like this back and forth is very costly for you in terms of time and also for the reviewers. So let's try to minimize this back and forth. And here are like very simple advices that are useful. So check the spelling. Before you submit your patch, make sure you don't have any spelling error. Otherwise, you'll get some comment and you have to fix it. Then if some part of the code is not very, very clear or if some background information is needed, add a comment. It's gonna, like for sure, somebody's gonna ask so it's better if you add a comment. Then before submitting the patch, run the style check and the unit test as I was telling you, they are gonna be run by the CI anyway. So make sure that the patch is working on your local machine. Otherwise, for sure, you'll have to fix it when you get the result from the CI. Create small patches. Small patches are easier to review. So if your patch can be split into two and it still makes sense, I suggest you to do that. It's also better for the statistic because you'll have two comments instead of one. So if you care about the chart, it's a good way to improve your position. Do one logical change per patch. Don't mix logical changes in the same patch. It's confusing for the reviewers and it's also not the right thing to do. And try to avoid dependent patches. If possible, it's not always possible but you have to be aware that it's a pain to deal with them because every time you update a patch, then you have to update all the patches that depend on it. And now some suggestions for the commit message which is probably the first part that people are gonna look at in your patch. So try to describe as clear as possible what your patch is addressing. Don't explain so much what you're doing because we can infer that from the code but explain why you're doing that and how. And so don't be afraid of being verbose. I'd say it's better if you are a bit verbose but if you explain clearly everything. Then use a special tags in the commit message. They were created for a reason. They perform some useful action. Like for example if you use the closest tag to specify that your patch is fixing a bug, then this will automatically update the back page in Launchpad. And for example if your change is introducing something that needs then the documentation to be updated, you can use the doc impact flag. And this will file automatically a bug for the documentation team and they will fix the bug and update the documentation. So you can get more tips if you follow that link. And now some suggestions when you're getting reviews. So try always to be polite. I know it's trivial but I think it's a good rule. Then when you get a comment try to answer. Like if you're going to address that comment so if you're going to apply that suggestion reply down. It's going to be easier than for the reviewer to follow what you've done and what not. If you're not going to apply that suggestion there must be a reason for it. So just answer and explain the reason. Don't just ignore the comment because then somebody else is going to ask. And so sometimes people complain because it's hard to get reviews. It's true because there are lots of patches in Neutron and probably not so many reviewers. Anyway a good way of getting reviews is to be involved in the community. So try to be there for the Neutron meeting. Try to be on IRC. Try to write on the mailing list. Try to talk with people. And especially a good way is to review other people's code. So I'm pretty sure that if you do that somebody will also review your code. And so here I give some suggestion about reviewing other people's code. Again, be polite. Then if you don't understand something it's better if you ask a question. Maybe it simply means that the code needs some renaming or that some comment needs to be added. Anyway, don't be afraid of asking questions. Even if it can seem trivial, but most of the times it's not. When you're giving a suggestion, make sure you provide an example. Like don't write 10,000 words explaining what should be done if you can write three lines of code and make it very clear. So prefer using code snippet if possible. And if you give a minus one, so it means that the patch has some problem, try to follow that patch. Don't forget about it. Because for sure the submitter will reply. Maybe it will upload a new patch set, so it will update the review. And you have to check that your comment was addressed. Or the submitter thinks that your comment is not valid, so it's not going to do anything. In that case, you want to be there to remove your minus one, because if your minus one stays there and this can prevent other people from reviewing that patch, sometimes people don't review patches that got minus one, because they were already reviewed. Or even worse, if the patch is going to be merged, so core reviewer approved it. Usually they don't merge it if they're still minus one pending. So somebody will ping you on your CEO just to make you remove that minus one. So it's a situation that you want to avoid, try to follow up the patches. And when you're doing code reviews, try to prefer quality versus quantity. It doesn't really matter if you do 100 reviews and if you just read briefly through the code. It's really worth taking your time, go deep. You can even test a patch locally. But really that's a process that it's rewarding. You'll provide a better review. And also you as a reviewer, you'll learn a lot. Reviewing, you'll learn a lot about Python, about programming in general, about OpenStack and about Neutron. So it's really worth it. And that was my last slide. Thanks everybody. If you have any questions, I think we have one minute, something like that. Nova Network, yes. Like the default will be Neutron. So yes, I guess the focus is on Neutron now. Yes. Our company is certainly trying to have a third party CI. And then it's been a little challenging. And then I don't know if you are doing right. Yeah, I'm pretty sure there's a wiki page for that. Because when they introduced that, there were lots of talking about it. So there are also people that follow the process for other CI. So I can give you some suggestions with who you should talk. Anyway, it's challenging because you have to set up Jenkins. You have for every patches that it's submitted, you have to run the tasks. So you need an infrastructure to do that. And then you have to make the logs available. So you need a storage for the logs. So yes, it's kind of challenging. And if you're doing that, I mean, there are people that have gone through that. So they brought a documentation and there are also like kind of workflow in place for that. Maybe I have just a specific question. How do you actually submit your test result? I know that we read about this third party plugin on the CI testing requirement doc. It has a specific format. And then it has instruction that we have to submit it. Is that actually submitting to a public OpenStack Jared? Or is that we have to actually submit our HTML? No, you're submitting directly to Garrett. So you run the test and then you submit the result, like a plus one if it worked or minus one using the Garrett... There's an API for that. And then you publish the logs. Yeah. I don't know if that was the question. Okay. I guess. Yeah, thanks everybody.