All right, folks, so today we're talking about pull requests, maintainers will love to review.
So first, maybe let me get a quick shift, Hans.
Who here is a maintainer for an open source project?
All right, who has ever submitted a pull request to a project they don't maintain?
Yeah, almost everybody.
Who is thinking about doing it someday is here to learn?
Nice.
And who has not yet had a chance to raise their hand?
Also, all right, thank you for being here.
Thank you all.
This talk has meant to be interesting and hopefully informative for everybody
no matter when you raise your hand.
So let's get to it.
And I'm going to try to make this interactive.
We'll see if it works in this room.
But when I, you know, we'll see basically I'll ask you folks to participate
and share your ideas throughout the talk and then I will restate them,
but you just need to say them out of for me to hear.
So first, let's get on the same page.
So what is a pull request?
Is it, can anybody raise their hands and throughout a definition?
All right, thank you.
All right, so in a request to integrate one of your comments into a public repo.
All right, let's see.
So I, all right, so here is a pull request in the context of a resource development.
All right, so here is my definition and that this is what it will be going for this presentation.
So a pull request is a presentation of your proposed changes to a project.
So it's a presentation of that request to integrate your comments.
And that's going to be really important.
So why put up a pull request?
You guys have all that at almost.
Anybody want to raise a hand?
All right.
Because something is a project in my view or everyone involved in it.
Yeah, because something is annoying and you want to fix it.
Others.
Yeah.
Yeah, because you want to share something you've done.
Anyone else?
Yeah.
You just fix something.
All right.
What?
Trying to change one.
If you don't want to have to reach out on the page.
Yeah, you don't want to maintain a forksy, you want to get your changes integrated up stream.
Cool.
So those are some great reasons.
I'm going to give kind of a first first pass reason as you want to get your changes merged.
Right?
If you submit a pull request and it doesn't get merged, usually you didn't get to whatever
you were trying to do.
But then yes, there's a bunch of different reasons why you might be trying to get your
changes merged.
So maybe as folks were saying, the fix initiative that's bugging you, maybe you just
think it's like really cool to be part of an open source community and you want to contribute.
Some folks do it for homework, or for resumes, a really transparent way to demonstrate
your capabilities to build code.
And hopefully, whatever other reasons you might have, that last reason also applies, which
is that you're trying to help the project, right?
You're trying to make the project better.
And so for the rest of this presentation, I'm going to assume that no matter what else
you're trying to do, you're trying to help.
So that raises the question.
So you're trying to get your PR merged and you're trying to help.
So does every merge PR actually help the project?
Anyone?
Any thoughts on this one?
Somebody said no?
Why not?
Actively harmful, a passive, a harmful, yeah?
Yeah, so it could be malicious, yeah?
Yeah, so it could be adding a bunch of maintenance burdens.
So maybe it's a good feature, but it's going to be really hard to maintain.
Yeah.
Yeah, maybe it doesn't match the vision of the people running the project.
Yeah, one more.
Company that's going to work for me to speak about leadership or whatever.
Company you work for a new Zexer feature, yeah, maybe it's so I think one way to think
about an open search project is we're all working together to build this drink of power.
And so maybe it starts out nice and small and really stable, really easy to understand.
And then we keep changing things and adding pieces and adding more features.
And as we do it, it gets more complex and more fragile.
And each new PR, you're adding a piece on top of this pile.
And what you really don't want is to just pull off your piece down carelessly and collapse
entire thing, right?
So when we have a PR that we're trying to get merged, we really want to be thoughtful
about that maintenance burden, the risks that introduces other parts of the project.
And it really is something that containers are going to be thinking about when they're
looking at your work.
So how do you get your good PR merged?
Well, like very simply you need maintainer approval, right?
That's the definition of what containers can do.
They can decide what goes into the project and what doesn't.
But how do we do that?
So first, okay, here's another toss-up.
What's a maintainer?
Anyone raise a hand?
Yeah.
Go ahead and then the jacket.
So you have to speak up a little.
Maybe some, sorry, I couldn't hear it, maybe because somebody could speak a little.
A maintainer's, maintainer's, maintainer's integrating into the project.
Yeah.
Any, any other?
Okay.
There's another hand there.
A person with no life outside the project, with a life outside the project?
With a life outside the project.
Yeah, sometimes it's definitely forget that.
All right, here's my answer.
Okay, first of all, sorry, it's not somebody who's fixes up autos.
It's a super busy person responsible for making an open source project better and not breaking
things.
Hi, I'm a maintainer, so let me introduce myself a little bit, so you know where I'm coming
from.
So I work on Zulip, which is an organized team chat app, an open source alternative
to something like Slack, Microsoft Teams, Discord, you can self-host it, or we offer cloud
hosting, which is free for open source projects that chat with me afterwards if you're
interested.
And we've really invested a lot into building up an open source community around the
project, so we've had 1,500 code contributors over the 10 years of the project with 100
contributors with 100 or more commits, so lots of folks who have got really deep engagement.
The support this we've written, almost 200,000 words of documentation for developers.
And if that sounds daunting, that was over the course of 10 years and definitely not something
we started with or you have to start with, much less could be very, very useful.
So how do you collaborate with maintainers, these really busy people?
Well, here are a couple of really important questions and maintainers going to have about
your pull request.
So one is, we talked about being useful, right?
So do these changes do something useful in a good way, so good can mean in line with the projects,
the standards and kind of fitting with the rest of the code, not introducing regressions
elsewhere, all sorts of things.
So, but let's talk about the useful part.
So suppose I'm baking a pair of tart, right?
And I have these nice three pairs that I'm getting ready to bake and you come to me and
you're like, here's a beautiful red apple, it's delicious, it's great.
And I look at it and I'm like, yeah, that's a great apple, but I am making a pair of tart.
So what do I do with your apple, right?
So when you're submitting a pull request somewhere, probably the maintainers of the projects
have some visions, some idea of what their product is, what it needs to do, and what it
doesn't need to do.
And so what you don't really don't want to do is they're working on a pair of tart and
you come in there with your apple, right?
Maybe it could be a great feature, maybe it's a great feature for some, it might be, it
might be, but the maintainers, it doesn't fit what the maintainers think their product
is about.
So you don't want to spend all that effort of doing the code changes, testing them,
all that work until you know that it's something that maintainers are actually interested
in.
And so there's going to be different ways to find that out for different projects.
So often one clear way is if there's a public issue tracker and maybe the project uses
a label to indicate which issues are open for contribution, like here we have the help
on in label, great, you know, that's something that containers would be excited to see
in this project.
Often there's like a development community, a chat or forum, or even just posting an issue
to their repose, hey, here's the thing I'd like to work on, is this something you're
interested in.
But don't do all that coding work before you've done the kind of social work of understanding
is this a feature that they want.
Maybe you're initial, maybe you'll also find that the initial idea came with is an apple
for them.
But there's something that is a pair that just requires discussion and back and forth
and kind of aligning what you're looking for and what they're looking for.
Okay, and then another question the maintainers are going to have is how risky is this change,
right?
Because we talked about how containers are responsible for things not breaking.
So they're going to look at your change and be like, okay, how likely is this to break
things?
And if everything looks good, it's useful, it seems reasonably implemented, it's low risk.
That's when your PR is going to get merged.
There's also a situation that's very common where initially the answer is, well, not yet,
like it doesn't quite meet our standards, this thing could be done better, so on, but
I can see a path towards yes.
And that's when the maintainer will probably leave some feedback on your pull across
and ask you to improve it to make it better before they can merge it.
But what if your PR is just kind of a mess?
Like you look at it and you're like, I have to do something, but I can't really tell what's
happening here.
I don't really understand this.
That's when you're probably not going to get reviewed, yes, you're certainly not going
to get that PR merged right away.
It's probably not even going to get a feedback, because as we said, the maintainers are
busy people, they're prioritizing things that they can see as likely to move the project
forward.
If they look at your PR and they have no idea if it's going to move the project forward,
they're not going to be able to review it, it's just not going to be worth their time.
And I think it's a really fair decision for them.
And so advice, you'll get a comment saying, hey, I can't understand what's happening here,
can you please fix that up and make it more clear.
Maybe they'll just think they'll review it someday when they have more time, so it'll be
forever and you'll never hear back or maybe they'll just ignore it, but really you're
not on a good track of this is where you start.
The rest of this presentation is how to put together a pull request that doesn't look like
a pile of LEGO fricks.
Let's see what's involved.
Let's just go kind of all the pieces that put together the go together to making a pull
request.
So this is just a screenshot of a pull request from one of Zolves maintainers and then
we're just going to go over all the pieces you can see we're using the GitHub UI so
this GitHub so this UI might be familiar for you.
So one piece is the comment history, so we'll talk about that.
The other piece is the PR title at the top and then just some textual description of
the changes.
You might have screenshots for visual changes.
There might be some CI running so it's going to be test that you need to pass.
And for us there's also a self review checklist that you need to check off before when
you're submitting your pull request.
So this is going to be kind of the outline for the rest of the talk with one bonus section
of the follow.
And the idea here is look, when as folks trying to contribute to open search projects,
we need to find our way around, maybe this is a new project we've never worked with before,
we really try to figure out how it works, what do we do here?
And often maintainers will create a kind of map for us like contributing guidelines, documents
that walk us through what their expectations are.
And if they've done so, it's super important to follow that map, it's really going to help
you out.
But what I'm trying to do in this talk is a couple of things.
One, sometimes you don't have a map for the maintainers or maybe it's very sparse just
a few checkpoints, but there's also lots of open areas that are unknown.
So what I'm going to provide is kind of best practices or ideas for where you can, how
you can fill in those gaps.
And then, as a maintainer, I hope this gives you some ideas for if you're still working
on your map or if you're improving your map, what are the kinds of areas that you might
want to fill in and think about for your project, with some examples of how we do it
at Zilla.
So that's the plan.
All right, so come in history.
So if you were here for the previous talk, I just want to tell you that we use the same kind
of commute approach that the speaker was advocating for, so parts of this will sound
a little familiar.
So, all right.
So, forgive me to history.
So, idea that we, for our projects that commits tell the story of your changes.
So what does that mean?
So, each commit is a minimal coherent idea.
So, why is that useful?
Well, you can quickly review each and separate commit and try and understand it and assess
the risk we talk to how risk is really important.
And then, if maintainers keep the commit history as you presented it, you can use things
like get by-sector to track down where something broke.
And as the speaker last I mentioned, even on your own branch, you could potentially use
get by-sector to figure out which of your six commits is actually causing the problem.
So, this means in really practical terms, you would split out things like refactoring
or enaming that's preparation for the changes that you're making from the actual functional
changes.
Because it's easily just to check, oh, okay, I expect this to not really change the functionality
and it doesn't change the functionality.
Great.
Each new feature improvement would be its own commit.
And then, with how just review tools work and how it does tools work, it's really nice
if you split moving code from changing code, because if you both move and change it becomes
much harder to see which parts you changed.
So the thing is you also don't want to split things too too much.
So each commit, the idea is here is that each commit should be safe to deploy, so it doesn't
make the product worse.
It might not make it better yet, like maybe that refactoring you did, doesn't really help
or hurt either way on its own, but it doesn't make things worse.
It updates whatever tasks need to be updated, so commits pass at each commit and includes
error handling for the code changes you're making.
And so when you do things this way, you can really lay out the story of how each change
that you're proposing is necessary or helpful.
You can really kind of set that out piece by piece in a logical order that's going
to be easy for your viewers to understand.
And it's really important to remember to tell the story of the changes as they are not
of how you got to these particular changes.
So here's a toss up.
Should you have a commit for things that you tried that didn't work out?
Who says yes?
Who says no?
Yeah, the nose have it, so you don't want that, because then the maintainers are going
to be looking at it and thinking, oh, why are they doing it this way?
Right?
If there may be reading your changes coming by commit, there may be like, oh, hum, I don't
understand this.
And I don't think this is the right way to go.
Maybe they'll start commenting on it.
And then you'll see that two commits later, you actually did all that and fixed it yourself.
And that was a giant waste of time for them to think about it.
How about things like fixed a test type book or fixed a link there?
Should those be separate commits?
Who says yes?
Yeah, who says no?
Yeah, squash them.
Get rebased that shy is great for this kind of thing.
Super easy.
And really, again, lots of your reviewers actually read your changes committed by commit
and understand the steps of your thinking and not get confused when they see something
as wrong and then they're like, oh, but you actually fix this down the line.
So commit, in addition to your coaches, you're also writing a commit message to explain
the changes.
So what goes into that message?
Well, explaining your changes means providing some context and motivation for what you're
doing.
So it might be like investigation or reasoning, like, okay, I'm removed, you know, this function
was removed because we haven't been using it since this other commit, I might have
some background on the contrasting and the situation was before your changes versus after.
And it can also make promises or gritty so like, this commit makes no functional changes
because something and that way the reviewer understands what you were trying to do and
they can much more easily to check, did you succeed in doing that?
So if they know that the goal is to make no functional changes, they can check for that
and see if that's correct.
But the commit message shouldn't just say everything under the sky, it shouldn't
explain the obvious.
So if you're updating some file, you don't need to say that in the commit message because
that's clear from the deaf, right?
If you're renaming a function, again, that is what their viewer is going to see in the
deaf and it doesn't provide any of the thinking that you have behind it.
So just kind of these facts that are easily visible from other parts, from the code changes
themselves or from the say of the good hub UI, like those things don't never need to be
in there.
And you also don't want to put information there that will help future readers understand
the code.
So not understand the change in the code, but understand the code itself because that information
is going to be really helpful to have a, as a common direct thing in the code and therefore
you don't need to be putting it into the commit as well.
So maintainers can guide contributors towards the commit structure, commit messages that
they want to see in their projects.
So here's an example for Zulu, this is just the sections of the commit discipline part
of our contributing guide.
So you can see we go into a lot of detail actually with a bunch of details, rules, examples
because we really want to get specific and really want to help folks do things in the
way that will kind of best fit for a project.
And so if a project has commit guidelines, I'm absolutely not going to tell you to throw
those out and do what I'm saying.
You should follow those guidelines.
But I think the approach that I'm presented here is going to be really helpful even
of them and maintainers, as long as the maintainers are fine with it.
Even if the action of squash or your commits later, it's still going to be a really useful
tool for them to review your work, even if it does get squashed as part of how they manage
their get work flow.
So when you have detailed guidelines like this, the amazing thing is you never have to
rewrite and re-explain what you're looking for.
So next time you get this is a screenshot of a real pull request for Zulu, so there's
a bunch of commits here fixing, lending, fixing tasks.
And when we see this, we don't need to explain to them everything that the previous
talk went over, we just say, okay, these are just a couple of the saved replies I have
in GitHub.
Okay, please clean up for your commit history and post again to request review, see here
for guidelines, or thanks for the fix, could you please, did your commit message to match
the commits style guidelines?
That's all I've got to say.
I don't have to tell them what we're looking for beyond that.
So this is the end of this section.
I actually want to do questions kind of as we're going along.
So does anybody have a question of this stage?
Yeah.
There's been no way that you can change your history like you, do you need to like
your.
Uh-huh.
And then you have a situation in that, go back and find the change of the
way.
Yes, please do.
Absolutely.
Uh, sorry.
Why does one work here?
Okay, please.
Yes.
I'm not sure.
OK, please, yes.
Well, so this is going in the commit history.
I don't think we've thought very hard about the migration pass.
I don't think that's a priority, but also I would expect that any move we make would
have to carry over the commit history otherwise it's just not going to be like a reason
we'll move first to make.
Right. Well, we're going to talk about several, but I was talking about commit
messages right now. Yes.
So, I'm personally not a developer. I'm a, the product lead, but our developers
I think do very much change their commit history as they work out in PR and redo it.
And often reviewers will actually say, OK, this part needs to be split up more.
Please break this up and just separate commit.
That is changing over the course of their approach this for sure.
Yes.
Because then, sorry, the question was why one change per commit when one change per
pull request?
Because that just makes it easier to review bit by bit and raise easier to understand the story.
So, if you expect each commit to be a coherent change, you can think about just
that one commit, not the like 300 lines of changes in the pull request, but just those
30 lines of this commit and take it one piece at a time as a reviewer.
Well, a pull request, sorry, what the question is, when would you put commits into
multiple commits into a pull request? I mean, usually a pull request will have like
some feature or something, you know, some related piece of work that it is.
But it could still be broken down further into coherent changes.
So, like, for example, you know, depending, but you might make back-hand changes and then
separately add a front-done for the feature.
Yes.
So, I see, so there's a question about a pull request that just had a commit,
must it just rename something? So, I would suggest saying something like, like,
if I knew why you're renaming it, right? Like, there's some reason you're doing that.
Making that change.
All right. So, I think I'll move to the next section, but thank you.
This was great.
All right. So, now we're going to talk about the PR title in the description.
So, this is the, I think, maybe a previous question was asked about.
This is the piece that wouldn't move if you're, like, changed from
GitHub to GitHub or something. So, this is where you're going to be explaining your
changes to reviewers. So, all right. Suppose your changes on the surface look like a
beautiful, tropical island. But underneath, there's a dinosaur skull.
There's really something fraught there. You have to mention the dinosaur skull.
Okay. You cannot just present this beautiful island. So, why do I say that?
Any thoughts on why I'm saying this is really important?
Like, what happens if you don't do it? Yeah.
Accurate estimation of risk. Yeah. For the maintainers to accurately estimate risk,
they need to understand what risks you're aware of.
They're really going to be helping them out.
Anyone else?
Yeah.
Yeah. So, I couldn't quite quite hear, but I think you said,
maintainers to be able to trust the needs to be honest with the maintainer.
Yeah. So, I think that's really, it's super important. Like, if you do this,
if you don't mention that what's hiding underneath, there's two things that can happen.
One is the maintainer might not notice and they might merge the changes and they could
cause problems for the project down the line. And we just said, we're all trying to
help these projects, right? So, we don't want that. They might also notice the problem.
And then they'll wonder why you didn't tell them. And there might be like two plausible explanations.
One is you didn't know, which brings into question your competence as an engineer.
Or two, you didn't know, and you didn't tell them, in which case, how can they trust you, right?
How can they trust you in the future? And so,
contributed to business projects was in part establishing a relationships with
the maintainers for those projects. And if they decide that they can't trust you as a
contributor, it's going to be really hard for you to get any of your work integrated
into the project down the line. So, it's not just hurting your chances with this
full request. It's really, it can be really damaging to your relationship with the project.
So, please. So, okay. So, how do you explain your changes?
So, here, I have an example of a pull request from one of Zulv's maintainers.
Just a simple API docs change to updates on documentation. And I'm just going to go,
it's not important. You know, you need to start reading this right now, but I'm just going to go
through the different pieces of it. So, the first part is just an overview. So, this is kind of like,
what was the state before this pull request? And so, why is this pull request needed, right?
There are some changes made to the API. Now, we need to update the documentation.
Then, there's a note section, which notes a decision that the author of the pull request
made. So, they decided to use the edit a message and point main description as a template for
these updates. And that is super helpful to review, because now they can say,
okay, do I agree with that decision? If yes, then actually it could be much less careful
in some ways when reviewing this work, because I now understand what they're trying to do.
And so, I have, I don't need to put myself go and compare this versus the edit a message
and point description necessarily. If I trust that they might have, they probably did this carefully.
Where they can decide that they don't like this decision, but then instead of going through
and giving detailed feedback, a line by line, trying to get this aligned with the edit a message
or with something else, they can just say, no, no, no, I think we should be matching this other template.
Can you please read it that way? That's all they need to do.
This also raises an open question or concern, so I'm not sure if I should include this,
I decided to do it this way, but I'm not sure. So, again, now the maintainer,
the reviewer can really think about this question and answer the question,
yes, great, I like it, how you did this or please do it some other way.
And then it also indicates a difference from prior plans, where maybe initially when this project was planned,
you didn't think about doing something, but when they're working on it,
the person who put up this full request realized that an additional change was needed.
And that also really helps the reviewer not get surprised by it, not be like,
this is coming from this wasn't discussed, so now they understand what that's all about.
So, this is the kind of points that your pull request description can make to really help
folks review your work quickly and really address the points of concern that you have.
So, any questions on this?
Yeah.
So, I would say that this kind of thing, like many of these don't really need to be like,
you know, because some of this is things like, oh, we consider,
basically like, should we do it this way or some other way?
And I don't, you probably most of the time don't need to describe that other way too.
This is more like important while you're thinking about whether to do it,
whether to merge this, but it won't be so important if you're later trying to figure out what happened.
And you can, I mean, as long as you don't, you're still on good hover whatever you're on,
you will also be able to trace down commits to the pull request they came from,
so this is not entirely lost, so it is like one step further away from the code.
Anything else?
What about tests? We're going to talk about them separately.
Oh, yeah. So, right. No, so I think that's actually, that's actually something that we have added to our peer
template recently, but yeah, I think explaining how you tested sort of manually is a great thing to add there for sure.
Yeah.
Yeah. I think people don't like reviewing those, but, you know, you do what you can.
Sorry, the question was of what about massive changes that you can't split up.
I think you, you know, I think, at least for us, we would try to split up things up as much as we can,
and then when we can't, I guess it's just, there's just a, there's going to be a lot of things that we can.
Yeah.
Yeah. So the point that was made in the audience is that it's not, that's not the kind of change that you would be making us back.
Like, you wouldn't just show up to project and contribute to change like that.
You know, it's something that maintainers are doing and working together on to make it as, you know, you've figured out a good way to do it for sure.
Cool.
All right. So the next section is screenshots.
So this is how to show any of changes that are visual changes.
So there's a few different things that screenshots are super helpful for.
In addition to kind of anything you're right about how you tested your PR.
They can also demonstrate visually how you tested your PR.
They can help clarify requirements, so maybe you worked on submission to add a button.
And the spec didn't say exactly where to place it or didn't, maybe it didn't say what color the button should be.
So now if you look at it and be like, oh, actually, I meant for the button to be over there, and can you make it blue?
Great. They didn't even have to look at your code.
They didn't have to pull down the PR into their dev environment.
They just looked at your screenshot and they could provide you the next set of feedback.
It can be a way to raise questions and get consensus on some decisions.
So maybe you're like, oh, should this be, should this part of be this big or twice as big?
Let me put up some screenshots of different variants and then people can discuss with concrete visuals in mind.
And it's just less QA for viewers. So maybe you actually did follow this spec and you did exactly what it said.
But looking at it now or viewers says, oh, actually, let's change this string to something else.
Again, they could just kind of get that official context for where your work is appearing.
So they're super helpful.
So we had a pull request and I'm going to try to speed up a little bit because we're going to pull requests to change it to a little bit.
So you might expect like screenshots for that. So what would you expect?
Like maybe the, okay, I'm going to actually sort of keep moving.
So let me show you what we got assuming this video plays.
This is what we got to demonstrate that change.
Now, how do you feel about reviewing this?
I don't know about you, but I think that's, that's kind of terrible.
That makes me cry. Like I can't really see what the tool tip was.
Did it, you know, was it what I was, what we wanted to be or not, I'm not sure.
So I think it's really important to be judicious with screenshots.
Like they can be tempting because you can show all your changes all at once to just in one fall swoop.
But it actually makes it really hard to review them.
And so they should only be reserved for interaction.
So maybe if you really wanted to show like how quickly the tool tip shows up or something,
they should be as short as possible.
So I never want to see like pulling open the app.
And even if you're showing everything there is to show on a screencast,
you should also include a still screen shot because it's so much easier to look at.
So here's after we get after I gave feedback to this contributor here's what they produced,
which works fine for this pull request.
I can see that they actually change the strings as expected.
But for some kinds of changes that are more visual like here changing an icon and the hover colors,
what you really want is actually matched screenshots of before and after.
The only thing that is changing is the thing that your PR changes.
So the the colors are the the mentions are the same everything in the UI is the same.
And only your changes are what what is what is different.
Because that way of your connection open these screenshots in different tabs.
For example, if flip back and forth and watch the changes animate that's super helpful.
And it's really great for kind of see us as changes visual changes in general.
So again, maintainers can really help contributors do this by providing guidance.
So this is actually brand new for us having these detailed instructions for how to generate the kinds of screenshots we're looking for.
And when you need really precise pairs screenshots and when you can get away with less and so on,
including like pointers to specific software.
When maybe think that out of everybody is explored, but like the dovetools and your browser of Chrome or Firefox are amazing for producing these pet and really nice pairs screenshots.
They really completely let you control the dimensions and get exactly the screenshots you want.
All right, good to move faster tests, which are good for moving quickly without breaking things.
So what are tests for so they they help you validate your changes right I probably don't need to sell y'all on to us, but I'm going to do it for a little bit anyway.
They help you communicate your PR is expected behavior including corner cases and then help you make future changes safely.
So the question is like, what how do we write tests to do these these great things that we want from them.
Okay, here's how not to write tests.
So suppose you have a recipe that requires some hazelnuts so your recipe might say how many hazelnuts you need.
It might say I don't know the the weight of the hazelnuts you need how to prepare them, but it will never tell you the size of the opening and the jar that you're getting the hazelnuts from right.
Because it doesn't matter it's not going to affect how your recipe comes out and you might have a different jar tomorrow and the recipe will still be fine.
And that kind of thinking applies to testing as well.
So you want to be testing the things that matter and not things that are just implementation details that happen to be this way, but it could just be as well be some other way and that would be totally fine.
Because when you test the size of the jar you're just going to have to be fixing those tests and rewriting those tests when you make changes.
But they're not going to be like they're not protecting against the things that actually are important to protect against they're just busy work.
So if you want to hear more about this Greg Price who's our mobile tech lead, give an excellent talk at Fluracon rating better test with less work.
So I highly recommend that.
All right, self review.
The other thing you need to do before you submit your focus please.
So what happens if you don't really review your own work.
So you're thinking your PR is now nice and this beautiful little house and nice feature you're adding.
But actually it looks more like this like it is there's a yellow wall.
It looks like maybe it's going to go somewhere, but you don't really know what's happening here yet.
And you know we talked about what happens when a maintainer doesn't really know the PR is going to be helpful or not right.
They might not even review it.
So you want to be before you ask for anybody else to take a look you really want to be putting your best foot forward.
So here like here are a few things you should be thinking about.
So it's great to look back at the issue if you were fixing an issue right.
Did you actually cover everything that was there?
Did you do it?
Did you follow any all the, all the, everything that was specified?
And if you didn't did you explain why in the description for your pull request.
Your code is, does it match the style of the code around it?
Lots of questions there.
Did you structure commits in a way that makes sense?
Do they tell a clear story of your changes?
Is there anything that needs to be squashed together or split out?
Do you have a clear title in the description for your pull request?
Do you have screenshots like we just talked about?
Do you have, did you update the tests for your changes?
And, um, for us we hope folks make sure to remember to do all the, look at all these things by putting a checklist directly in the pull request template.
So that it's right there for them to go through and that's so that we can see that they would at least check off the points that make sense for their, for this pull request.
But there's one major part that's missing.
I guess really quickly does anybody know what we have it covered yet in terms of re-re-ringing your own work.
Super important.
All right, you have to test it.
You have to actually test it as closely as possible to how it's going to be end up being used in actual product.
So, you know, if it's, I think it's an app and you can go and click, you added a button, go and click that button.
And all the different ways you can think of and all the different configurations and make sure it does, it does what you did.
Or if it's more back in, you still try to, like, really run and exercise the code.
In the ways that it's going to be used in reality.
Because if you don't click on it, it might just not work.
Like, you don't know how many times I've tested PRs and the first, the moment I open it, again, an error and they're like, oh, the contributors like, oh, sorry.
I must have tested, fixed, messed it up when I rebased it.
You have to test your work and you have to test the latest version of your work.
So, again, we have a checklist and really also really detailed guidelines on all the things you can think about testing.
And that means that if somebody doesn't fill out this checklist, we can really point them to it and say, okay, please, please go through this without having to sort of hand hold every contributor.
Okay, one last one, I think this is really important to talk about in 2026 is the use of AI.
And our philosophy and that on humans is humans own the work and so I'm going to get into that.
So, I think a lot of us who maintain open search projects these days really feel like we're drowning.
Sorry, yes, I'm going to use our help.
No, right now.
So, we really feel like we're drowning in a sea of slop.
And here is this an example of a polar quest we got recently and this is just a description for this moderately small change.
You don't need to read it because it says all the things it doesn't need to say.
Clearly written by an LLM, the check-self review checklist is not the one that we provided, it's the one that LLM made up.
If you want curious what happens in the spare we close it without review, but there's a lot of this.
And, you know, we're all trying to do for texture cells and really figure out how to move forward in this context.
And a lot of projects have been adding AI use policies which, you know, they help a little.
They definitely don't solve the whole problem, but I do think they help.
And for anybody who's thinking like, oh, maybe it's just really good, which is just all work with the eyes, not with contributors.
Do observe that third hand that they I created on this image for me.
It really doesn't know how to make an umbrella without a hand holding it.
All right.
So, one way to think about the AI use policies, you can use it as a filter.
So, when a PR submitted, we look at whether it follow the AI policy and other guidelines.
And if it did, we really review the work.
If it didn't, we don't try to review the work because it's not in the state that's ready for you.
We just asked the contributor to read that.
And if they fix it and now it follows the guidelines, great, we can review the work.
If it doesn't, we close the pull request and warn the contributor that we won't be able to review their work.
If they do it in this way.
And we're really trying to minimize the time we spend on work that is just kind of LLM garbage.
And I think philosophical, like a part of what's going on here is, you know, the way that open source succeeds is it's really a collaboration between people,
the maintainers, the contributing community.
We're all trying to work together.
We're learning from each other.
We're creating something better.
And it's a given take, right?
The contributors are contributing code to the contributing of their work.
They're learning from the maintainers.
My retainers might be learning from them.
It's a human endeavor.
And so, when somebody just takes my feedback and posts pasted into NLLM,
and then paste with the LLM said back into the pull request, nobody's learning, nobody's going.
And that's just not where it's worth spending our time.
So, our A policy is much more detail than this, but the key highlights are that you as the human contributor have to understand,
test and explain the work.
You have to know what you're doing because if you're not providing this,
I might as well work with NLLM myself, right?
What is the value that you are bringing as a human to this?
And you have to communicate clearly, concisely and accurately.
And, you know, when we first saw the policy, we were missing the accurate piece,
because I thought, of course, everybody's going to try to communicate accurately.
But now you get pull requests where the description says one thing and the code does something else.
And that's, again, as you saw, like with the island and the skull,
like, that's even worse, right?
Now, the contributors intentionally are not misleading the reviewers about what the changes do.
And so, how can they be a trust in that situation?
And you also have to communicate about points that actually need communicating.
So, saying how many lines of changes you made in the PR description is not a thing that needs to be communicated.
And it makes writing this, you know, this really long alum.
PR descriptions make it very hard to actually get to the nuts of, like, what is important.
And that might actually get missed with all the garbage around it.
So, wrapping up, so what I've hope I've done here is for the maintainers.
I laid out kind of with the kinds of things that you might want to put in the map for your project.
Given some examples that you could use as a reference, if you're thinking about it.
And then if you're contributing to somebody else's project,
hopefully think about, you know, first of all, trust the map.
If there is a map, please follow it.
But then, for any kind of uncharted territory, these might be good starting points for you to think about
to really clearly explain what you're doing and why and make you work easy and fun to review.
So, hopefully the next time you submit a PR, it'll be a this beautiful little thing.
And maintainer will be delighted to receive it.
Thank you.