Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Why I close pull requests

jeffgeerling.com

Post reply on HN
Print view View original

111–120 of 188 posts

Re: Why I close pull requests

#111

Post by int_19h »

fdsfsaa wrote: post #47
yegle wrote: post #13

At Google, if you want to implement new features (or large refactoring), you'll need to write a design doc. In which, you should answer questions your reviewers might ask (common questions like: why do you want to do this, what are the alternatives, how components interactive with each other before/after your change). This is something like Python's PEP: you need a proposal to convince your reviewer that you have put…

Requiring permission to do work is the enemy of progress and engineering dignity. It creates a presumption of incompetence and an atmosphere of low trust that punishes people who want to push the envelope of what's possible. Google's design document culture is bad. Google has succeeded in spite of it. In my experience, having worked at many large tech companies, design documents obfuscate, not enlighten. They become…

> Code is just code. Bad changes can be backed out.

Not if they have already been shipped.

Re: Why I close pull requests

#112

Post by fdsfsaa »

hhandoko wrote: post #106
fdsfsaa wrote: post #95

Earlier quoted context omitted.

> break the testing infrastructure for practically every other developer in the building Why wouldn't continuous integration have caught that bug? If a diff breaks the build, it shouldn't land. If a diff causes tests to fail, it shouldn't land. If a diff lands anyway and causes problems, any developer negatively affected should be able to insta-revert the diff. How does a design document help?

It helps identify potential problems / conflicts across teams even before a single code is written (or development time committed).

I don't think so. Who looks at design documents? Your own team. If you don't yourself catch that a change will cause problems with other teams, the existence of a design document won't magically alert that team. If you do suspect that there might be a bad interaction with another team, you can alert that team with or without a design document.

So again: how does a design document requirement help?

Re: Why I close pull requests

#113

Post by zardeh »

fdsfsaa wrote: post #100
zardeh wrote: post #71

Earlier quoted context omitted.

To clarify here, what kinds of changes do you think require a design document?

I don't think any specific type of change should require a design document. That framing presupposes too much hierarchy. Design documents, like code reviews and tests, ought to be helpful tools for developers, not requirements imposed from above. I've worked at companies that didn't require design documents, but occasionally wrote them anyway because I wanted feedback. Another trigger could be a reviewer commenting,…

(to be clear, this is all made up)

Well let's put it this way, let's say that I'm a googler, I work on the android team and I want to rewrite the launcher from the ground up because I have some whiz-bang idea. This falls under my general purview of stuff that my team works on, so I grab my coworker, and for a month we hack away at it and have a good MVP. It has great improvements over the existing homescreen.

We've been working and reviewing each other's code, and so after a month we submit the big change that touches bunches of files out for review by all of the various owners of various affected components. One of them shoots me an email a few minutes later and says that this work is all wasted because another team has been secretly working on an updated launcher for the release of Google's new flagship phone, the Pixel, it already has some of our features, but also has many others, and has been in development for 6 months already.

So now my coworker and I have wasted 2 man-months of employee time on something. That's tens of thousands of dollars that goes poof when someone closes the pull request. And those 10s of thousands of dollars could have been saved with a 2 page document and a 1 hour meeting.

The goal of these things is to not waste developer time, because you or I can't be aware of everything going on in a company, so writing a design doc allows other people to see what you're doing and

1. provide insight and feedback from their experience with similar problems

2. provide prior art from within the company

3. remind you of things you might have forgotten about

4. give you insight into how these changes will affect others

5. most importantly, give you information about other activities the company is doing in this direction that are related to your proposal, so that if you can avoid destructive interference, and potentially have constructive interference.

Otherwise you end up with repeated work, wasted effort, and fragmentation.

Re: Why I close pull requests

#114

Post by zardeh »

fdsfsaa wrote: post #107
acjohnson55 wrote: post #102

Earlier quoted context omitted.

While I agree with you in principle, I have my doubts that that approach works at "Google scale".

What makes "Google scale" unique? I've never understood the argument that because Google serves ultraziggabytes of data, Google needs complex engineering practices. A program is the same program whether it runs on ten machines or ten thousand. Complexity is what matters, and while Google does solve very complex problems, other companies solve them too.

I think the point is that every company that works at this scale does more or less the same thing out of necessity.

Re: Why I close pull requests

#115

Post by zardeh »

fdsfsaa wrote: post #112
hhandoko wrote: post #106

Earlier quoted context omitted.

It helps identify potential problems / conflicts across teams even before a single code is written (or development time committed).

I don't think so. Who looks at design documents? Your own team. If you don't yourself catch that a change will cause problems with other teams, the existence of a design document won't magically alert that team. If you do suspect that there might be a bad interaction with another team, you can alert that team with or without a design document. So again: how does a design document requirement help?

>Who looks at design documents? Your own team.

At least where I work, no. Your team, your manager, and anyone who you think will be affected, and depending on the scale of the change, you inform everyone that uses your tool or works on your product so that anyone can provide comments and feedback.

Re: Why I close pull requests

#116

Post by dcosson »

fdsfsaa wrote: post #47
yegle wrote: post #13

At Google, if you want to implement new features (or large refactoring), you'll need to write a design doc. In which, you should answer questions your reviewers might ask (common questions like: why do you want to do this, what are the alternatives, how components interactive with each other before/after your change). This is something like Python's PEP: you need a proposal to convince your reviewer that you have put…

Requiring permission to do work is the enemy of progress and engineering dignity. It creates a presumption of incompetence and an atmosphere of low trust that punishes people who want to push the envelope of what's possible. Google's design document culture is bad. Google has succeeded in spite of it. In my experience, having worked at many large tech companies, design documents obfuscate, not enlighten. They become…

> A culture that requires permissions and signoffs before work can begin is a culture that leaves products stagnant for years.

I've also seen the exact opposite being the case. A culture where everyone does whatever they're in the mood for without running ideas by other teammates who will have different experience in different areas of the codebase, can leave products stagnant for years. Tech debt builds up and the size of change that anyone is comfortable doing gets smaller and smaller until large new features become unfeasible.

If the culture on the team is to mostly work on your own without spending time designing & brainstorming up front except in rare circumstances, then nobody wants to be the only person enforcing process on themselves. You might worry that you come across as a weak engineer if you ask for a lot of feedback and nobody else does, and it does slow you down some so you'll get less work done on individual projects than your teammates (and your solutions might be of a higher quality, but that tends to show itself as the absence of problems or only be visible in the future to the next person who works on your code, and those things are easy to overlook).

So IMO it's not a matter of a presumption of incompetence vs competence, the goal is aligning incentives so that collaboration and taking the time to come up with the best solutions become the most natural way to work.

(FWIW I've never worked at Google and can't speak at all to their implementation of a design document culture).

Re: Why I close pull requests

#117

Post by binoct »

fdsfsaa wrote: post #105
jimmywanger wrote: post #101

Earlier quoted context omitted.

> There are companies with data needs, user counts, and codebase sizes on par with Google that don't practice Google-style process, yet succeed anyway. Which? The ones I can think of are Apple and Microsoft, and I'm pretty sure they practice Google-style process. Amazon has its own flavour of process which is heavyweight in its own way. What are you thinking of? > Code-level concerns. You're not going to stop SQL inj…

It's funny that you mention Microsoft. A friend (he has ~100 reports, transitively) at Microsoft tells me that at least on his team, the old-fashioned three-specification (design, dev, test) document triplet, each with a multi-page checklist-laden Word template, has been supplanted by a lightweight scheme that boils down to one or two paragraphs. That's real progress. Microsoft even runs successful open source projec…

Uber's cars and Otto's trucks are different platforms I believe (for now at least.) The beer delivery was a publicity stunt, but definitely impressive. However it was largely made possible by a team who had spent years at Google figuring out how to do it :)

It's definitely possible for a team to come along and catch up/overtake the Google (now Waymo) project, but I agree with jimmywanger it's not a valid comparison for the sake of this discussion. Uber is following a different path than Google focused on, and is hugely benefitting (as is the whole industry) from the work done at Google.

Re: Why I close pull requests

#118

Post by vincnetas »

fdsfsaa wrote: post #47
yegle wrote: post #13

At Google, if you want to implement new features (or large refactoring), you'll need to write a design doc. In which, you should answer questions your reviewers might ask (common questions like: why do you want to do this, what are the alternatives, how components interactive with each other before/after your change). This is something like Python's PEP: you need a proposal to convince your reviewer that you have put…

Requiring permission to do work is the enemy of progress and engineering dignity. It creates a presumption of incompetence and an atmosphere of low trust that punishes people who want to push the envelope of what's possible. Google's design document culture is bad. Google has succeeded in spite of it. In my experience, having worked at many large tech companies, design documents obfuscate, not enlighten. They become…

Talking about desing documments i think internet would be a mess without RFC's (https://en.wikipedia.org/wiki/Request_for_Comments) which i think are formal design documents...

Re: Why I close pull requests

#119

Post by fdsfsaa »

vincnetas wrote: post #118
fdsfsaa wrote: post #47

Earlier quoted context omitted.

Requiring permission to do work is the enemy of progress and engineering dignity. It creates a presumption of incompetence and an atmosphere of low trust that punishes people who want to push the envelope of what's possible. Google's design document culture is bad. Google has succeeded in spite of it. In my experience, having worked at many large tech companies, design documents obfuscate, not enlighten. They become…

Talking about desing documments i think internet would be a mess without RFC's ( https://en.wikipedia.org/wiki/Request_for_Comments ) which i think are formal design documents...

RFCs are usually protocol specifications. Specifications are usually intended to facilitate interoperability. They document protocols or grammars or some other artifact. Specifications need to be well-written and precise.

The kind of design document that I frequently find superfluous isn't a specification of some protocol, but a prose description of the code one intends to write.

In concrete terms, an RFC might describe TCP header flags and the TCP state machine, but it'd be silent on the Linux kernel's sk_buff structure. A design document would describe sk_buff in detail.

Re: Why I close pull requests

#120

Post by fdsfsaa »

zardeh wrote: post #113
fdsfsaa wrote: post #100

Earlier quoted context omitted.

I don't think any specific type of change should require a design document. That framing presupposes too much hierarchy. Design documents, like code reviews and tests, ought to be helpful tools for developers, not requirements imposed from above. I've worked at companies that didn't require design documents, but occasionally wrote them anyway because I wanted feedback. Another trigger could be a reviewer commenting,…

(to be clear, this is all made up) Well let's put it this way, let's say that I'm a googler, I work on the android team and I want to rewrite the launcher from the ground up because I have some whiz-bang idea. This falls under my general purview of stuff that my team works on, so I grab my coworker, and for a month we hack away at it and have a good MVP. It has great improvements over the existing homescreen. We've b…

Coordination is important. I think you can achieve it without a formal design document and approval process. Your team could post a quick, informal message to a mailing list saying that you're going to work on a new launcher. The other launcher team could then reply and suggest getting together to talk about common plans and avoiding duplicate work.

I'm not suggesting that communication is bad. I'm objecting strenuously (perhaps stridently) to the design document as a step in a rigid process and a requirement imposed from above.

Personally, I'd rather see two teams work toward our improved hypothetical launcher than to see zero teams do that work because process imposed too high an "activation energy" on the launcher experiment.

Also, why are both teams working in isolation for a month? If both teams check in code, the checkins themselves can provide an indication that other people are working in the same area. Incidentally, it's this effect that makes me strongly dislike feature branches. It's better to develop unstable code behind a feature flag, where the code is visible even if not active, than in a feature branch, where nobody can see it.

(It's true that not all changes can be gated behind a flag, but most can be.)

Post reply on HN