For non-trivial reviews, when there are files with several changes, I tend to do the following in Git:
- Create local branch for the pr to review
- Squash if necessary to get everything in the one commit
- Soft reset, so all the changes are modifications in the working tree
- Go thru the modificiations “in situ” so to speak, so I get the entire context, with changes marked in the IDE, instead of just a few lines on either side.
Just curious if this is “a bit weird”, or something others do as well?
(ed: as others mentioned, a squash-merge and reset, or reset back without squashing, is the same, so step 2 isn’t necessary:))
As a senior dev, I’ve found “can the junior devs grok wtf I did/made” to be an excellent “did I overengineer?” Litmus test.
A good implementation should be not too hard to explain to the juniors, and they should be able to “get it” in a single short 20-30 minute meeting at most.
If they are curious/interested and ask questions, that’s a good sign I made something useful and worthwhile.
If I get a lot of “I’m not sure I get it” and blank stares, I probably have overcomplicated the solution.
If that “ooooh, okay!” Comes quickly, then we are good!
If you need a whole meeting to explain what’s going on in your PR then it’s already too complicated, IMO. That explanation should be done as a combination of PR description, commit messages, documentation, comments, and the code itself.
Everyone will forget a meeting. The stuff I described will pay dividends for future maintainers.
The meetings should happen at design and planning phase.
Do you not do demo meetings after introducing entirely new features?
Sometimes a PR can be quite large as it involves an entirely brand new feature that simply didn’t exist before.
And if it’s an internal tool/service for fellow devs to use to make their lives easier, yes, it likely deserves a meeting so the devs can have a chance to QnA about it. Usually 5-10 minutes going over the who/what/why/where/how, then 20 mins or whatever of any needed QnA if devs are curious for more info about specifics, like performance or extensibility or etc.
If you create a new tool like that abd then just hand it off with all the devs have to go on being “here’s the manual, figure it out” you know what happens?
Almost no one reads it, and pretty much no one uses it, because parsing a giant manual of info is difficult co.pared to seeing a live demo
Sure but it’s rare that a single PR introduces anything but a small slice of a feature, and the demo is usually something that can just be recorded in under a minute and sent over chat. The PR reviewer is likely to try building and using the new functionality too.
Just document the tool or service. That must exist anyway if it’s going to be used by many people. And we’re not really talking about a PR review at this point, we’re talking about an internal release ceremony, which may involve parties that are not going to look at the PR.
You’re still straying from the topic of conversation: PR review process. But regardless… If no one uses it then it’s probably not useful. Why did you build something that didn’t compel people to use it from a one-paragraph internal PSA?
Yes, I never said this was a common occurrence. This is indeed rare but it dies happen.
No, this is 100% still part of the PR review, I was pretty explicit about that. This process should happen for a large feature/service/etc as this simply cannot be covered by a “LGTM!” Comment on a PR.
These meetings primarily cover when you’ve established something that needs to be followed or used moving forward. IE: “This new feature makes our lives a lot easier and now (annoying thing) is much easier to implement. This is how I used it in my PR and I wanna make sure all the rest of the team is on the same page about it, and everyone else starts using it in the future.”
This 100% comes up here and there and it absolutely necessitates an actual meeting, because any dev worth their salt knows what happens if you dont get everyone on the same page on it…
The inevitable “why didn’t you use (thing I made explicitly for this purpose)?” Convo comes up a month or two later, because all you did was document the new thing and open a PR, get a couple "LGTM!"s, and you posted a blurb about it in the chat and pinged some folks.
And if you’ve gone through this process before you will know that simply just never works, full stop. Doesn’t matter the team, doesn’t matter how well documented, doesn’t matter how good your write up is… People. Don’t. Read.
There’s a reason “RTFM” is such a meme in linux communities, people don’t fuckin read mate, abd that’s why critical big PRs 100% need a 20-30 min QnA meeting so people can actually talk about it.
I’d estimate tops 10-20% of devs that should read your docs, will actually do it.
Let’s step back. We are trying to talk about code review, right? That’s when you are getting a final check that your code looks roughly correct and does what you already planned for it to do with your colleagues, give or take a few details you couldn’t plan for. So at this point, usually at least one other person knows what you’re trying to do, is bought in, and should be able to review it.
I’ll concede that if you are desperate to merge a PR and people are on vacation or something, then you might want to grab someone else to review. I’d send them the PR and say, “let me know if you have questions.” Then if they do, you can have a quick chat or meet one on one.
That’s code review.
You are talking about some other thing. I’ve been in internal release meetings with lots of people that needed to understand the basics of a feature in order to support it or use it. That happens way after the PR is merged. And I’ve been in meetings to figure out how we should solve a problem, which happens before the PR is reviewed. I have gotten PSA emails or slack messages about cool new tools that make my life easier or changed our coding standards in the organization.
I have never been asked to meet with multiple people about what a PR is about before reviewing it.
IME those meetings only happen if the PR is objectionable upon review and it’s hard to negotiate what must be changed.
Only on very small projects.
As the team grows, having just 1 person review your code is simply not sufficient.
Even 2-3 may not be enough to sanity check if a larger new feature on a massive project is good. If it impacts the team and means a fundamental shift in methodology, then you need more voices weighing in.
Now, can you merge the PR in first, then have the meeting after? Sure, I guess, but why would you?
If the team reacts negatively to what you built, finds flaws in it, or simply just doesn’t get it because you overengineered, now you have to revert the PR and go back to the drawing board.
It makes tremendously more sense to bring folks impacted in on a swarmed live PR review as you go over what you did, where you did it, and why… before you merge it in.
At this point you can QnA, get suggestions, feedback, etc.
Now typically most of my response to live chat feedback is “aight, can you add that as a comment on the PR itself so I can see it after?” And then they go and do that asap, usually typing it up as I answer other folks questions. Because at this stage the PR is literally the perfect place for feedback to go.
I’ve been down the path of “1 person LGTMs the PR, huge new feature is added, I document it on the wiki rigorously, I post the new feature to chat… 1/10 people bother to use it and 9/10 give blank glassy stares when I bring it up”
It. Doesn’t. Work.
Period, lol. And don’t get me wrong, I wish it did, but people just don’t RTFM mate, that’s a fact of life a d the sooner you accept that, the easier the job gets.
K what do I know, it’s just what I’ve done on code bases with ~5 million lines of code, at the point where no one understands even half of it.
Everything about what you just wrote, and the way you represented it, signals you are precisely the type of individual that should take everything about what I wrote above very much to heart, friend.
If you have no idea what I’m talking about, I hope one day you do :)