"Your First Django Contribution" with Sarah Boyce

Hello, my name's Sarah. I'm a Django Fellow. I've been in that role since uh I think April last year or something. And that means I'm one of the uh paid contractors to help maintain the Django framework. So um I am often on tickets and doing PR reviews and and I'm one of the people that will be merging the contributions into Django and doing releases and things like that. And what I want to talk about today is your first Django contribution. So This is very much advice that

I would have found useful when I was getting started, and it was very biased to my own personal experiences I hope you find them useful, but we can always have a discussion afterwards about different strategies, different techniques and things like this, because I appreciate not everybody is. me. But let's let's go for it anyway. So this whole presentation has the assumption that you have decided that you want to contribute to Django. So you've thought about it and you've gone right, okay, this is something that interests me. I want to start contributing to the Django

code base. And the first place you might end up when you've made this decision is probably track, which is the issue tracker for Django. So we're not using GitHub issues In fact, Django is older than GitHub itself. So we've been using this tracker for a really long time, like nearly 20 years. And that's where our tickets are all stored. And you go there and you see, wow, there's like over a thousand tickets in here. And perhaps you open a ticket and you go, oh wow, this has been open nearly 20 years. And then maybe you go to the pull requests and you see that there's a roughly like Like 300 open pull requests.

Some of them have literally hundreds of comments. And then you go to the forum because this is where people like discuss the development of Django, and there are lots of discussions going on there with lots of people engaging. Some people are even like minor celebrities and all this kind of stuff and you go, wow, that's that's intimidating. And generally you go, oh my god, how do I do this? This this this is a lot. And I was like this as well when I first started. My very first comment in track was I was wondering if this is being worked on, or if I could try to pick it up. Happy to work on it in a group as well. Which is not the comment from a confident

person who knows what they're doing. So contributing to Django, it's not easy, and I'm not going to pretend that it is easy. It's certainly there's a lot involved in this process. But it's not impossible. I think everybody here will be capable of getting contributions into Django. It's just going to take some persistence. And the first piece of advice I would have given myself is there is a contributing tutorial. And I know everybody who's part of DjangoNot space will have already done this tutorial. I do really believe this is a good preparation for introducing you to some of the processes and stuff that we have in Django.

And to make sure that you've gotten prepped and you've got the uh, you know, you've got it all locally and set up and you're running your tests, etc. So Step one for anybody would be please go through this tutorial because it will it will take you through a lot of the of the stuff that you will need to know anyway. And so how do we get you from this overwhelmed feeling to actually getting something into Django? And One of the first steps that makes people really struggle is finding a ticket. It is tough. And it's tough because this is probably not a tool you are familiar with

a track. I mean There are a lot of tickets there. They don't sound very easy. And it's very difficult to know what you can start with, what you what you probably shouldn't start with. And to give some background, there are states of tickets. So when someone creates a new ticket in track, the very first state it will be in is unreviewed. That means that it needs somebody else, it can't be that person, to check the ticket and see if it's basically valid or not, or something we want to do in Django or not. And this usually this process happens fairly quickly

and the ticket will either be accepted or it will be closed. And this is important because if you randomly go on track and you just pick the first ticket. There's a good chance that first ticket has not actually been reviewed yet and it might just get closed very quickly later. So don't just grab the first one off the list necessarily What you want to always do is filter for accepted tickets because anything that is not accepted We don't actually necessarily want contributions submitted for them. So always filter for accepted tickets When you once you apply that filter, there is still nearly a thousand tickets. Okay, it's a little bit less, but

at least now you you see stuff which we actually would welcome contributions for rather than some stuff that perhaps it's just not ready yet. The next tip is really play with track because there are quite a few features in there that you're That you can use to your advantage in order to make this tool work for you. So one of the ones that people are probably not aware of is you can actually group results by something and so I like to group my results by a component and part of the reason I like to do this is Normally when you look at the list of issues, it's just in like

the most recently created ones of first. And then the order tickets are less, right? So it's completely random. Okay. And you will get whiplash reading the different ones about the different areas of the code base. And this will just give you a little bit more of some structure around skimming the different tickets to see what is interesting to you. And the other reason this is useful is because. Common advice is to pick one component, okay? And if you're starting straight away, you're probably open to contributing in a lot of different areas. So you perhaps don't know a particular area you necessarily want to specialize in yet.

So I quite like this as an in-between, but you can still have some some structure so that you can uh see a group of tickets that are similar um but uh you haven't like completely narrowed your horizons just yet That 's one tip. And then uh okay, we'll go to this one. And then mostly when you're looking at tickets What I would do is I'm checking for reasons that I don't want to do this ticket. Okay. And it's easier for me to find To rule out tickets rather than to say this is definitely a yes, because nothing is definitely a yes

for me. Everything is a bit like, uh And so that there should be reasons why you don't want to do a certain ticket and then you can like look on look at something else until you have some, until you have a list of maybes. Okay, these these are the ones you maybe want to do. So red flags is the ticket being actively worked on. Okay. So Is it has it been assigned to a person recently? And when I say recently, recently in Django, you need to appreciate that it's a volunteer project. It's not super active like it would be in a workplace. Recently is like in the past couple of months. What has there been

Someone grabbed it in the past couple of months, for example. Is there a PR that is attached to the ticket that's had a review, et cetera? If there's been no activity for six months on that ticket, then you can say it's free. If it's a a reasonably new ticket that was never assigned to a person It is also free. So try to avoid anything that's being actively worked on. Is it like 10 years old and has loads of comments? This is a sign. It's probably tricky and maybe not the best choice. So if you're Whenever you work on a ticket, you need

to become the world expert of that ticket, that you understand it better than anybody else who's who's Been working on this ticket before because you've read every comment about the ticket, every previous PR, every previous comment on it. And the older it is, generally, the more information there is for you to process There will have been more voices on the ticket comments, on the other PR comments, etc. And So I recommend like a bit of a sweet spot of something that is perhaps a couple of years old but not a decade, for example Does this require a setup I'm unfamiliar with?

So some tickets are database specific. They might require an Oracle setup that you don't know how to do. They might require something like this. that's going to be challenging for you to to to do. Perhaps it's to do with async and you're not comfortable with that, etc. You if If the setup sounds really complicated for you to replicate the issue, it's probably not worth that effort. So I would skip it. Does the ticket require a community agreement before it can be progressed for a

A new contributor, I would say this is a big red flag because this requires quite a lot of goodwill and energy and persistence And you also need to appreciate that at any point, if the community decides it's actually we shouldn't do this That's also like a good conclusion kind of thing. Like it won't necessarily lead to you if you if your goal is to get uh code into Django, this this is going to be tough uh because you need to really engage with pros and cons of of different approaches and solutions and stuff and uh Because the community is all volunteers, there will be large gaps between you get

any feedback on this kind of stuff. So in my opinion. Don't choose those tickets if you're just getting started. That would be really challenging. Okay. This particular view is my preferred way of trying to find a ticket to work on. You can see I've got quite a number of filters here and I've grouped by components. And This strategy I have named the Vulture strategy. So you're filtering for triage stage equals accepted. That's something that you should always filter for. Has patch yes. This means that Somebody submitted a contribution before, usually on GitHub.

Patch needs improvement. Yes, that means that contribution had a review and it got some feedback And then you can update the modified column and you can pick the date it was last modified by to be roughly six months ago. And then you can filter for bugs. And I personally prefer to filter for bugs because um There's no documentation you need to write. Um you don't need to get any, well, you mostly don't need to get um like an agreement on uh like whether we should do this or not. It's pretty clear that we definitely want to do this, etc.

So it also for me it filters out a a bit of work and effort. So that was the view I had, the has patch yes, patch news improvement yes, modified You know, this this screenshot's a little bit old, but that was roughly six months ago. And then it's accepted and it's a bug. And then that really reduced that list down to a very um manageable number. And then what I would do is right-click new tab, new tab, new tab, new tab, new tab, etc. with a bunch of ones that sound good. And then on those tickets, you can see in the pull requests.

It's not a column, but a thing. Don't know the word for that. There are links to previous pull requests That are associated to that ticket. If it has a cross-through, that pull request will be merged. If it doesn't have a cross-through, the pull request is not merged. And so the first thing you we should do is check the uh most recent one to try and see if it's still active. So A sign it's so active is um uh The person has not submitted new code since they last got a review.

So we are in this filter that I did, it's already the ticket hasn't updated for a long time And that 's clear. But what could have happened is perhaps the person pushed up changes, but they forgot to update the ticket status. That it needs another review. And if you spot this, then what you should do is update the ticket status for them so that this then goes in the review queue, but it's also an indication that you shouldn't do it But I'm going to assume that, you know, it they haven't done anything. It's been roughly six months. You can be like, or longer, and you can be like, okay, it it's quite likely that life has gotten in the way here. And you can look at those uh pull requests and that recent feedback and and go, okay, do I understand what the next steps are here?

Uh is this something that I could perhaps do? Okay, key piece of advice. You can always change your mind. Okay. And I recommend this thoroughly because if you start working on something and you get stuck And you've you've you've persisted with that for quite a while. Unfortunately, we don't actually have that much capacity in this community to have volunteers ready to kind of help you get unstuck. I actually feel like you should put that down for another day and try another one because it's quite likely that you will find that something else

suits you better and that perhaps this isn't something that you're ready for right now. And if you ask for help you can do that, but bear in mind that you might not get help for weeks Or ever. It's very possible. So don't have that as your main strategy Just always bear in mind that there are other tickets out there. There is like what a thousand to choose from. You can pick another one and be willing to pick another one. That first comment on that ticket that I put that was not the first ticket I did. I did also try that and went, I don't know how to do this and I did something else. Okay, next step.

You've picked your ticket or you've picked something that you feel fairly confident that you can give a decent bash at it. You're now working on the contribution. Okay, it's a bit scary, but you you could do this. So where to start? Sometimes I get this question, how do I start with this ticket? That's part of the reason why I encourage the Vulture method, because you at least have concrete examples of how previous people have approached the same problem before and they have been given concrete feedback on that approach. So that will already give you a good starting point and hopefully next steps

Assuming that you are working on a bug, but even not, if you're working on a new feature also, you need to be able to uh replicate the issue, you need to test the issue, you should have a test project. Okay. It's so valuable to have To be working on it in a realistic scenario rather than just relying on the test suite. So make sure you've set up that test project and that you are able to replicate the issue That you're working on. Writer regression test. This is the if you're lucky, there will already be a test in the previous PR. Sometimes there are some tests in the comments, etc. And if not, that's your first job.

You're gonna have to have, assuming it's a bug, a test that was failing before that you you want to be passing after you've changed it. Okay, learn from the history. Django has a really strong bit history and I would say this is a really good idea to use it when you're working on contributions because sometimes I get a question about like, okay, I need to write a test. I have no idea how to write a test for that method, okay. Go to that method that you are wanting to update and look at the git history of that method.

Pretty much every one of those um Uh commits will have tests, and if you look into it, you will be able to see how they tested. It's last time they made some change to that method, and the setup is likely to be very, very similar And where you put the test is probably going to be in the same area, etc. And even if there was a better place to put it, Uh you'll find that out later. Where you if you if you follow this, it would be like a really reasonable suggestion. You're not going to put it somewhere completely random or something like that It's not just the Git history that we have. We also have

other tickets like Dymo 's been around for 20 years. A lot of the problems, we've solved really similar problems before. And so go to track filter for the components that you are currently working on and also filter for closed tickets because those are the ones that you actually want. You want the ones where it got merged and fixed And look at look at some of those. If you go, okay, actually that that sounds reasonably similar to what I'm working on now, then you can look at that old ticket, look at the um The commit, which will also be commented at the end of the ticket when the PR for that ticket gets merged,

it's linked at the bottom, and you can look at that and and learn from that And like I said already, that the history is super useful and not just for writing tests, but for example, if you are doing a deprecation you can go to in the documentation, I think it's docs internalsdeprecation. txt and this is a list of everything that we have deprecated in Django Look at the git history of each of those and you can each one will be a different commit with an example of a deprecation. Okay, and that will include where you have to update the docs and what kind of tests you have to write and all this kind of stuff.

So Learn as much from history as you can because in Django we do things in quite a standard way and we really try to continue to do it in a standard way. So if you can make it as Django-shaped as possible then it's it's already a really good good start. Tests are your friends 100% Once you've got your regression test and you're working on this bug fix, the first thing you're going to try and do is to get that test passing. The next thing you're going to try and do is run the test probably just for that module. So you don't have to run the full test suite. But if you're running um if you're updating something when the test is in

admin views, just run the tests for admin views because it's quite likely that you might have fixed your issue but created issues elsewhere in really similar spots. And so then you're going to keep playing this game where you tweak it, tweak it, tweak it until eventually everything is Is is green at this stage. You get that all the tests are passing. And when I was first starting, that was just all I was doing was try again, run the test, try again, run the test, try again, run the test. Okay, so at this stage you have a contribution which has The contribution itself, it has tests

and you and those tests are passing, we've ran them locally, and now you're in the stage where you want to uh get this contribution merged into Django. So you've you're probably creating a PR at this stage. Django does have a contribution checklist which has a list of things that you should look for whenever you're doing a contribution. This is also used by reviewers as things that they should check for. So there's no reason why you shouldn't be, you you really should be checking for these things yourself And making sure that you feel like you've done everything in this list that is applicable for your contribution.

Another thing that I really recommend people do is look at other people's pull requests and look at the comments that are happening on other people's pull requests. because it is quite likely that there will be some things that are fairly standard, fairly standard comments that happen again and again That may not be documented in a bullet point. So one such example is probably that in Django, we don't want you to make the um Git diff, the contribution bigger than it needs to be. So if you've added loads of new lines to space out this method or you updated a line in a JavaScript file, but you

re-indented the whole file or something, you will be asked to revert that. Because we want to keep the fix as tight as possible. to that fix and so it hasn't got anything unnecessary that is included within the commit that fixes that ticket And you probably wouldn't know that unless you either got that comment on your PR or you saw that on other people's PRs. And it's a really good idea to polish your contribution as much as possible learning from other people uh because it might take a while to get a review okay So you have followed the contributing docs

to the best of your ability. So that's got the style guide, that's got the contribution checklist The CI is green, okay, all the tests are passing. If it if they're not, you need to investigate them and push up changes, etc. It's possible that Perhaps you you ran the tests only on SQLite and something has broken on the Postgres tests. And if you were working on a contribution which is a follow-on to somebody else's contribution, for example, so you need to make sure you have resolved the comments that that person also got. So you may not have gotten comments on your PR, but make sure you've gone through all of the previous comments on

those previous PRs and gone, okay, I did do that thing, I did do this thing, etc. So check that as well. The next thing is the ticket needs to be in the review queue. The review queue. The easiest way to find it in my opinion is if you go to track there is a a link to reports. If you click reports within there there is a link to patches that need review. It's called something like that And this is a filter for has patch yes, needs documentation no, needs test no, patch use improvement no, and the ticket is accepted. And that will give you a list of all of the

tickets which have pull requests which currently need to review right now. And you want to see that your ticket is appearing in this list. And if it is in that list, it will be reviewed eventually. We don't have That many people giving reviews compared to the number of people who are creating pull requests to Django. And the people who are giving reviews it is quite likely that they are either a fellow, in which case reviews are like a small proportion of the job And they're actually considered one of the least important parts of the job because we have security releases and fixes, we have other things which have been deemed high

a higher priority And then if they're not a fellow, then they're a volunteer. And so they are not paid to do this. They are doing this in their spare time. And They might have given you a review recently, but it doesn't mean that they will be able to give you a review in two days' time when you push up updates. you might need to wait again until they are have some time in their um you know their free time to to give you feedback again. But if it's in the queue It will get reviewed at some point. It's on the community to review that pull request. You get a review, okay, and you probably get a whole bunch of comments And then the next thing you do is exactly the same thing again.

You need to like do the changes, you need to check that your changes follows the contributing guide, etc. You push up those changes, check that the CI is green, and you've resolved all of those comments and then you put the ticket back in the review queue. So And when I say in and out of the review queue, what will happen on the ticket is the person who reviewed it will likely mark one of those flags like needs documentations, yes, or patch news improvement, yes, or um needs tests, yes, and to put it back in the review queue after you've done all of those things, you would then put no, no, no, no on on those things. And then

after you've gone through this process a couple of times, what will then happen is And and I should also say there there is there are people with a particular role who are mergers And those people are myself, Natalia, Marish and Claude. Not only will you get a review from the community, maybe somebody from the community has approved your PR You will also need a review from a merger and part of the reason is that the mergers have quite a lot of accountability to the changes that get into Django and so one of the mergers needs to feel comfortable that they're like, yes, okay, I I do believe this is ready and they will have also have done a review

And once you've got a merger who's happy with it, what they're going to do is they're going to mark the ticket as ready for check-in and then they will merge the PR. Other members of the community can mark it as ready for check-in and that in that that lets a merger know that it also needs a review from them. and merger might review it, they might agree that it's ready and merge it or they might give feedback and then put it back to accept it. All of these are possible. But once it's been put in ready for check-in, this is a good sign, but you're on the right track. You're basically done now. Maybe you get a few more comments, but it it should be nearly there. And then well, hey, it's in and that took a while.

It's a process. Uh but yeah, it it feels really great when it happens. Um so yeah, so congratulations to anyone who's who's already achieved that, anyone who hasn't, it it will happen. It is uh It's a mixture of you being persistent and then having a bit of bit of luck that the the community's gained enough time and uh to have the capacity to to give it the attention it deserves. And that ticket that I I I uh did comment on, eventually I did do this ticket and got that merged and fixed as well. So Like I said, contributing to Django, it's not easy, but it's not impossible.

If you stick with it, you can definitely you can definitely get uh mergers changed and um Django. I have a feeling that some of these resources you're probably quite aware of, but just in case you didn't know, there is a Django Not space contributing. program which I recommend anybody who's starting to apply for that. I think that's a really good idea to be contributing to Django. Django. space also has a YouTube channel which has a number of talks and uh recordings that are all around mostly around contributions to Django and I think they're all really useful There are some other places on YouTube if you're if you're into talks that could be interesting.

So there's uh Django under the hood. Which has some of these like long technical talks. They are all quite old. They're probably about 10 years old. The core of what they're talking about is often the same. So you might find those useful. On the Django Discord there is the Contributing Getting Started and the Contributor Discussions channels. They have like a bit of a live chats with some of the contributors to Django are sometimes online and can reply and there are other very useful members of the Discord community who will reply to you. And then the last thing, we don't have technical docs.

Sometimes I get asked, is there some technical documentation I could be reading for X? The answer is no. We have the the docs which should tell you what that thing is supposed to do. Um that we don't have uh other diagrams and and such and such like that that is available somewhere else. And With that, thank you so much for joining and listening. I hope you found that useful