Unclear message about base repository when creating a PR

I suppose this has recently changed in #1706. The current prompt is confusing to me:

$ gh pr create
? Which should be the base repository (used for e.g. querying issues) for this directory?  [Use arrows to move, type to filter]
> liberapay/liberapay.com
  waldyrious/liberapay.com

There are two issues here:

I am not sure what "base repository" means here; my mental model when creating a PR is one of "source" (e.g. my fork) and "target" (e.g. upstream), and I could interpret "base" as referring to either of these.
It's not clear what "for this directory" means. I would expect something like "...for this PR", but I guess something different is being asked here, and the message doesn't tell me what.

Note: I had erroneously committed to master instead of to a feature branch before creating this PR — I suppose that may be why I saw this message. Regardless, gh didn't help me figure this out, but instead confused me further; so I suppose the message could be clarified.

@waldyrious

@waldyrious Thank you for the feedback, I can understand how the messaging can be confusing. There is definitely room for improvement in the pr create messaging and we will take your feedback into account as we continue to iterate on this feature. 🙇

@waldyrious

@waldyrious Thank you for the feedback!

The concept of a "base" repository is not just specific to the pr create command, but to most other commands. The "base" repository is the GitHub repo where the majority of the maintenance happens; i.e. PRs get submitted to it, issues get filed in its issue tracker, Releases get created in it, and so on.

We weren't sure how we could name it more descriptively, but if you or anyone has suggestions, we're all ears.

Thanks for the context. I would say that meaning of "base" you describe matches what I'd intuitively call an "upstream", "canonical", "primary"/"main", or "original" repository. These are just from the top of my head, so I'd be happy to contribute to discussions in case these have shortcomings I might be overlooking.

@ampinsk

Switching away from "base" here makes sense to me since "base" means something in git terms. I like the idea of "primary". @ampinsk do you have thoughts?

This is a tough one, but I'm partial to main. This may be tough to find a word that makes sense to 100% of people. I also feel that the parenthetical in the middle of the prompt makes the prompt more difficult to read. If we want to give an example, I think we could list it at the end.

Choose a repository to use as the base for querying issues and submitting PRs.

Could this make more sense?

Choose a repository to use as the base for querying issues and submitting PRs.

Could this make more sense?

I think the "and submitting PRs" definitely helps, as well as the removal of "for this directory" (was that intentional?).

Here's a thought: why not simply remove "as the base" from the sentence? And maybe also switching "a repository" to "the repository":

Choose the repository to use for querying issues and submitting PRs.

@waldyrious

@waldyrious I like that! Thanks for the copyediting help 😄 The only lingering problem with this is that querying issues and submitting PRs aren't the only things that selecting the "base" repository affects. It also affects querying PR lists, creating issues, etc. Basically all read/write operations. So to avoid listing out every single thing this decision means, we do need some general way to talk about this concept 🤔

In that case, how about something like this?

Choose the primary remote (used for querying issues, submitting PRs, etc.) for this repository

@waldyrious

@waldyrious I like that! I think it's clearer than what we have today 👍

I also confuse at the first place..

@waldyrious

Just chiming in here since I was also confused by this message when running gh pr checkout for the first time. Is there a reason @waldyrious's suggestion hasn't already been incorporated (as of version 1.9.2)?

@samestep

@samestep No real reason except inertia. But, we are planning to do improvements around the "base repo" experience that go beyond just renaming the prompt.

Honestly if you just removed the word base it would make so much more sense. Or renaming base to "default".

Current:

Which should be the base repository (used for e.g. querying issues) for this directory?

Proposed:

Which repository should gh use for querying issues, submitting PRs, etc. for this directory?

Choose a default repository for gh to use for querying issues, submitting PRs, etc. for this directory:

This really confused me today. I just started using gh and I ended up selecting my fork -- which made a PR a to my fork and since I referenced an issue in the project repo github a reference in that issue to the PR in my fork! 🤣🤣

Some other ideas for wording it:

"Which repo is the main repo? (The repo which you submit PR's to, or list issues from, etc)"

"Choose the base (or original) repo. This is the repo that you submit PR's to, contains the issues, and etc." 👀👈👍

Apart from that, it would be good if the explanation was written out in the help. At first I cancelled what I was doing and looked in gh pr create --help but there was no good explanation there for what base meant.

My other issue that I came looking for was that after I selected the wrong one (my fork) I couldn't change it (or it wasn't obvious how to do so anyway). So I had to start over from scratch. If there is a way someone please tell me. 😎

So I had to start over from scratch. If there is a way someone please tell me.

Sorry for the nuisance! #2300 (comment)

As a quick update here, there's work being done to improve/clarify base repositories here: #4859

Thanks all for your feedback. In the latest release we replaced the "base repository" prompt with a dedicated command gh repo set-default which should be clearer. Please leave your feedback about new functionality here; thank you! #6777

Thanks for addressing this! I've left a comment in the discussion.

Navigation Menu

Repository navigation

Unclear message about base repository when creating a PR #2090

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Unclear message about base repository when creating a PR #2090

Description

Activity

waldyrious commented on Oct 4, 2020

samcoe commented on Oct 5, 2020

mislav commented on Oct 5, 2020

waldyrious commented on Oct 5, 2020

vilmibm commented on Oct 22, 2020

ampinsk commented on Oct 29, 2020

waldyrious commented on Oct 29, 2020

ampinsk commented on Oct 29, 2020

waldyrious commented on Oct 29, 2020

ampinsk commented on Nov 5, 2020

zigang93 commented on Dec 3, 2020

samestep commented on May 11, 2021

mislav commented on May 11, 2021

bhajneet commented on Aug 9, 2021

1dancook commented on Nov 24, 2021

mislav commented on Nov 24, 2021

darcyclarke commented on Mar 16, 2022

Griffin641498 commented on Apr 22, 2022

JohSteph890 commented on Oct 10, 2022

mislav commented on Dec 22, 2022

waldyrious commented on Dec 24, 2022

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions