Introducing draft pull requests (opens in new tab)

My team recently started requiring an implementation proposal on the issue that has to be approved by their peers. It saves a lot of wasted effort by exploring the problem domain collaboratively before development begins.

Someone suggested this on my team. I personally don’t like the idea because these policies often times lead to bureaucracy and then nothing getting released. It is not that I am against thinking ahead but if i have to in details explain everything I do, then more time is spent documenting than actually creating which is the part I enjoy.

Why not add the plan of attack to the issue in the issue tracker?

Back when I was first doing XP style development, we did everything with trunk based development (TBD). As a rule, we pushed to trunk (master) every 20 minutes or so. Since we were all co-located (i.e. in the same time zone and working relatively similar hours) it meant that there would be a push to trunk every 5 minutes or so (frequency depended on the team size, of course). We read all of the diffs between trunk and our branch before we merged our code -- and integrated with any changes.

Probably most people won't realise, but it was in that kind of situation that "continuous integration servers" came into being. The idea was that after you pushed to trunk, the tests would run (and in those days we slapped your fingers if the test suite ran for more than a minute or two -- for reasons which will become obvious) and you would have a minute or two to fix any gaffs you made merging conflicts, etc. If you wanted to merge your code, you would wait until the CI server gave a green light, so if the tests were slow, it would be a major PITA.

The massive upside of this process was that you always knew what your colleagues were planning to do. You saw all their progress every 20 minutes! You integrated with their changes! If you saw a problem, you yelled over the cubicle wall and said, "Hey that won't work because I'm doing X" -- saving both you and your colleague hours of wasted effort.

TBD in this style is hard, but very rewarding. The main reason I don't practice it these days is because 1) We have continuous deployment and you don't want to deploy unfinished work 2) The teams I work on these days are distributed (and I'm 9 timezone hours away from their day). However, I really miss that immediate feedback and the seemingly effortless way in which everyone on the team is kept completely in sync. I've never found anything that even comes close (and I've done the "preliminary PR" thing many times).

Indeed, code review shouldn't be architecture review. At that point it's too late and the friction/cost of revisiting the structure is often high. Early sign-off on broad strategy is great for productivity even if it takes a while to document the approach ahead of time.

We do this as a design document on a wiki. It's more long lasting that way and richer with better text and media support.

One of my previous teams used to do something similar, but the initial PR would be for a change to the docs for the project. Would be great, because the docs would be updated to reflect any new changes automatically.

Is there actually a way to do this, if there is no code difference between your new branch and the base?

Opening a Draft PR-

* Signifies that the work is being done, preventing duplicate efforts.

* Shows people all the work being done in a single location, rather than having to hunt down forks and branches.

* Gives a nice UI showing the exact changes, without having to compare to specific commits.

* Gives a review interface, where people can comment on the code itself or even on specific lines.

All your other points still stand- you still create one branch per feature, check in frequently and push up work. If you explicitly want a review you can ask people for it (as you already do), but now they have a nice place to do it.

I see PRs with titles prefixed "DO NOT MERGE" or "WIP". People want the UI that goes along with a PR, prior to it being ready to merge.

I use and ask other team members to make draft PRs now (ad-hoc, basically the subject includes "WIP").

#1. PR triggered checks will fire

#2. You use the same tools for reviewing and can leave better comments

#3. I like PR comments to be detailed and explain the changes well for non-team members. Composing the draft message can help reveal items I need to make clearer or need to still do.

#4. It's clearer which branches/tasks are still being worked on, and how the work is progressing.

This works well on your own project, when you have permission to create branches... but what if you're trying to contribute to some other large and complex project? "Go look at my forked branch" isn't a great way to discuss a feature.

The blog post seems to specifically answer this question far better than anyone here could. It essentially formalizes a workflow like the one you describe.

Remember than anything GH does “can be done by email”, to cite some early commentary. But collectively, the ease of use, and defaulting to best practice, that GH introduced have vastly improved and enlarged the open source community.

I know I never submitted patches in the 10+ years in the industry pre-Github. Now, barely a week goes by without at least one PR.

In a draft PR you can add a description and annotate lines of code with comments - making it easier for your peers. A branch can be harder to find and in your case you had to manually notify that you wanted them to have look at your code, whereas with a draft PR you probably get a notification.

Why not have everyone create their PRs against a feature branch instead of master, and merge the feature branch into master when the project is done?

One of the benefits of mono-repos

Do you mean link multiple PRs across multiple repos? You can already merge multiple commits together in the same PR, in a single repo, of course. via branches.

If so, this can't be done within git, since the overall container is a single repo.[1] There is no atomicity or even coordination between repos. You can get loose coordination though via integration with an issue tracker like jira. The tracker links multiple PRs across multiple repos into a single meta-merge. But you aren't going to get "simultaneous merge" in the sense of a single atomic cross-PR and cross-repo commit.

[1] One of the things that is awful with github [not git itself], is that all your controls such as commit rules, privileges, visibility, have the granularity of the entire repo. Even though awful, this is the right approach considering that many git restrictions are per-repo, eg branches. vs perforce, eg

I think the way git supports this workflow currently is to have a super-repo containing all the other repos as submodules. You can bundle all those changes together as updates to the submodule references in a single PR.

Gerrit supports this feature. You just add "Depends-On: changeID" in your commit message.

Phabricator can do it, you can add child revisions to any differential. It's quite nice.

I don't know if I would call it GitLab's concept. Every place I have worked at that has used github has had the idea of a Work In Progress pull request. Its a pretty natural concept for an multi-member development team. So much so that all of the places I have used it have written explicit CI checks that would check for a label on the PR or the title to be in a given format and would fail to make sure you couldn't merge the branch until WIP was removed.

I doubt it. I've heard interviewees for years on podcasts talk about opening a PR as a means to discussing something long before the code is actually ready. Seems like this is just a feature following a common though informal common practice.

Well, I guess there’s nothing wrong with Github replicating good ideas, considering Gitlab is pretty close to an identical clone.

> We want fast, continuously integrated code that is merged early

For some projects maybe.

Other projects want changes to be very carefully presented, considered and reviewed.

> it's not supposed to work that way

According to who? Is this how you do things at work? Ok, but other people work differently. There’s not authority in programming to set what we’re ‘supposed’ to do.

> is this pushing back progress made in CI coding practices?

Seems orthogonal to me. You can run CI on a branch.

But overall, no not everyone’s development is a mad dash to get everything merged instantly and some want carefully created PRs.

I often write just my database models, or just my API/schema first. It's typically syntactically correct, but entirely non-functional.

I'll sometimes open a PR for this with "WIP" in the title, "DO NOT MERGE" in the body, or without the "For review" label that we use.

These PRs serve to facilitate discussion, start knowledge sharing, and update other developers on my progress more clearly than a branch they might have to check more carefully. However I would definitely not want to merge one.

I love CI/CD, we do a lot of it and try to have small changes and feature flagging as much as possible, but this feels pretty useful in general for us. Yes it could be mis-used, but I don't think that's a reason not to have the feature.

It really does depend on what you're developing and what you're shipping. Even minutia like language and build systems influence what's a convenient way to manage in progress work. I'm much more tolerant of dead-code/feature flag branches in certain parts of my codebase than others even. Sometimes you know exactly what you're building, but other times you're trying to sketch out an idea to see what it might look like and to get buy-in for a feature. You'll need to decide if you want to put the drag of partial work on everyone else who's making changes or on yourself to keep up with HEAD.

It's a choice.

All that said I think this feature in github is minor enough that it'll make what people were doing already more convenient (UX win) but won't substantially change how people work. It's just not dramatic enough.

If you use the `CODEOWNERS` feature, it won't auto-ping anyone until it comes out of the draft state.

The differences seem minor to me. I create draft PRs all the time and probably won't bother with using this feature, because I usually open PRs using the `hub` tool or via VSCode, and only rarely via GH web site.

That will send notifications to all code owners, which a draft PR will not

Doesn't always work - if you're not a write-access collaborator on a repo, you can't add labels.

That requires social knowledge of reviewers to not merge WIP stuff (and/or avoid missing WIP labels/notes). These draft PRs make it much more obvious in the "Merge Checks" at the bottom of the PR by blocking the PR from merge until no longer a draft (marked "Ready for Review").

Yeah, my normal Gitlab workflow is:

1. Start a branch with a first commit 2. Open a PR and write details / background 3. Mark WIP 4. Eventually remove WIP and add someone as reviewer.

Glad to see this is available now.

I count 17,800 cases where someone accomplished the same thing by typing 3 letters.

I've done this many times myself, and I hope nobody was counting those as a feature request.

The difference is whether the author of the pull request considers his code not ready for review or not. Both are work in progress but they need different treatment.

I need this as well. I have a ton of PRs with WIP labels.