First Time Contribution Workshop

AMYJUNE HINELINE:
OK, one last time, I'll be the housekeeping in case someone new came in since the last time. This is the first-time contributor workshop. We're gonna be going over some different ways about why we contribute. I'll be sharing techniques on how to find things to contribute to, and then I'll go over the order workflow process of reviewing an issue and creating a patch, and then right after this workshop, Markee is going to go over the new workflow process of the merge requests. If you're looking for general contributions, those are in different rooms and you can go to the mid-camp page and you'll see that all the different links to all the different sprints. There's a general contribution room, Randi Phase is in there. And I think with Matthew and they'll be helping folks throughout the day, set up their machines for local environment. And what I'm going to do is I'm gonna go over how to do these in ways that you don't need a local environment. We'll be looking at how to write a patch, but not using code.

So, we don't necessarily have to have a local environment to test that because it doesn't show up in the user interface. And I am part of hearing. So, using the chat works really good. I do get into momentum and sometimes I don't see this chat, but just be mindful that if I don't hear you just if you put a little alert in the chat, that's a good way to tell me that you're saying. So if I'm focusing, I can hear just fine. But sometimes when I'm in the flow and talking to myself, I just don't catch everything and you know, you're here because you wanna contribute back to Japan, which is really great, and I just wanna tell folks that I am a non-code developer. I do know some code, but most of the stuff I do in the community doesn't have to do with code. And that's why I think it's important for folks like me to give some of these workshops. So, not only coders can follow along, but people who don't have experience with a lot of these things. You know, your traditional roles that are excluded from giving back to Drupal like human resources or, you know, you're in sales and stuff like that.

I try to teach it in a way that everyone can contribute back because we know that it really feels good when we do that. I'll post the link one more time to the slide deck because I do provide a lot of slides and there's that and I'll just get started, because the first few slides are kind of fluffy and it gets people tended to kind of role in. My name is AmyJune, that's titled Amy Case never Amy. So, if you fall out, Amy, I might not hear that. So it's always AmyJune. I worked at Kanopi Studios. I am their QA engineer and open-source Ambassador. Most of the days I just kinda do stuff like this and get back to Drupal and find ways to help. Initiative leads to do different things. I am a hospice nurse by trade and I've only been doing tech for like six years. So, I'm really into accessibility because I had first hand experience how hard it is for folks to use technology. So, I help organize sort of a Drupal adjacent meetup space called accessibility talks. We meet once a month and talk about things about digital accessibility.

And I share that because we have all different kinds of presentations and we have a huge library of resources. So, if you wanna find out a little bit more about accessibility, it's a A11yT-A-L-K-S. And that's like on Twitter and a website and on YouTube. I do help with core mentoring for charitable contributions. And I'm a member of the Community Working Group, Community Health Team. So, I'm pretty active in Drupal. Kanopi, I'm throwing in the slide because we're hiring, if you know anyone, or looking for a position. I love my job. We really care about community, all kinds of jobs, Drupal Tech leads, accounting, UX project managers, all different kinds of roles because we've done some reorganizing in the company where people have moved forward and we're looking to fill some of those spaces when people get into more leadership roles. So today, this slide is for the whole workshop, so we're gonna be talking about some of these things were mostly going to be talking about why we contribute.

We're gonna talk about how to start contributing to code. We're gonna look at the issue queue from like a thousand view, talk about etiquette, how to create an issue, things like that, and then we'll do some patching and go through the review process a little bit. I do have on here that we're gonna chat about pull requests, but we're not. I'm gonna tell you what they are and then is going to talk about them at 11:30 Central Time. So, why do we contribute? This is a slide I always use. If you depend on open source, open-source depends on you. That's just straight out number one reason we download for free. We find Budd's. It's our sort of obligation to give it back. It prevents redundancy, all kinds of things. And our contributions are really valued. Our developers, who are makers of Drupal really appreciate when we help them out, because all of us have different perspectives. They don't know how different people are using the software. So, it's really important to have the diversity of voices helping out.

Contributing gives you another space in the Drupal community. Not only do you go to camps and meet-ups to see sessions or the hallway tracks, but now you can stay that extra day and contribute on the contribution day. So, it sort of sets you up for having more to do enjoyable. Do you need to talk your boss into why they should pay you to get back to Drupal? Companies who use Drupal just like us, you know, they really, really should give back. I see it as good corporate citizenship. It's the value of helping other ones. And I really do think it's a part of our agency social responsibility to give back to Drupal. But also, like if a company gives back to Drupal, it kind of creates a natural talent recruitment because it's fun and rewarding for us as developers and salespeople and whatever role you might have to work with smart people in Drupal. And it's reflected when potential employees view our agencies page. giving back to Drupal is important to someone looking for a job, they're gonna check out that agency page and see what kind of contributions they are.

And one of the ways that that agency can bump their contributions is if they allow that time on company time to give back. And there's definitely benefits of contributing. And I kinda went through this a little bit. Makes you feel good. We really move our project closer to perfection. We can't ever get perfect, but we can definitely improve because one of our jobs in giving back to Drupal is making it look good. Typos, user interface errors, grammar, all of those things are things that people see when they're evaluating the Drupal projects. If there's a UI with a spelling error or a typo or someone who's looking to maybe build a Drupal or workplace, they're gonna look at that and sort of wonder about things a little bit. So really, every time we fix Drupal, we make it more marketable too. You build your resume by giving back to Drupal. Hold on a second. I have a message. OK. So, you build your resume every time you get back to Drupal and I have a slide that shows us how we do that. And you're more recognizable the more you're in the issue queue, the more people see your name, the more you sort of network, the more you learn and then the more you contribute, the more you learn.

I came into Drupal not having a lot of coding skills, but every time I teach a workshop, every time I create a patch, every time I work in the issue queue. I learn something new. So I like to say I'm a non-code developer, but as I've worked with Drupal these last six years, I've actually learned some stuff. I started in Drupal 7 and now I'm Drupal 8. I understand what a tweet file is. So, the more you're in there and the more experience you get, the more you learn. And then here's that Drupal.org profile and I just use Dries. You can see where he's worked. He's only worked at Acquia, but it was someone else. You would see all the agencies they work for. You have a place to have a bio. You can see documentation credits. You can see how long he's been on Drupal.org. You can see what projects he's contributed to in the last year. And then you can see some code comments that he's made over the years. So like I said, when you apply for a job and contributions are important for that agency, they could look at this page and sort of check you out a little bit.

Types of contributions, again, I'm not gonna go all through each of them in detail, but I do wanna mention some of them, and this is more geared towards that first workshop, but it's really important to know that even in in the issue queue, you can still contribute without ever having making a merger request for without ever making a patch. There are so many ways to give back to Drupal beyond code, and that includes in the issue queue. So, just keep that in mind. Like don't let your non code skills or or not knowing how to make a patch stop you from working in the issue queue. So, I was talking earlier before some people came on, that sometimes that hardest part of giving back to Drupal is actually figuring out what to do. You have maybe two hours a week from your agency or you're doing it on your free time. You don't have the privilege of getting paid to work on it. So, you only have an hour here and there, but it takes 25 minutes to find the issue and it doesn't give you a lot of time to actually work on the issue.

So there's some guides in Drupal and one of them there's a link here is Drupal.org/community /community-guide. And I'll look at this with folks after the slide deck. But it's it's laid out in a way that makes a lot of sense. You can find your role. You can find a task, you can target it on your specific skill area. And then, there's different areas of contribution and they're all listed very clear with links going out to subsequent pages. I live in the San Francisco Bay Area, and I think it's really important to remind folks that our community should really stand against racism. Hate crimes in San Francisco and the Bay Area have gone up since covid, and I just wanna remind folks that. There, that we should stand against racism. If you want to reach out to me in a PM, I can give you a really good resource on bystander training and things like that. It's a really important issue for me. So I just want to hold some space for that this morning. OK, so contribution can take lots of forms. There's documentation guides.

And I'm gonna go over a couple of the documentation guides here because when we get done with the slide deck, I'm gonna like go through how to contribute exactly to documentation because it's a lot easier than some folks think. We can work on translations and localizations, sharing your knowledge, writing contributed themes and modules, event organization, promoting the platform and of course, the issue queue which we're gonna go into detail in a bit. So documentation, when I first started, people said, "Oh you can start contributing back to Drupal by helping with documentation." I thought, well, "How can I can contribute back to documentation if I don't know what I'm doing?" And it really turned out that I was the perfect person to give back, because if the documentation skip steps, I knew because I couldn't figure out how to do it. And it makes sense that you're the perfect person because it helps the next person out. So, if all of us sort of help out with documentation when we renew it, refines that documentation for the next generation.

And there's different types of documentation. There's official guides. These are maintained and held to a higher standard, so there's an editorial process involved with these official guides, but they include the Drupal User Guide, the evaluator guide in the local development guide. There's community guides. This is community documentation that can be edited by anyone. And I'll show this in a little bit. There's a couple of different ways you can do it. You can do it through an issue queue. And if you have the right privileges, there's actually an edit button right there on the screen, which is really handy. There's contributor guides. These are the guys that we're going to look at and how to find tasks, where to go to give back. It really helps you figure out how you can bring your unique skills in perspective and join with others in the community. And then there's contribution guides. These are the form of external documentation or read me within the contributed projects and themes.

And we're gonna actually do a patch in the issue. queue on A Read me. So, we're going to do like documentation but in code form so that that will be the patch we're going to work on today. Translation's and localizations, it's a really good way to give back to Drupal. Sharing your knowledge, giving presentations, training, mentoring, creating, participating in BoF'slike we did yesterday. They do say that sometimes the best way to learn something is to teach it. And I find that true every time I teach a class. OK, so this is why we're here kinda of getting into the meat and bones of contributing back to code. So, what happens in the issue queue? All different kinds of things happen in the issue queue. We report issues. If we have bugs, if we have feature requests, if we have tasks or roadmaps, we create issues in the issue queue. We update issues. Sometimes it takes the form of updating the summary in the issue queue. You visit an issue and you can't figure out what's going on, so you ask for the summary to be updated in the summary gets updated.

You can triage issues. That's the process of going through the issue queue and maybe pulling out issues that are antiquated and old, there's no reason why there should be a Drupal six issue up in the issue right now. So there's triage that takes the form of MIT campus coming up or Drupal is coming up and going through and tagging issues to work on at particular events, we can create patches and submit all requests for issues that are active and open that need fixing. Once patches are submitted, we can provide useful feedback in the form of steps to replicate, steps we did to validate screenshots, testing. There's always a need to write testing in the Drupal issue queue I don't know too much about testing, but Matt Gleeman on Thursday did some night launch review and that'll be up on the mid camp YouTube space. I think. If not, then you can pull in one of the organizers and we'll give you the link. But testing is always being asked for in the issue queue. And then general collaboration, because some issues are ideas and they want people's input on what to give back.

So, you can see there's not just creating a patch and doing a merger request. There's all different kinds of things that happen in the issue queue. Now I'll do a disservice if I didn't talk about they're not two different issue queues, but they are in a way, there's core and then there's contributed modules and themes. Drupal.org is where most code that makes the Drupal site work, including the core project and all Drupal websites run on a version of core. What makes the website different are the contributed modules that are added, and they're often referred to as contrib. And you can pick and choose from a wide range of contributed modules. They add functionality to your site and then themes add, they change your site's appearance. Distributions, provide features and functions for a specific type of site, which includes a single download containing the core software and then some pre-configured configuration when it comes to modules and themes. And really I use the word module. What is a module?

Some people might not know. It's a set of files that could include JavaScript , CSS, and again, that extends your site's features and adds functionality. So issue queue 101, we often hear the word issue queue but what is it on? I like to encourage first-time contributors to start small and work their way up and that can be starting with triage, like I said, making sure the issues are still relevant and that there's enough steps to validate or replicate tagging issues. Again, a lot of stuff I already went over, but there's also applying patches. You know, it's pretty straight. I'm not going to use the word easy because easy is relative, but it's pretty straightforward how to apply a patch and to get repository. And then there's also simply testing me, which is an online browser-based local environment, and I'm gonna give a little demo of that too. We can re-roll patches and we can update summaries and the issue queues too. And what kind of issues are worth reporting? Well, this slide is the same information on the last slide, which isn't true.

But really, the issues that are worth reporting are all of them, because if our software development developers don't know how we're using them, they can improve upon it. They might have a certain story that they tell themselves as they develop. But we all use Drupal differently. We all have our edge cases. So, if you have a Drupal site running and you have, you know views, bulk operations and you have meta tag and you have this and some combination somewhere makes it break, that's important. You might not think so because it's an edge case using contributed modules, but there might be four or five, six, a thousand more people who have that same configuration that you don't know of. So, reporting those issues and having those patches up there for other people is super valuable. And it sort of eliminates that redundancy because you've already worked on it. So, providing that patch for someone else that they don't have to work on it again.

SPEAKER:
And you found and you have a bug, you have an idea, you have a feature request, the first thing we need to make sure is that it doesn't already exist in that issue queue. We don't want to duplicate efforts. So, the first thing we'll do when we start working is I'll show you how to do an advanced search and find if the issue already exists. But if it does already exist, we want to make sure that we update that summary with any changes that might happen. You know, reporting similar findings is super important because it validates that the bug is replicatable. And then for the next people, we want to add steps to replicate and steps to validate as well if the issue already exists. Again, sometimes finding an issue is the hardest part you know try using the advanced search feature. And like I said, I'll show this when we do the demo. The advanced search option really just sort of hones in on everything, and then this is when you open the issue queue the advanced search button is something that you have to select.

And when you select it, it opens up some more choices. And for those that might not be able to see my screen, I want to go over this picture a little bit. You can see here that there are some fields you can use to kind of refine your search. Search for is good. When we talk about how to create an issue, we'll talk about why we need succinct titles and it's for searching. We want to make sure that are our titles are easily searchable for the next person. Say you're working at a cantrip day and you can't remember what the issue was, but you remember who submitted it. You can search by who submitted an issue. You can search by who's following an issue. Your coworkers said, oh, I'm following this issue in Drupal, but you can't remember the issue. That's OK. You know their username. You can refine your search to only issues that need to review. You have some time. We don't have enough time to write a patch, but you have time to review it. You can search by version. So Drupal wants to make it easy to contribute.

As new users, I do have some suggestions on things to stay away from because things can get complicated and muddy really quickly, and sometimes we can just avoid those things. I do tell beginners to pass on contributed projects that aren't actively maintained, and I'll show folks how to do that when we look at the issue, cube projects that have lots of open issues. Now, this can be subjective because you could have something like meta tags that have hundred of issues, but it's also a project that's used on tons of websites, but if it's, you know, one of those sort of obscure modules or maybe it's only installed on a couple of hundred sites, be aware of the issue queue having lots of issues open, that kind of is a signal that the maintainers aren't really active in there. If you see lots of issues in there that were marked, won't fix, sometimes that's an indication that the maintainer doesn't really want a lot of collaboration when it comes to feature requests and stuff. So if you have a feature request, be mindful of that.

Stay away from individual issues with tons and tons of comments. I used to say stay away from issues that have over 100 comments, but other contributors will maybe say 10 for a beginner and. This comes into this next point, these next two of issues that have changed status lots of times and issues with disagreements. So, if you see an issue queue and you see it as an active disagreement between folks, sometimes as a novice, it's best just to sort of steer clear of those issues and find an issue where it's really straightforward. There's one road map. There's one plan and then be mindful of issues that have just changed status, a lot of times it's marked active, it's marked needs review and there's a lot of nitpicking. So that might be an indication that that summary is up to date or it's not clear how to fix that. So as a beginner, just be very mindful and read those comments through before committing that time to a project. So we're going to create an issue and want to talk about the different metadata that's involved there.

We want to make sure this is a screenshot of a picture of the top of an issue, kind of the summary, and what it looks like. You can see that this is a fixed issue on the sidebar there. You can see the version. You can see the component is the user interface. It's a feature request. We can see who assigned it, who the reporter is when it was created when it was updated. But we really want to be mindful of that title. When we create an issue, we want to be descriptive and concise. We want our title to not be aggressive or accusatory. We want it to be straightforward and nice, the category, is it a bug report? Is it a feature request? Are you asking for support? These are drop-downs priority know you can select critically. Your site is White Screen of death or you know, you just can't get anywhere. That might be a critical bug, a major-minor or normal. The status is important you know when we create an issue. We usually just leave it as active. But as the issue queue, as the issue moves around, someone submits a pull request or a patch.

So the market needs review, someone's reviewed it, the patch needs some work. So there are all different kinds of status changes that can happen in the life cycle of an issue. A version is important when reporting a bug because not every version might have that bug. So if you're using a contributed module and it's 1.2 to put, the bug isn't on 1.3. We want to make it clear what version of that bug is on and component. This drop-down varies across projects because the maintainers have the ability to add what components are worked on. So you could see a component drop-down that's very sparse. It might say code documentation, user interface, and tests. But another, if you ever open up the Drupal component, it's a mile long. You've got all different kinds of components. You have Ajax, you have JavaScript. So this will vary from project to project. And then tags are used to help people search and we'll create a tag when we create an issue. And then the summary again, the summary is really important.

Within the last six months, they've gone back to injecting a template into the issue queue which is really nice. It gives us some headings and reminders of different things that we should report when we fill out an issue. So here's what that looks like in the user interface. You can see most of this stuff is required. So I'd remind you if you forget to fill out one of these fields. This is for an issue if you want to create on Drupal.org itself, the website, so you can see the component list is rather short. You can see that issue tags are a field, and that's an autocomplete field. And I don't know if I'm going to mention this later, so I'll mention it now. Issues, tags. The issue tag you're looking for is 98% guaranteed that it's already been created, so be very mindful when filling out this issue tag on the field, let it autocomplete, and see what comes up. About a year and a half ago, they went through the tags and they found, like, I'm just going to throw out an example. Accessibility was spelled wrong three times.

So don't try to create your own tags. Just let them autocomplete and the exception might be when we tag for an event like midcap 2021 the first time. That tag didn't exist, so we had to write out midcap 2021, but now it already exists and will autocomplete for folks. And just make sure you use that template that's injected, there's problem motivation, there's proposed resolution, there are remaining tasks, there are UI and API changes and there are data model changes. And it's OK that you don't know what all of those mean. I do. I don't typically use the last two that I've listed. I'll delete those or I'll put non-applicable. And that's steps to reproduce and the I want to clarify a little bit, we really want to make sure that we give enough context. The person who's reviewing the issue or creating the patch, you know, gives you URLs and breadcrumbs. Just be very clear with those steps to replicate that way. There's no question as to what the problem is. So tooling and documentation, these are mostly links and just some ideas to throw out folks that these things are available for us.

Again, Randy's available in the general cantrip space. He will help folks if you want to get Drupal up and running on your local machine but some useful tools, of course. Drush, of course, is very useful. Git you don't necessarily have to know. Git but writing a patch and reviewing a patch, using it again is pretty straightforward and get for those that might not know, it's a version control system composer. It's a dependency manager. We should all be using composers for Drupal eight, nine, and 10. So get on board with getting that installed on your machine and then just having a basic text editor or IDE. You don't need an IDE. There's a learning curve that comes with it. You can start out with the basic bare-bones editor like Beebee Edit, which used to be text, Ringler. But then there's like the kind of like halfway in between, like Sublime or text mate or Adam. And then you can like, you know, if you really need that ID with that integrated development environment, there are tools like PHP Storm and others simply test me again.

It's an online service that provides on-demand sandboxes. You can test modules without a remote version of Drupal. Using this tool, you can also test any patches using advanced options. You get the screenshot, you can see there are advanced options, but you can't see the bottom, but you can add a URL BUT test a patch. Important note when you use simply test me right now, it doesn't always work. We are actively working on the project. We are getting it up and running on the tugboat framework. And we met Glayman's, been helping us out and he's been doing this really neat sort of streaming. He works in streams working on simply testing me. I think he does that every other Sunday, but be mindful that it doesn't always work. So, I just want to point that out to new beginners, but we are working on a more stable version and hopefully, by triple come, we won't have to say that it doesn't always work anymore. Details for simply test me. You click on a button, it speeds up the sandbox, it pops open a Drupal site, you come into the login screen.

That admin, admin is your username and password. Just so everyone knows that you're like, Oh no, what do I do? It's admin, admin and what's nice about simply testing me is it provides a URL. You can share that your URL with someone across the country, across the continent, across the globe. So if you like, mock up a little website and you want to share it with someone like you're doing marketing or you have some configuration that you want to share, that your URL is shareable, which is super nice. TugboatQA, it's automated on-demand deployment, it's previewed in the issue queue it was just in core, but I think maybe last week or two weeks ago it's now available in the Cantrip issue queue two. So this is very exciting and what this does, it's the previews really accelerate development. It automates the environments and kind of bridges that technical divide and brings the ability to review changes to more users in the issue queue and Mark will go over this a little bit more, but Tugboat reduces frictions by making the changes visible.

So if you don't have that local environment, you can use the tugboat preview system in the issue queue. Dreditor is in all of these slides are wrong, I apologize, but Dreditor is an extension for Drupal that enhances the user experience and functionality in that issue queue. Dreditor is short for Drupal, Editor They are not actively maintained, but when we do the demo, you might see some buttons in the issue queue that you don't see on your own, and it's because I use this Dreditor extension and I think it's only available on Chrome and sometimes Firefox and then here are some useful links, slash doc slash documentation, there's API.drupal.org/community. You know again, guides are pretty much for everything. The API guide allows you to search the complete API for Drupal and for those who might not be familiar, API stands for application programming interface, API application programming interface, I don't say it enough to have it roll off the top of my tongue, but the API includes things way back before Drupal five through the current version.

So if you're working on core code and you want to start developing modules, it's sort of an indispensable link for you to have. A community is the community hub. There are all different kinds of things. There's the working group, Core Governance, Security, Working Group, Technical Working Group, these documentation pages around the community. And there's also it was called the Getting Involved Guide, but it might be called Contribution Guide and we'll look at that. The name just recently changed. So I'm unclear what it is and then you know Drupal stock exchange, if you're a developer and just want some nice forms to look at, Drupal Stock Exchange is very valuable. Oh, I also have two flagship projects. Drupal what that is is that's triple-core. But I want to share the naming convention because when we talk about contributed themes and modules, it follows that naming convention. It would be Drupal Projects, Drupal. org project bootstrap paragraphs. So it all follows that naming convention.

And I'm going to go kind of step by step before going into a demo, just to sort of show that the process is straightforward, there's not a whole lot of steps involved. So the patch process really it down to you have a problem. You file an issue, you make sure you provide all that metadata, you. Well, sometimes to patch the issue already exists, but once the issue exists, you download the repository onto your machine, you create a new branch and this is the patch process. You create a new part of branches. You make the changes on the new branches. You compare the two branches and provide a file and that's creating a patch and then you upload the patch to your dog. So I'm just going to say that one more time, really simply you find a problem, you file an issue, you download the repository on your machine, you create a new branch, you work on that branch, and commit your changes. You compare the two branches to make the patch and you upload the patch to the dog. So that's the process in a nutshell.

The review process looks very similar to the patching process, just a little bit differently. You found an issue that has a patch. You download the repository onto your machine, you download the patch. That's a little bit separate process, but pretty straightforward. You apply the patch. The two ways I'm going to show today is using simply test me or you can apply it locally in your get repository. And then you if you have a local environment running, you would review the user interface. If It's a user interface patch. But say it's just like the read me like we're going to work on you would look at the code and review that and then you would provide useful feedback. So again, download the repository, download the patch, apply the patch a couple of different ways, review the code and then provide useful feedback and you change that metadata depending on that. I wanted to show a little bit of a picture of Ed because this is an extension that really helps new contributors. It's got a few different bonus features which are really nice.

It provides a color-coded file. How wonderful is that? Because if you do review a patch on your blog, it's usually just white with text, or however you have your settings in your browser with just pluses and minuses. And it's really hard sometimes, especially if that patch is over, multiple files to review all of it. But when you have a predator, it provides that color-coded green lines have been added, red lines have been removed. So it makes it really easy to review code. It also allows you to use a dialog box. So if there's there's a piece of code like, say, line 18, that doesn't look right. I select row 18 and this dialogue will open up. And in that dialog, it allows you to enter code comments so you can say line 18 has an extraneous space at the end of it and then you would hit save. And then when you go back into the issue, queue your code comment is injected in the next comment for you. It's a really handy tool and I'll show that. And then again, Mark is going to be showing this at 11 thirty, but issue Fork's and merger requests, again, a pretty straightforward process.

It emulates the work process that we use on GitHub. If you're a developer and use that work workflow day to day, you create a fork, you get push access, you use Git branches and you commit and push changes pretty straightforward. I do not use that development workflow, so it's not straightforward for me and it might not be straightforward with how you collaborate in the issue. queue and that's what Mark's going to go over with us. And I just want to note, I'll just read this for ADA. While project maintainers may not require patches and can handle merging and testing themselves with git remotes. Non maintainers trying to test an issue can still be greatly helped by a patch file. Patch files also allow for faster delivery of changes across multiple test environments. And that's straight from an article on drupal.org. And that's why we're still teaching this patch process a bit. And that's the end of the formal presentation, so we'll move into a demo now. I am going to take a couple of drinks of water.

I do want to just mention that Midcap is always the camp right before drupalcon. So we like that people come and get acquainted with how to do the patching and how to do the merge requests and get their local environments up and running. So that way when Drupalcon starts in a few weeks, we'll be ready to go. And Drupalcon this year is going to be a little bit different in regards that there's a huge focus on contributions. So Drupalcon days are shorter. It's four hours of your traditional session in content delivery and keynotes in the morning, but all afternoon, each day of the week will be initiatives. So, not only will they be working on initiatives, but other contributions stuff too. And I do want to let people know that you do not need to buy a Drupalcon ticket to participate in the code contributions. It's a separate entity. We're working, I think on Monday, the commenters are getting together and we're going to work out what the platform is going to be like. So there'll be more information next week on the Drupalcon website about how to participate in the contributions.

But I do want to stress, you don't need to buy a ticket to contribute on contribution day. And little known fact, you don't need to buy a ticket to go to Drupalcon when it's in person to go to (UNKNOWN) day. You can still go to a facility that's hosting Drupal Con and be able to contribute at that, in those contribution spaces without a ticket. So, be mindful of that, if like the 800 dollar ticket, when it goes back to real life is that barrier. But you're really into contributing, You don't need that ticket. You can just go there and contribute and hang out and do all of those fun things. You just don't have access to that session delivery. OK, so that is the end of the formal presentation. So I'm going to hit stop share and I'm going to breathe and take a drink. And I have to answer a slack and then I'll do a little bit of a demo. We do have a core mentor in the Oliviero room. So when we're done here, if people want to, Oh OK, that's a private message. I didn't seee that at all. OK, so after this workshop, there's the merge request.

But if you want to stick around and see Markis, OK, I'm talking too fast. I just said the same thing twice in my brain and once out loud and I don't know where I am, so I'm going to reset. After this workshop, there will be the merge request, but Randi from DDeb will be around all day in the general contribution room for local environments. And then Matthew, who's a core mentor, is in the Oliviero room, if you want to take on some novice issues, working on the Oliviero theme, which is now in core. So there's a space in that Oliviero room if you want to kind of extend what we're going to go through on the demo and Matthew will walk, I don't want to say hand in hand, but he's a really valuable resource, a really good teacher on helping us figure out how to do it on our own. So, we're going to close some tabs because it's embarrassing. And I'm going to share a different screen now. And I am going to share a screen which has my notes. So, this is a no judgment zone, everybody. I just want to say that out loud, because my notes aren't always written in a way that other people understand.

But I understand. And sometimes it's easier to have my notepad open and show folks what's going on because we all make mistakes. We all do things a little bit differently. And it's been known to happen that I forget one step of the process. And so me going through it, having my notes open, is an honest look at how we do things. And it also allows collaboration and troubleshooting if something goes wrong. OK, so let me share my screen, I'm a big fan of troubleshooting because you never know what goes wrong. And so if you go to a workshop and something goes wrong, you're like, oh. Then if it happens to you, you're like, oh, we saw that in the workshop, I know how to fix that. I used to be really self-conscious when something didn't go right. And then I realized that all of those are really good learning opportunities. Just have to switch your mindset a little bit. OK, so I'm going to share my big screen. OK, so here is this contributor guide and I'll put the link in the chat. This contributor guide is sort of a real good diving board when maybe this is your very first time or you're relatively new, haven't done a whole lot, it kind of breaks things down by task, you know.

We can look at one of these just, for example, find a task. The filters are pretty nice for experienced event planning, temporary, you know. Some of these still need to be fleshed out because this is a new set of documentation. But, you know, it gives you a different idea of different things that you can do. Like create a patch for an issue. Then it gives you specific instructions. So, that page I like to suggest to people to look at when you have like about an hour to sort of learn and kind of do that bumper car thing where you go from link to link and just sort of bump around and explore the set of pages quite a bit. It's very interesting and intriguing, all the different things there are to work on. We're not going to go through too much of it just because I just want to point out that this exists and it's a good resource. OK, so what I want to do is I want to find a bug because of time and whatever, I already know what we're going to do. I help maintain this march or march module.

And if I spell that right, that would be fantastic. So this (UNKNOWN) module, I'm going to go through what a project page looks like again. You know there's Drupal.org/project/smart trim nomenclature for finding a project page. So, here and when we look at some of these pages, if you follow along, my pages might look slightly different just because I have, I might have an extended privilege or something like that. So don't think there's anything wrong with your browser or your account or anything. I just want to let folks know I might have a different tab or I might have a different edit button that other folks might not have. So the smart trim module, this is the project page. You can see that they provide a description of the module. You can see who helps support it. You can see how many sites are actively using this module. That's pretty good data, if you're reviewing a module to use on your deceptiveness, reviewing a module for your own website and project. On the side block, you can see when the last comment was made a month ago.

So this is an actively maintained project. You can see there's a link here for the issue queue. It gives you some statistics and each of these project pages have these documentation. If there's an external documentation guide, you'll find links here. There's resources, there's this development column. And this is pretty handy because there's a link to view the code repository. So you can view the code repository on git lab without having to download it on your machine. So if we want to look at that, we can go in here and we can kind of poke around and look and see what this issue or what this project is all about. I just want to show that little thing. You can see down here that there's a Drupal seven version and there's a Drupal eight version. And we can see that it was last released in May of 2020. But we can see from over here that it's still being actively worked on. Remember I talked about trying to keep to actively maintained modules. So, if I select this here, I'm taken to the issue.

Q The issue queue, and I'm going to give kind of a broad 1000 foot view of the issue queue. The issue queue you can see is sort of color coded. It can also, for those that might not be able to see the colors, the colors relate to the process, where the issue is in the life cycle of the issue. So, you can see there's needs review, you can see there's active some are postponed. You can see when it was last, when the issue was last updated, when it was created. Anybody who's assigned to it, what version? So this is a great way to just sort of scroll. If you don't want to take the time to scroll, you can click this advanced search issue or link, and it opens up that advanced search function that we saw. Again, say we're looking for issues for mid camp. I'm going to create mid camp and I'm going to look and I can search the issue queue for mid-camp. It looks like the documentation guide is tagged for mid camp. I don't want to work on that, but that's how you would find, like if you're going to go help with the Oliviero theme, you could search the core code base for Oliviero.

You can select the category and you would hit mid camp and you can see all the different issues that people are working on. But we're going to reset this. But what we're going to work on today is we're actually going to, we're not going to do the whole thing. I'm just going to do the patching process really quick just to show what it's about. This read me, and I know because I have the experience behind it, is not Drupal standards. This readme provides information, but we really want contributed modules and themes to follow the red me template guide for that specific version. Because, when people evaluate our projects, they want to go to a red me and expect the same information in the same layout as the last project read me they went to. Consistency is super important. It's a coding standard. Just because it's documentation doesn't mean it's any less of a coding standard. So I do have a link to the template page. And what this does is it basically just kind of goes through and shows you what the template supposed to look like.

We can see, sorry for the scroll, they're supposed to be a table of contents, an introduction that provides some useful information about what the project's about. If the module requires anything beyond Drupal core, if there's any recommended modules that work well with it ,installation processes, you can see there's a different link for Drupal seven than Drupal eight. You should provide a configuration section, an optional troubleshooting section and then the maintainers section. So, if I scroll down here, here's an example of a read me, what a read me supposed to look like. So, most read me's on Drupal.org across Drupal.org or Drupal core and contributive projects follow this format. We can see that table of contents, we can see all the different things. But if we go to our smart trim module, we don't have any of those. So what I want to do is I want to start the template for somebody else. So I'm going to create an issue about bringing this up to coding standards and then we're going to create a patch and we're not going to finish the whole read me, but I'm going to start a patch just so we can see the process.

And then I'm going to mark it needs work. So the next person who comes in can download that patch, which is a template and work from there, straightforward. OK, so if we remember back, we found an issue, so we want to create an issue. So first thing we want to do is go back to that issue queue for smart trim. And remember, we want to search to make sure it doesn't exist. So we're going to use some keywords. So I'm going to use a keyword, read me. These are closed, so I'm not going to look at those. Documentation guide, that's not the same documentation guide as external. It's not internal within the project. OK, something else I might want to search is documentation. So if I search for documentation, we don't see anything,. So I'm pretty confident the issue doesn't exist. Remember, that's the first thing. Make sure it doesn't already exist. So now that it doesn't already exist, I'm going to select this create new issue. Be very mindful if you're reporting a security issue, you do not report a security issue in the main issue queue.

Because that alerts everybody that there's a security issue. So there is always a different process and procedure for security issues super important. OK, moving on, or is this not a security issue. So we're going to have a short, concise, not accusatory title. So we're going to say, read me does not follow Drupal documentation standards. So we've got two keywords in there that I searched for, read me and documentation. The project is smart trim. That auto populates for us the category. It's a task. The priority, it's minor. Let's not fool ourselves. It's not super important. It's important. I'm not going to devalue documentation. Documentation is important, but this is a minor issue. We're going to leave it as active. But you can see as you work through issues, the different statuses that are available are version. We're going to select the latest version. We're going to select the development version because we want them to move forward with this. If it was a bug, we could select which one.

But when you're really doing a feature request or updating a coding standard, we want that to get into the development version component. This one is documentation. It's not quite code. It's not an external documentation guide but it's documentation. And sometimes you might not know where it fits. Just sort of use your best guess because the next person can update that issue. Remember when we talked about triaging issues? This is something that people can go back in and update if they see fit. Assigned, if you are working on core, please don't assign yourself an issue. But if you're working on Cantrip, you cannot, I'm a maintainer of this project, so I see other people's names, but you would just see your own. I know for a fact that in the next five minutes I'm going to be working on this, so I'm going to assign it to myself, OK? And that's sort of the guideline. Are you going to be working on it? Issue tags? I'm going to add a couple. I'm going to add documentation. I'm going to let it autocomplete.

I'm going to add the novice tag because this is for beginners. Allow it to autocomplete. I'm also going to add the mid camp tag because we are at mid camp and we like to track what we work on in mid camp. So we're going to do the mid camp 2020. I do see that I'm at 9:10, so please allow a little bit of flexibility. We're probably going to go over that 11:15 mark, so forgive me.

AMYJUNE HINELINE:
Can I interrupt you, sorry. Just a quick question. Did you say for core issues, don't assign it to yourself?

SPEAKER:
Typically not. What I would do is I would in a comment because when we work on issues, best practices is to review the comments that are happening. So I would, if you're working on an issue, I would make a comment that says I am actively working on this issue. Here is what I am doing in the core queue. That's what I would do. Because core, I've been told that it's more about the maintainers assigning it to other people, like once it goes from like it needs a patch to a needs a test though, or if it's like a UI component in someone's designated to work on that specific component or initiative, they'll assign it to that person. That's my understanding of the assigned feature in Drupal core. So, but I like to do this in, my fear is redundancy and replication of effort. So that's why I always assign myself. And then also to tag on to that, if you get lost and you have a fire at work and your kids are out of control and you can't work on this for a few days or a week, go back and unassign yourself and make a comment that says, I'm assigning myself.

I just whatever, didn't have the time. This is what I have so far. That way that helps the next person. Because when you assign yourself, people can be like, oh, I'm not going to work on that because someone else is working on it. So be very clear in your comment, what you're doing, who you are. Just, you know, it's all about collaboration. And sometimes the only Documentation for the collaboration is in the issue queue. So, just be very transparent. So, I'm going to grab that link to the template, snag it. And I am going to problem the motivation, README does not follow documentation standards, please visit this page for the template steps to reproduce they aren't really applicable here because it's just in the README, there's no user interface. But if there was a user interface then make sure you have I selected configuration, administration, breadcrumbs, and all of those steps. Proposed resolution, provide a patch that follows the template, remaining tasks, we're going to say we need patch and review.

User Interface changes there's none, API changes none, data model changes, none. And feel free to delete those if you want. Feel free to delete the whole summary if you want these are sort of just easy reminders for us to what we should include when we report an issue. I'm going to come down here, parent issue if it's a bigger issue and this is like a little sub issue. Say there's something related this is where you would put the URL for those issues. Files that's more like if you had a screenshot, if it was a user Interface thing you want to provide a screenshot of the bug. Say you're doing collaboration later and you have a text document you want to share it, that's where you would upload the file. And we don't want to change any of this other stuff. So, we're going to look one more time just to make sure we have all of the things. And I'm going to hit save. So, what this does is it creates a unique node on drupal.org. specific to this. So, we can see that there's this unique node number.

That's valuable to me and I'm going to use that in a little bit. So, I have a note pack. That's not it. I also have a Zoom window that is in the way no matter where it is. So, I have that node number which I want to say because we use our naming conventions for patches, rely on that node number. OK. So, we created the issue. And remember our next step is we want to download the repository on our machine. We want to create a new branch, work on that new branch and then create a diff file. So, let's do that. So, if we go back to, I'm going to close some of these because tabs, but not that one. We want to go back to the smart term module. And we want to download the repository. And remember on that project page we can go over here then we can view code repository. But if we go over here to this version control tab and select it. What that does is it's some text that lets us know how to download a repository onto our machine, how to create a patch, how to do a couple of different things. So, that version control tab is super handy.

It's like a little bit of documentation that's always there on the project pages for us. So, setting up the repository, I am going to snag this command. I'm going to open my terminal and I need to find it. So, here on my terminal, I'm going to make sure I am someplace safe, pwd is present working directory, you can see where you are, I'm going to change directories, I'm going to go into my desktop because my desktop is fairly clean. So, it's going to be easy for me to find this stuff. So, I'm going to go into my desktop. I'm going to snag this command. I'm going to paste it in, hit return and what that's doing is it's cloning the smart trim repository onto my machine, onto my desktop. And then the second command cd smart trim changes that directory and now I'm in that repository. So, if I do that pwd, present working directory, I can see that I'm in my desktop in the smart trim window. OK. So, that next step is we want to create a patch or I mean create a branch. So, what I like to do is I like to name my branch how I would name a ticket and that issue number is a ticket number in a way.

So, I'm going to create a branch with that unique node number dash two. And that two is the anticipated comment number where I'm going to paste this patch. So, if I'm working in the issue queue and the next comment is three, I would put dash three. If the next open comment is four, I would put dash four. So, it's the anticipated comment number where you will paste the patch. And it's okay if you don't name your branch this way. You can name your branch anyway. But I named my branch because I'm going to name my patch the same thing. And you know what, if someone goes in and writes another comment it's really easy to change your file name. So, this isn't set in stone. But this is the normal naming convention for patching is the issue number and the anticipated comment number. So, with that being said I am going to create a branch. And I copy and paste because I don't work in the issue queue every day, let's be honest. And I'm already lost because I have too many tabs open. So, I'm just going to keep this training tab open.

I'm going to go to my issue, I'm going to do get checkout dash B because that is how I create a branch. I am now on a new branch. So, I'm going to open my text editor which is sublime. I am going to do open space period. And what that does is it opens my present working where I am in my Finder. And what I can do is I can just drag this into my sublime. But I have too many screens in the way. I drag it into sublime and it opens it up. So, we're on that new branch. We're going to look at the README. We're going to look at that README template. We're going to see that we need a table of contents and stuff like that. For the sake of brevity I have already have the template up. So, I'm going to copy and paste that. I'm going to go into my sublime. I'm going to absolutely change everything because what this is is it's example on how to create a patch. You can see I filled out the template pretty nice. We have the table of contents, we have a blank template so people can fill in this information.

We can see all of us in brackets for things that people need to do. I've started the configuration for people. So, this is going to be like a Drupal Ladder project. So, we're going to put this patch up on drupal.org. And then the next people can work on the README. Does that make sense? So, normally you would supply the whole README, it takes about I don't know, half an hour, an hour, hour and a half depending on how complex the module is to create a README from scratch. But we're not going to do that work. And because me and Mark maintain this module. We're okay with it being worked on incrementally on these contrib days.

MAN:
You probably put your name in there too under maintainers.

SPEAKER:
Well someone else can do that the next time.

MAN:
OK. That's actually a good. That's a good, I'm glad that you actually created this ticket. So, now I have a ticket to do my talk on.

SPEAKER:
That's why I did it, actually.

MAN:
Otherwise I would make a dummy ticket.

SPEAKER:
So, that's why I did it. It's for the ladder. And we're going to go a little bit over Mark because, okay because I talk a lot, but you know that.

MAN:
Oh, I know.

SPEAKER:
So, we have this template up now. Like I said if we were really doing this, you know, in real life we would make sure we fill on all these things, we would test the links. We would open it up in simply test me we would make sure that the configuration process is right, but brevity. So, we're going to hit save. And now what we're going to do is we're going to create that patch and remember the patch is the difference between the two branches. So, we had that first branch we downloaded and that second branch we created. So, if I go into my notes, we can... Is that the same number? Yeah. OK. So, I have my naming convention right here. So, our naming convention is the project name. So, we're gonna do smart trim. We have the fix which is a short description and we're gonna say, read me, we're gonna do issue number. Sorry, we're all over the place. We're gonna do that anticipated comment number. So, here's what we're going to name the patch, we're going to name it smart trim which is the name of the project if you're working on core that would be Drupal.

That is really for you. So, if you work on different projects from time to time it's a quick way, like if you keep things in a patch folder it's quick to identify. It's just for you to reference later. And then that short description which is read me, the unique node number, dash two dot patch. Now a dot patch file is the same as a dot diff. So, that's our patch name. So, knowing now we're going to copy that. And we're going to create what we're going to do. And this is copy and pasted. So, I'm going to explain this, we're going to do a git diff. And we're going to have the first branch. And if we go back into our terminal we can do get branch and we can see the name of our first branch. So, I'm going to copy that. And then we see the name of our second branch. So, what I want to do is I want to create a file that compares the two branches. But I've missed a step. Does anyone know what that step is? I need to commit my changes to the repository. So, for those that might not know, git is version control.

So, you need to make sure that you add it to the Git repository. So, what we're going to do is we're going to do a git status, and make sure there's changes Yes we've modified the ReadMe. We're going to do a git add, sorry, (INAUDIBLE) period. He says never do git add period. But this is only one file, what a period does is it adds all of the files. We're only adding one. So, period is safe. So, we're going to git add period, we're going to do a git, commit, dash M. And I really do suggest that you follow your muscle memory and do your commit messages the same way you do everything else. And for me, it's the ticket number. And the change. And will spell fix. OK. OK. So, we're going to commit these changes, we're going to do a git status just one more time because that's the sweet spot. Right. Git statu, and we can see that our working tree is clean. So, we have a clean repository. So, now we're going to do that diff between the two files. So, we're going to like to say this a lot of times for for just memory.

A git diff is comparing the two branches. We have our first branch, the eight branch. And then we have our branch that we created. And we're going to put it, we're going to write it into a file that we have named smart trim, dash ReadMe dash issue number. So, at smart trim ReadMe that unique node number are anticipated. Comment number dot patch. So, I'm going to copy that. Put it in there. And then hopefully, there it is. And what I like to do is I like to look at the patch to make sure it's not empty because I am notorious for uploading an empty patch. So here's our file. It looks right. You know, we took out all that information, you can see what we've added. So, now we're going to go back to our issue queue. We're going to indicate that we want someone to review our patch. I am going to unassign myself because best practices is you don't review your own code. And I'm going to make a comment that I have uploaded a patch with only the template. And because I am not a novice, I should not be working on this issue, I make it very clear that I'm in a first time contributor workshop doing a demo for transparency because we really want novice contributors to work on novice issues.

So, if someone goes in there and says, well (INAUDIBLE) has 10,000 commits what's she doing writing, you know, doing a review on a ReadMe? I like to provide that clarification because really that novice tag is really for novices. And with saying that if you're a novice and you're working on that feel free to tell people in the issue queue, this is the first time I've ever reviewed a patch. This is the third patch I've ever submitted. It gives you a little bit more grace. I hate to say that but it allows maintainers and people to collaborate to know that you are a beginner and they'll really help you out. I am demoing the patch process at mid camp using this issue as a learning project. OK. And then if I scroll down you can change the summary if it needs to be changed which we don't need to do, we're going to add our file. And remember we just put it on our desktop, we did smart trim. And there's my file. Here's another way to kind of review and make sure it's not empty before you upload it.

We're going to hit open, upload. You will not see this line here. But what you will see here attribute this contribution. If you're volunteering your own time select the box, if canopy is paying for you, you select this box that kind of is just a metric for drupal.org to see how people work on the issue queue when they work on it and who's paying for development. So, be mindful that that's available. And I kind of review it and I hit save and now spins a couple of times. And it's changed the status to needs review. And just quickly before marquee starts I want to show that dry editor added these buttons in my issue queue. If I was to regularly look at this issue or this patch it would open up a really hard to read patch. Right. And how I opened that was I right clicked it. If I wanted to save the patch on my machine, I would just hit Save As. Going back here that dreaded or button, it opens up in a color coded diff file. If I wanted to make a comment, I select the thing, I write needs work.

Hit Save, hit paste. And now that second or that third comment injected what I wrote in that window, which is super handy. Back up here creditor also allows a simply test me button. And what that does is it opens simply test me and it pre populates all the information for us. We're working on smart trim. We indicated we wanted to work on the diversion. It pre-populated that patch. But say you needed to add another patch, you would just hit add a patch. You go back to that patch URL and you snag that, obviously it's the same one. So, we wouldn't do it. But that's how you would add another patch. And then you just hit launch sandbox. It may or may not spin up, we'll have to see. But I'm going to let Marquis take over. So, just to iterate you know, what we did was we found an issue, we created an issue on drupal.org. We use that version control tab and we downloaded the repository onto our machine. We created a new branch, we made some fixes. Committed those changes and then we compared those two branches to make a diff file.