 COVID-19 situation. Our company decided not to fly us out to do this remotely. So that's why I'm here now. I'm working in the Drupal issue queue. My name is Ilke Blok. I'm a senior Drupal developer at Wonshu in the Netherlands. Wonshu is a full-service digital agency. I'm on Twitter at Ilke Blok and I'm also Ilke Blok on Drupal.org. I'm not sure how we should handle questions. You could shoot them over on Twitter. I'll keep an eye on that or maybe we can just do it through microphone. Right. What will we talk about today? First of all, what are issues and what is the issue queue? Just to make sure we're all on the same page. Then we'll talk about issue statuses and priorities. The issue template I'll explain. We'll talk quite a bit about patches, how to create patches, how to apply patches, how to re-roll patches, that sort of thing. And then maybe if we have time, I can give you a sneak peek into the future for Drupal issue queue when working on the software. So what's an issue? Basically any change to Drupal or a contributed project will be described in an issue on Drupal.org. There are various categories of issues, bugs, features, tasks, plans and support requests. In other settings you might also refer to them as tickets, for example, if you are working in a support organization or something like that. So what then is the issue queue? Drupal core has one and each contributed project has one. There are also some special issue queues on Drupal.org. The ideas issue queue is a nice one. If you have a good idea for Drupal, you could first create an issue in the ideas issue queue to see what people think about it, maybe flesh out the idea together and then only when the ideas are concrete you can actually start building software and patches in the actual Drupal issue queue. People refer to the issue queue. There is actually a single overview of all the issues on Drupal.org. It's at Drupal.org slash project slash issues. It could be interesting to see the sheer volume of issues that is available, but actually it's more practical usually to look at the issues for just a single project and you get to see those when you put the name of the project behind that URL. Every project will have a block like this. If you look on your computer you will see this on the right sidebar or if you're looking on a mobile phone, for example, you'll see it at the bottom. It's like an overview block of that project issue queue. It has a little search box, an overview of how many open issues there are, how many issues to review, the total numbers and also bugs are singled out because they're obviously pretty important. Some nice statistics about how many new issues were created, how quickly or whether response has been given, that sort of thing. And then the issue queue itself looks like this. This is the one for Drupal core. You can search for keywords, you can filter by status, priority, that sort of thing. One important part if you start working in the Drupal issue queue is if you work for a company, then list that company in your Drupal.org profile. When you work on issues and especially not just when you supply patches or when you just weigh in with your opinion, you get issue credit once an issue has been committed. And if you tie that to your company, your company will get credit as well and it will, for example, influence the position where it's listed on the Drupal.org marketplace. So how do you do that? When you click on your avatar on the top right in Drupal.org, you click on my account, you go to profile, you go to edit that profile, and then when you scroll all the way to the bottom, you get to this, a set of vertical tabs and then in the work tab you can select your current company as well as any previous companies that you might have worked for. Right. On to the various categories of issues. First up is support requests. You could create a support request issue when you're having trouble using Drupal or some contributed module, or what actually is also pretty common is if somebody opens, for example, a feature request or a bug report, somebody else comes along that basically thinks, well, that is supported. That is possible. You're just doing it wrong. They might actually change it to be a support request. And then obviously the neighborly thing to do is to actually also say what, how you should be doing it and how you can actually achieve what you are trying to do. I personally don't consider an issue, and you issue Q the best way to get support. So you probably should consider using other means of getting support. Just a web search. I use Dr. Go for that myself as a convenient url.com. Of course, you could also use Google for something like that or whatever other search engine you prefer. Somewhere where you might actually have a good chance of ending up when you do a web search is StackExchange. There is a Drupal dedicated StackExchange, which is a question and answer site, which has very good information as well. And obviously if you cannot find the answer to your question, you can ask a question on there. There are a lot of people in the community are actually on there as well who can support you. And then for more interactive experience, basically there's Slack and IRC. They're both chat solutions. IRC is more like the old school way of doing things. It's got a bit of a learning curve, although the page you see linked there is quite good and can help you get connected. And then there is Slack, of course, which is basically the same idea, although it's probably a bit easier to get on. And everything to do with Drupal on Slack is listed on the page you see linked there, Drupal.org slash Slack. So next up, bugs. All this is basically, by the way, it's based on definitions for core. And the definitions might differ a little bit for other projects, although they generally follow the core definitions. A bug is a functional error in the system. You could think of examples like PHP error, such as a warning or a notice, data loss, regressions in functionality, memory leaks, that sort of thing. Obviously they have different severity, but that's something we'll get to later. And there's tasks. Basically, tasks are things that need to be done, but they're neither a bug nor a feature. Examples could include refactoring code to make it more readable, adding automated tests for something that doesn't have tests yet, or maybe add some more tests. Refactoring functions for performance, as long as it's not causing functional errors, because otherwise it basically would be a bug. Uplating code to new APIs, that sort of thing. Feature requests. Basically, any completely new functionality would be a feature request. For example, new modules, like a media browser, for example, that was added not so long ago. New subsystems, like JSON API, and adding or actually also removing an option from some administration form, for example, could all be called feature requests. Then there's plans. I copied the definition from the documentation, actually. It says plans are used for major issues that capture process and give an overview to problems that cannot be solved with one issue. Then issues will often have multiple sub-steps in related child issues, and those are issues that have the plan issue and their parent issue relationship field. Basically, it's like for bigger things that need more small steps to actually accomplish, it can be divided into small steps. You might see a plan for that. Right, we'll move on to issue priorities. These are basically the four ones that you might find. Guidelines for when a priority can be applied are based on the categories, so bugs, feature requests, that sort of thing. The guidelines get less strict with lower priorities. You'll see that critical issues can actually block the release of major versions, like 8.0, 9.0. Major versions, if any critical bugs apply to them, won't be released until all of them have been fixed. That does not apply to minor patches like 8.1.0, 8.0.1, 7.1, for example. Major issues are useful issues that are not critical but do have significant impact or important by community consensus. Basically, everyone agreed that it's important, can become major. They are prioritized in current development release, and they may actually be backported to stable releases where applicable, for example. We're currently on Drupal 8.8, but 8.7 is still supported. Any major bug might actually be backported to 8.7 as well, if it makes sense. There's normal and minor. Basically, normal is everything else. Minor is limited to usually cosmetic small little problems, for example. So when there's an issue considered critical, bugs can be considered critical when they render a site unusable and there is no workaround. When there is data loss, actually the actual data in the site is destroyed for some reason. For security vulnerabilities, you'll see a small asterisk there because security vulnerabilities should actually usually be reported through the proper channels, the secure.drupal.org site. They should not be reported through the regular issue queue because that's public. We would like to keep those under wraps until there's actually a solution for the problem. Tasks might be critical when there are severe performance issues, significant regressions, and a maintainer can always decide that an issue should not block a release actually and can downgrade it in that case. Features are actually rarely critical and would be at the maintainer's discretion to make a feature critical. When there's an issue major, bugs might be major when they have significant repercussions but do not render the whole system unusable or when they have a known workaround. For example, they could interfere with normal site visitors use of the site. They might render one feature unusable with no workaround as opposed to the entire site. It might be blocking contributed projects without a workaround or when user input is caused to be lost but not actually corrupting existing data, so that's a difference between a critical bug and a major bug might be that actual data in the system being broken would be critical. Well, if you try to get data into the system that's lost, that would be major. It's still obviously a big problem but not as big as if existing data would be destroyed. Tasks could be major for important API additions, refactoring other significant changes that are not bugs. An example could include code refactoring like the removal of the taxonomy term reference field in favor of entity reference which I think happened from Drupal 7 to Drupal 8 or decoupling Drupal core from a dependency that's no longer supported, that sort of thing. Features could be major based on their value to the project overall or the scope of work to complete them. An example could be providing a better UX for creating editing and managing draft revisions, for example. And like I said before, normal and minor we haven't discussed that normal would be everything else and minor is basically cosmetic issues that do influence the functionality or sorry do not influence the functionality or main purpose. Right, onto issue statuses. These are the major statuses an issue could have. I drew some transitions that make sense. Basically, there are no limitations to what status you from what status you can go to which status. Usually or issues will start out on active. It's the default. It means there is no patch and sometimes it can also be used to reset an issue even when a patch has been attached. Issue will then move to needs review when a patch has been added. It means the issue needs review and testing of the patch. It's also a trigger for the test box to start testing the patch, apply it to the project and see if all the tests still run. Or if there's no test, it could also be that somebody came up with an idea that they think needs reviewing and that status is also used by people looking for issues to review. Let's see if there are patches and then a review is needed. After that, the issue might move on to needs work. It means it has a patch but there is additional work to be done. It could be set by a reviewer who looked at the patch and found there's work to be done. The test model will also do this. If tests fail, it will automatically set the issue to needs work or the author could actually do it themselves saying, okay, I'm not actually finished with this yet. It needs some additional work. That could go back and forth a few times needs review needs work and eventually if everybody agrees that it is good to go, the status will be made reviewed and tested by the community. You'll see that often shorted into RTPC. It means that the issue received sufficient reviewing and it's deemed ready to be committed. Usually that is not set by the patch author but by somebody else and it's basically a judgment called whether it can be set to RTPC. It's about whether everyone who has done a review actually agrees that it's good to go. It looks like enough people looked at it to agree that it's good to go that sort of thing. Although this status does not mean it will be committed and it's still up to the maintainer and it might actually get reset to needs review again or maybe even needs work if somebody feels it needs to be. If an issue is on the status reviewed and tested by the community for a long time that might actually be an indication that needs to be re-evaluated. Then there's a status patch to be ported. Once an issue has been committed it might move to that if the problem also applies to a different version for example of Drupal. Something might be solved on Drupal 8 first and then it might need to be report back to Drupal 7 for example. Once something is committed and there is actually no patch to be reported it will get moved to fixed and the status basically only exists to have it still show up in the issue queue because after a while it will be automatically transitioned to closed fixed in which case it will not show up in the issue queue any longer and that should be specifically filtered for it I think. Then there are two versions of post phones. The first one is just regular post phone it means the issue is still valid and should be fixed but there are blockers. In that case if you put it to post phone make sure that the issue is marked as blocked and state which issues are blocking it and also attach those related issues or it means that the issue is not being worked on actively but the intention is to actually return to it and then post phone maintainer needs more info basically means there is insufficient information in the issue to proceed and if it stays there too long the maintainer might actually decide to put it to closed cannot reproduce or closed won't fix. That's also an indication I drew only closed in this flow chart but there is actually cheating a little bit because there is actually six different persons of closed we're running a bit late so I won't go through them all but like I said closed fixed is basically not something you should put an issue to yourself the others could all be said by you as a user or somebody else and they have their specific meanings and they do make a lot of sense if you want to look at it or want to find out what they all mean exactly it is all documented on Drupal.org as well. So moving on when you create a new issue actually it's important when you think about creating a new issue to know when you should not create a new issue the link you see on the screen has a good article about this it's titled how to solve all your problems and basically it's about this subject it helps you narrow down your issues your problems that you encounter and make sure that when you actually end up creating an issue that you really found something new. For example you should always try the latest code that means the development version so it might not even be the latest release there might be a development version of whatever module you found a problem with that has already a solution for your problem you should check the issue queue for existing issues but when you do find an issue that looks a lot like yours do not change the version because usually issues only apply to a specific version and you might have the same problem but then it's a good idea to actually create a new issue for the other version. When you check the issue queue try search terms you would use to describe your issue but also use search terms that somebody else might use to describe the issue and do not reopen closed issues unless it was closed very recently and you find that it's not actually fixed and do explain in that case otherwise it's better to create a new issue actually and lastly make sure to always run updates there are many problems that sites encounter which can be traced back to not actually having run updates properly either through drush updb or through the updates php web page can also help and then when all else fails you could actually create an issue make sure you only report one issue per issue that sounds a bit silly but you probably understand what I mean don't put a entire very long list of all the issues you found with some projects in a single issue or even worse multiple projects make the title descriptive not too short not too long so that people understand what it is about and then in the issue summary give enough information obviously not too much but do give enough information for people to be able to reproduce for example that's the next bullet point steps to reproduce what should somebody who tries to understand your your issue do to see the see the issue themselves and lastly use the issue template the issue template is linked here dribble.org slash issue summaries it's somewhere on the page it looks like this you can copy paste it directly in the issue or you can use a tool like text expander I have it on a on a short string I can type on the keyboard and it will just fill this out for me starts with the problem motivation why did you file the issue steps to reproduce should be in there as well if you have them that sort of thing then your proposed resolution why do you think this is the best solution maybe any workarounds that exist for people who cannot use the patch any remaining tasks is the next heading that would include create a patch create tests reviews documentation needs to be written that sort of thing then come a few sections that basically describe what would change if your patch were applied changes to the user interface changes to the API changes to the data model part of this is also a recent release note snippet if the issue ends up being in a release what could be added to the release notes to explain what was changed and then lastly if you applied this template to an existing issue you could leave the original report as created by whoever created that issue originally right then what's a patch the patch basically is a file describing changes that need to be made to a set of other files for example triple itself contributed module we named patches for according to certain convention and there's actually a naming convention for every taste if you look on the URL linked here you'll find that there's actually numerous naming conventions basically pick the one that you prefer most I like a lot of description so that it makes it easy to identify the patch well the first one is like this it's the least descriptive one actually it's just the issue number and the comment number where you posted the patch in the issue then the next one is a bit more descriptive it adds the description at the start of the patch name and then the last one is even more descriptive because it also adds the project name in the patch I like this one most I usually use this one because it makes it most easy to to identify a patch file then there is two variations the first one actually has some functional implications it tells the test ball to not actually test this patch if you do not test in your patch file name the second indicates that you expect this patch to actually fail and why that is useful I will tell you a little bit later I don't think this has any functional implications at all you also see tests only for example for this right then working with patches remember that kit is your friend it is a very powerful tool that even though we do not use to create pull requests for example it's still very useful to work with patches so before you start make sure you have a clone of the project skip repo what I usually do you will run into the need for creating a patch while working on a project what I usually do is I'll make the changes within that project that will obviously be for example in a composer downloaded module so it will be hard to to get it into the to get it into a patch I then create a clone and I'll copy the files from the changed files from our project over into the clone so first of all let's look at what you do for to apply a patch an existing patch that you download is from Google org and you want to continue work on for example you find the commit where that patch was created from this step can often be skipped although it can be important later on you create a branch at that point for example you could use the issue number and then I put a temp number there it would usually not correspond to the actual comment number that you would put in the patch name because you might have several patches coming from the same branch so it could be something like this it could also be a description of what you're trying to solve that sort of thing that branch name doesn't make that much of a difference and then you'll apply the patch using get apply minus fee is for verbose so that you can see what is actually happening there and you commit the changes that the patch has made again the message doesn't really make much difference except for yourself it's useful to actually report what patch you actually applied there and that's it that's where you have your patch applied and can work continue working with it so what would you do if you create a patch you basically start with the same first two steps although you'll probably want to start with the tip of the branch that you actually want to solve the problem for so you don't have to find a commit where the patch was created from because you're still creating a patch you create a branch and you just solve your problem that would be look like something like this and you commit you make a commit message solve the issue whatever you can come up with your own submit message your commit message that makes sense to you and then you can create a patch with it this you basically list the changes between the current branch the in this case the 8.x.10 which is a tag and you list the changes with your actual solved can you see my match counter or not probably and basically list the changes between these points in get what I will usually do is I'll leave off the patch name and you can just see the changes then in your terminal you can see what the patch would look like and then when it satisfies you you can redirect it into a patch file name that even works when you do it like this when you have a few more commits I like to make a lot of commits usually when I am programming and you can use the exact same git command again to get a patch name something else that you might come across and that people might actually request if you post patches especially if the if the issue is getting a bit long is an interactive it's a way for reviewers to quickly understand the changes that you made from one patch to the next and it's basically a patch itself only from one point in your basically your patch history then from to the next for example went back to the previous slide if you wanted to create an interactive if you for example you created a patch here and then later on you created a patch over there you could actually create an interdiff by doing git diff between this commit and that commit and you pipe it into another file just call it interdiff something something dot txt and you have your interdiff file and it helps reviewers to understand what changes you make since the last version of your patch so that's an interdiff right moving on to rerolling patches that's also something you'll see you will find that you might actually have found an issue that covers the problem you've encountered you are happy to find that there is actually a patch you try to apply it to your project and you find it doesn't apply anymore that might happen if the base project changed in such a way that the patch well the base project changed so much that the patch no longer applies and that actually means there is a merge conflict and it just so happens that that although you might not think so git is actually very good at resolving conflicts by itself it's much better than most patches can figure out or most mechanisms to apply patches so to illustrate let's say we did actually find the commit where the patch was applied this is where we actually could go back to the very first slide about patches this is where it becomes really important to find out from where the commit or sorry the patch was created you find that commit you apply the patch or you create a branch and apply the patch there and what you can then do is just use git to merge in the latest version of the project in many cases that will actually be all you need to do in others there might actually be some merge conflict at the end that git cannot figure out itself either and you have to solve those but at that point it's no different than solving a merge conflict in any other git project and once you've done that you resolved any conflicts that there might be you can just go back to what you learned before you can do a git diff make sure that you do the difference between the tip of your patch branch against the commit that was actually merged in and by that time you will have re-rolled a patch and you can post it you can say okay thanks I re-roll this against version whatever people will be happy because you helped them getting the patch applied again right then I quickly mentioned before test only patches many projects actually require tests and then the it becomes a challenge to actually demonstrate that the tests that you created that go with your patch actually test the changes you've made and what better way is there to have a patch that only contains your tests because when trying to run those tests and your code is not actually there those tests would actually fail you could do this for example by having a separate branch where you only build the tests and then you merge that into your full patch branch and that makes it pretty easy with the workflow and I've shown you to get test only patches as well as a full patch so that concludes my slides on the current state of things I can't really I was hoping that I was actually there to to see you but basically I don't think anybody currently thinks this is a workflow that is fit for 2020 the future and we're already with one food in that future is GitLab it's already being used on Drupal.org there's git.drupal.co.org which is where you end up if you click the browse code repository link that every project page has so it's already being used for browsing repositories and work is actually being done right now to have per issue repositories which would also enable editing in the online browser on GitLab which could be very useful for little typos in documentation for example or in translation strings that sort of thing it would not require you to create a Git clone go through all the patching that sort of thing but you can just create an issue create a quick edit in GitLab and create a pull request that would be very nice and obviously it will also be very nice to not having to create all these patches just being able to push to per issue repository and collaborate that way an example that is posted somewhere on Drupal.org looks like this you'll see the main branch on the left for some project it's actually based on the interaction in a particular issue and then you see people collaborating and finally you also see somewhere over here somebody made some changes that were actually not used in the end you'll see some people interacting every color represent somebody else and eventually the main branch is merged in and then it's merged back into the main branch and that would conclude that issue so fingers crossed this doesn't take too much time anymore because personally I'm quite fed up with patches actually but we're still stuck with them for the moment right that concludes my talk so are there any questions I'm just looking at Twitter in case anybody use that I guess we finish early are you guys having some get together tonight yeah about to go to the coin laundry for a social night okay shame I can be there I have a lot of fun guys and it was nice to be able to do this it'll be online probably tomorrow now but yeah so yeah cool I'll look out for that brilliant all right thank you very much thank you too cheers bye bye