Larry and Matt share some tips on how to get started making open-source contributions on Drupal.org.
Transcript
Larry Walangitan: Cool. Hey everyone. Today we're going to be talking about getting started with doing some open source contributions on Drupal.org. This is going to be with me, Larry and my colleague Matt.
Matt Daniel: Hello I'm Matt.
Larry: Glad to have you on. Providing some context here, we're going to be sharing about things that we've learned in this ramp up to Drupal 9 and the release of Drupal 9. There's many ways to contribute on Drupal.org. You can contribute on contributing modules. We're going to be focusing on the core. Just Drupal core because even though we've been working with Drupal for a while it feels still a bit intimidating to get involved with Drupal.org and the comments and patches and how to go through this process so that we've gathered and compiled a bit of some links, and some tips, and some tools that have helped us to get up to speed with starting to contribute into Drupal core and be more familiar with that whole process there. Just once again we're going to be focusing on Core and not Contrib. Let me share my screen and we can get right into the nitty-gritty here. The first link, there's this link that's great on Drupal.org about how to get involved. There's a bunch of different ways so you don't necessarily have to be a developer to do and get involved in contributing to Drupal.org. There's support, there's documentation, translation, testing. There's a bunch of other things. For the purposes of our method Monday today, we're going to focus specifically on contributing into development and this is important for us because it helps us to help build our reputation, gets more core commits, get more involved with the community and build our own expertise with Drupal 9 as well. Matt's going to take over here and talk about how we've gotten involved with this.
Matt: Thanks Larry. I echo a lot of Larry's comments and I also found the same when I started working on Drupal's contribution work. It's pretty intimidating. Mostly for me, from the perspective of how do I find something to work on, and what's the process to follow in order to actually contribute in a meaningful way and actually give some good feedback and value back into the community. As Larry mentioned we're mostly going to focus on the Drupal.org core project for today and the screen he has up is actually one of the most useful guides I found which is the Novice code contribution guide. It breaks down a bunch of steps which you pretty much need to follow for any contribution work in terms of development contribution work not documentation or user support.
Basically you can see in that flowchart the get an issue, solve an issue, create a patch, submit it for review, resubmit as needed and then hopefully the issue is fixed. I just wanted to chat about a couple of these in a bit more detail because the workflow doesn't really match what I'm used to working in. Typically, if you're in GitHub you'd be able to push commits to a branch and you can see the differences very easily. In GitHub you're often given tasks to work on. In this space, you've got to go and look for your own tasks and a lot of the contribution work is provided or you contribute through the use of submitting patches as opposed to just pushing commits to a branch. That third step with create a patch is something that we'll talk about in a bit more detail.
In addition to that, the submit for review, you have to remember that there's potentially hundreds I guess of other people that might be reviewing your patch depending on what you're working on so you have to be willing to get lots of feedback whether you agree with it or not. You've got to keep very focused on the issue at hand. If there's something that is out of scope that you just happen to notice when working on an issue, you'd want to spin up a new issue for that otherwise you'll be quickly given feedback on keep focused on the task at hand, don't try and fix anything that's not part of this particular issue.
One of the good things out of it though is you do learn a lot so for me the education side of it has been great. You get to work with code that you don't necessarily need to contribute to. Often you're just consuming but not really providing back if you're just downloading Drupal and spinning up the site. So that's been really good. The other thing is, you may have tons of Drupal experience and this applies to me, I have experience working and using Drupal.org but not in terms of explicitly going there to look for issues to fix and to get involved with. We're trying to help fix them.
I think we could jump to the next section Larry. If you have the link there, the issue queue. We just wanted to put some emphasis on this link. This is one of the most useful places to find issues to work on and you can also look for issues outside of Drupal core for modules and themes but just for the purposes of this Method Monday call, we're focusing on Drupal core issues. You can see that this issue queue, we've already pre-selected some filters so the status is needs work or needs review. There are a bunch of other options like reviewed and tested by the community. We're assuming that those issues may have already been fixed and they're just waiting to get merged in on the next release.
For this, and to keep it to a pretty focused list, those are really good options to search by because those two statuses in particular reflects the fact that these tasks all need some kind of help to get them pushed through. The other key filter here is on the issue tags. We have novice selected, so because we're focusing on just getting started with Drupal.org, that tag is really useful because if anyone thinks that it's a fairly straightforward fix like maybe it just needs some grammatical changes, or there's a typo, or it could be anything from replacing a couple of characters to something more complicated. It can be tagged with novice and it's a good way to jump in there and get started with what should hopefully be a fairly simple code change but the point is that it gets you into the workflow and mindset of working in Drupal.org with patches and comments, and so on.
That's been really useful as well and then as soon as you're ready to get involved in more complex defects or issues, you can remove that tag and basically there's many things to work on. Another couple things to point out are some of these issues are very old. If you look even at the top one, it was updated an hour and 43 minutes ago but it was actually created two years nine months ago, and it has 61 comments in the threads. This may be something that it could be overwhelming to jump in there and figure out what's still remaining to be done or does it just need a review and just that there's probably going to be a lot of information to go through to get up to speed so bear that in mind as well if you're getting started. Even if it looks like it's been worked on recently it might have a big history that you need to take into account as well. I think that's mostly it for this screen. I think Larry's going to talk through some of the workflow for how we actually work on creating and testing some of these patches.
Larry: Thanks Matt. Talking about the filtering here. Right now we're looking at Last Updated and this is really great to see the status of things. Personally when we are looking for issues and tickets to work on, starting with Created is a good place because usually it's something that we can start to look at. For example this change documentation link, there's only five replies. It seems to be a fairly straightforward issue here and it's not super daunting especially if you're just getting involved on Drupal.org and want to dive into something, starting with the Created filter and filtering it with that helps to select some of these that are a bit more accessible for someone, as opposed to ones that like Matt said have 60 plus comments that will take a lot of time to get up to speed with the issues there.
I'm going to open this change scaffolding documentation link and we can look at this together. To talk about how we're going to actually do some of the work there's a few things that we wanted to call out in terms of tooling. The first one is a plug-in called Dreditor. I'm going to get the link here and we can take a look at it. It's something that's available on Firefox and on Chrome. There's different extensions that are available to us and now this makes it much more easier to review some of the patch files that are updated. If we take a look at this one number two, there's these two buttons when the chrome extension is enabled that gives us a sense that we can see a diff on GitHub or GitLab, that makes it easier to know what's actually happening as you're scrolling through tickets and trying to see what sort of issues you want to contribute to. That's a great tool, Dreditor.
Another one that we use is Lando. Lando has a Drupal 9 recipe that we can use to get our Drupal 9 set up and segment our local development to be Drupal 9 specific so we don't have to mess with any of the setup of any other Drupal instances we have in our local dev. I'm going to share my terminal and we can take a look at what I have set up locally. We can look at our Lando file here, just inside of this we have our Lando. I'm using still the Drupal 8 Lando recipe which is pretty simple, pretty straightforward. I haven't tested the beta version of Drupal 9 just yet so I'm still working on the Drupal 8 recipe. I'm not sure if Matt if you're still working off of this recipe as well? Mat: Yes, I'm using the same.
Larry: Great. So far it seems to work pretty well and I'm sure we're going to transition to the Drupal 9 recipe soon. If you just want to get started just using whatever's set for Drupal 8, works pretty well. Another tool that we will use is called [inaudible 00:11:51] Details. This is something that allows us to create interdiffs. This is something that we don't see on this issue in particular but ideally, between patches we want to see an interdiff that notes the difference between the two patches in a easy to read way.
If we go back we can take a look at one of these other issues that has a lot of replies. We'll be able to see an example of an interdiff. This is just a common practice on Drupal.org when you're contributing to be able to quickly get a sense of where the status of things are in terms of tickets. We see one here by our very own Matt Matsu that has an interdiff and a patch. Using Dreditor we can see this interdiff that compares his patch with the patch that was submitted previous to that.
This is a tool called Patchutils. There's a lot of different installations of it. It works on most systems, so different ways to install it. The best way that we do it for Mac is just to use Homebrew. Brew install Patchutils allows us to get access to the interdiff command here that creates this incremental patch between two patches. Matt, is there any other tooling that we've been using that you'd like to call out? We've talked about Lando, Dreditor, and Patchutils. Those are the ones that I feel like have been pretty standard for the work that we've been doing.
Matt: Yes, that's exactly the same as me. Just there is a useful curl command that's a one-liner for applying patches. Is that something you'll look at, Larry?
Larry: Yes, that's great. Let me switch back to my terminal. Actually, we're going to take this issue that we were looking at back here and get a sense live demo style, we'll see how this works, of what's happening. We want to update from Drupal 8 and it looks like in our first patch we're just updating the scaffold line from 8.8.x to 9.1.x. We're able to take this patch, we can copy the link address here. If we go back to the terminal, I'll switch into my Drupal 9 branch so we can see that they we're on 9.0.x here. We can apply patches, there's a variety of ways to do so.
There's a whole documentation section on Drupal.org about applying patches. We're going to apply patches here using curl which seems to be one of the simpler ways to do so. Curl, the link to the patch, pipe and then patch and patch p1. We can apply this patch and we see that in our patch applied it downloaded cleanly. Get our git status and we can see that there's a modified file inside of here. That's a super simple way of applying patches. This works also for contributed work as well if you want to apply patches there.
It's the recommended tooling that Matt and I have been working with in our own personal terminals to apply patches for issues. Now quickly I'm going to make a quick update here just in my editor. I'm not going to share the screen but I'm just going to make a quick update and save. I want to showcase the interdiff tools, this is going to generate an interdiff with our two patch files. Maybe this is not a great time for a live download Matt. Can you think of real quick like with setting up the interdiff, what we need to make sure we--
Matt: You could even grab the previous patch and then just interdiff the two of those just so you don't have to create a new change from the comment, the issue thread just for the sake of demoing the interdiff tool. The thing with the interdiff which neither Larry or I we're used to doing is, that's an expected courtesy as part of any contribution thread. As well as you're taking the time and trying to fix the issue, you also want to make it easy for the next person to come and review it. That's where a lot of issues or comments people don't put the interdiff and then you'll get comments back saying, "Please add an interdiff." Instead of taking another day or so to get back and do that, it's great just to submit it in a single comment so you have your patch and the diff in one go.
Larry: Great. I have the interdiff here locally. We'll do this with interdiff. I'll pull in the patch number and we'll say interdiff using the same naming scheme that Matt referenced. We have our issue number, this is from the URL and then dash comments will be number six.
Matt: Missed your command. You'll need the old patch and the new patch if you download like patch four or something.
Larry: That's right. Sorry for the technical difficulties here as we get these patches squared away. The command that we're basically putting in is this structure. We have interdiff which is a patchutils tool, our old patch and creating following this exactly. I think for the sake of time we'll just call this out of how we create these interdiffs. This creates a nice and clean similar to what we saw Matt's comment innovative look like. One of the tools that we've found and it's probably the cleanest tool that we've used for creating interdiffs, I know that there's other ways that you can do so. On Drupal.org there's some documentation on how to create interdiffs in other ways as well here. This is super useful. Like Matt said, it's a great courtesy to do if it's something that you're picking up an issue on that's being worked on. Making small updates and creating an interdiff is super appreciated from all of the maintainers there as well.
Matt: Larry, can I just point out the command you had in your terminal, it mentions comment number there so one thing that is also a little bit strange when you first get started is you have to go back to the thread and then figure out what your comment would be when you post it because it hasn't yet been posted to Drupal.org and then try and name your patch appropriately. Just increment the number of whatever the last comment number is and that's generally the best practice for naming the file.
Larry: Then we can see here that we see when we're adding a comment to upload our files like Matt said, we can see it's going to be number six. I know that there's been some anxiety on my part sometimes when I'm working on an issue. I'm nervous someone's going to swoop in and add a new comment and all my things are going to be off by one but that's anxiety that's never come to fruition. I wouldn't worry about it either from that point of view as well. I know we have just a few minutes for questions. Just to call out so we have this great tool that Mark wrote about announcing our Drupal.org statistics and slack. This has been cool to keep track of in our open source channel. Just to see what projects we're supporting, what issue count we have. If you're interested, please check out this blog post.
Also leading into our discussion here, I know Matt has been working on a blog post that captures what we've talked about here today in written form so that you'll be able to reference this. All of this stuff, none of this is particularly new. It's all on Drupal.org, but we've tried to link the pieces that we found the most helpful in our own workflow and experience in diving into getting into Drupal.org and Drupal core contributions. I think that's it. I'm nervous to go back to my live demo portion just because I feel like it's going to take a bit of time there but perhaps in another session we can look at this in more detail about some of the more advanced portions of contributing on Drupal.org.
Mark: I have a couple questions.
Larry: Cool.
Mark: I wonder if we can probably-- These links that you shared, we could probably put them in the video description so if people are watching this later, they can get at some of the stuff that you mentioned. I think that would be cool. I had two questions. One is just a call out. I thought Dreditor was no longer being maintained so that's pretty cool if it's not. I had missed Dreditor often. Did you happen to run into anything about that or run into any issues using Dreditor?
Larry: No, it seems to be working pretty well from our usage. I think that was new to me that if it's no longer maintained.
Mark: Okay, maybe it's just moved to a different maintainer or something, or I was mistaken. The other question I had was just are there any contributing faux pas that people should avoid or watch out for?
Larry: This is interesting I think that there are some, a few things that we should call out in that regard. I think one is just coming into an issue and making an update and leaving never to come back again. Just trying to get an issue credit without actually being involved with the actual work. That I think is something that is not necessarily a great thing to do. Just trolling for easy issues and comments there.
A remedy towards that, if you're going into an issue and it does have some work that's being done, some helpful things to do are always screenshots. Not just applying a patch and saying patch applies cleanly, it's good to go, without running it locally and seeing how it actually affects Drupal core. Getting a screenshot saying I tested the module or the portion that this patch applies to, here's what it looks like on Drupal 9. That's always super appreciative and helpful. Matt are there any other faux pas you can think of that we've encountered in our work?
Matt: One of them I guess would be using the Assigned To field so you can assign a thread to yourself to work on it but generally you only want to do that if you're actively working on it. There are a couple of issues I was actually following and then someone assigned it to themselves, so they dropped off my radar but then it could be a week or so and there's no action being taken on that thread. Then someone has to remind them. Only assign it to yourself if you're actually going to work on it or contribute in the next day or two because otherwise people will overlook it because on the issue queue you can also see if it's assigned to anyone.
That was something that I would look for if someone had recently assigned it to themselves, I may not pick up or start working on something because I don't want to do duplicate effort. That was one thing to keep in mind. The other one for me was just to keep close track on what the issue is that we're trying to solve so you don't go fixing things that you notice or having to get people's feedback on things that aren't really part of that change set. I think just to keep it concise is the best way to go.
Chris: We had one question from Adam. He asks, when you clone a module repo to work on it, do you have any recommendations on how to integrate it with a full Drupal code based site for testing? I know that your talk today was mostly centered around working on core, and this is a little bit more on contrib but do any of you have thoughts on that?
Matt: For me I would just clone the module using the command you can get right from the module page. I would clone it and then I'd apply my patch and work that way. There's a full Git workflow as well on how if you don't want to use the interdiff tool, you can also create a local branch and work on it that way and create a diff between your branches. Which is so I think it's just a case of trying what works best for you and ultimately you're trying to get that patch filed cleanly out of there with your own change set in it. Beyond that, I can't think of anything specific that would be a very big difference between working against core and a contributed module really. Any thoughts Larry?
Larry: I'd also echo that using Lando has been super helpful in terms of just starting from scratch, getting clean install of Drupal 9 and installing that module so you know that any issues that you see are specific to that module. I know that in the past I've had just this is my contrib directory where I put everything in but sometimes that creates a lot of noise when I'm working on multiple modules or trying to apply patches here and there. I found that it's just way more cleaner to clean the slate, work on an issue or module set and then get rid of it and start again with something fresh so you don't run into weird issues with dependencies or those sorts of things as you're applying patches all over the place.
Chris: I've got one last question and I think I might be putting you on the spot because you're obviously not in charge of the association's move to GitLab, and in particular merge requests but have you guys looked at all about the issue, about when that might be completed or what the status is of that because I know personally patches, patch workflow, and interdiffs, all that stuff in the time that I've tried to contribute or have contributed have been in a blocker or just really slowed me down. Especially if I haven't done it in a while. I don't know, thoughts on that or any insight you guys can provide in that regard?
Larry: I don't know the status of where we stand on that. It's something that's super welcome because in reality this whole how to contribute on Drupal.org has been a bit of weight on the velocity of things. I feel like that whenever that happens that would be super great. It can't come soon enough in my opinion.
Chris: Agreed?
Matt: Agreed on my side as well. The patch workflow's been one of the biggest pieces on my side. I always need to make sure I'm doing it correctly at least until I got a few under my belt for applying a patch and creating one and creating the interdiff. So yes, that would be welcomed. I also don't know the status of timing or anything on that.
Mark: I don't know the latest but I would expect that there's going to be news shared at Drupalcon in a few weeks about at least I don't know whether there will be news or not but it's sharing the status of where they're at as part of that phased migration.
Chris: Excellent.
Larry: Great. If there are no other questions, we'll get that blog post worked on. We'll get that up on the site. I'm sure we'll do a follow-up on on some of this as well in the future. Maybe more contrib focused on getting things ready for D9 since there's a lot of work that still needs to be done in that part as well.
Mark: Do we need to tell people to like and subscribe down here?
Larry: Yes.
Mark: We're not on YouTube if you don't do that I heard. We will add links to the video description of the items that Larry mentioned.
Larry: Great.
Chris: Thanks guys.
Larry: Thanks everyone.
Matt: Thanks everybody.
[00:30:20] [END OF AUDIO]
