Repository navigation
[Doc]: gitwash deleting main branch #25857
Description
Documentation Link
Problem
Our dev guide has advice to consider deleting your main branch, with a link to this pretty old page. I see two problems with the linked advice
-
It describes
masterinstead ofmain, and it may not be obvious for someone who is new to open source that that is just an old name for the same thing. Also there were good EDI reasons whymasterwas dropped. -
the instructions for deleting the branch and setting up
placeholderas your new default branch are fairly involved. These days you can just rename your branch within GitHub, which I think will have the same practical effect with less effort.
Suggested improvement
I see two options
-
just remove the advice about deleting the
mainbranch (but retain the advice to not develop with it). -
remove the advice about deleting the branch, but add some advice to rename it instead. I think this would fit better in the setting up instructions as you’d want to do it before you clone.
I have a slight preference for 2, but I think that’s just because my default branch is placeholder, having followed gitwash in the past. I’m not sure I have a strong argument that it’s better to rename than to leave it as main.
Activity
story645 commentedon May 11, 2023
My bias is to remove the advice about deleting it - it's not a practice consistently followed by the devs, which means that a bunch of us rely on it being there when trying to help contributors untangle their commit logs. Most guides written to help untangle and to help sync also assume the presence of a local main.
I'd rather add more language about why starting the feature branch on main is a bad idea w/ maybe a link out to some advice on what to do if they've done that.
timhoffm commentedon May 11, 2023
I don't understand what the benefit of renaming is. local
main,upstream/main,origin/mainare still the distributed variants of the same branch. Renaming part of that feel confusing. IMHO one should either delete a branch or leave it in place (untouched).jklymak commentedon May 11, 2023
I think the only distinction is didactic. When you start with git it's not really clear what the difference between main, upstream/main, origin/main all are and how they talk to each other. When I started I thought they all did talk to each other somehow. It's very elegant, but confusing at first, particularly if you are just trying to get something done. Conversely if you never have a "main" it's clear that your "placeholder" is a completely separate thing and you need to sync it up manually.
story645 commentedon May 11, 2023
As much as I know we don't want to write a how to git guide, I wonder if we should just add something like:
Edited to try and make owner ship and source of truth clearer.
rcomer commentedon May 11, 2023
Having an out-of-date local
main(orplaceholder) shouldn’t matter if you are creating feature branches offupstream/main.story645 commentedon May 11, 2023
We should mention it in our guide too. So proposed revision is:
And we put that at the top of https://matplotlib.org/stable/devel/development_workflow.html so it explains why the guide always uses upstream?
timhoffm commentedon May 11, 2023
If we want to go into the remote+branch details, https://matplotlib.org/stable/devel/development_workflow.html should get one (or two) visualizations.
Something similar to (taken from https://www.tomasbeuzen.com/post/git-fork-branch-pull/):
This is still not exactly how I would draw it because it mixes setup (fork, clone) and the PR workflow (pull, push, pull-request). These should better be in separate diagrams. Possibly one would also want to annotate the used branch names and/or the github URLs of the remotes.
story645 commentedon May 11, 2023
Might be a good way to anchor and differentiate https://matplotlib.org/stable/devel/development_setup.html and https://matplotlib.org/stable/devel/development_workflow.html (currently I'm like why are they not on the same page?)
rcomer commentedon May 12, 2023
I think we should be cautious about adding content to the dev guide. Nothing wrong with the above suggestions in themselves, but the dev guide as a whole is quite extensive. I think there's a danger that puts people off reading it at all. I once decided not to bother putting a small change in a script because the working practices document for the repo it was in was huge!
oscargus commentedon May 12, 2023
I think it often makes sense to have a TLDR approach. Brief information and then you can read up on parts where needed. Also, there is a difference between "this what we expect you to do" and "this is how you do what we expect you to do and some help to get you there".
With that said, it is extremely hard to write text that is both flexible in the sense that one know what can be skipped, but also contains information for all different types of background knowledge...
jklymak commentedon May 12, 2023
I agree. I think for git workflows we should state what flow people need to use (because it actually is different from personal repo use), and link out to a few guides we like that explain that workflow. Gitwash started out as such a guide, and if a modern good one doesn't exist, maybe we need to write one, but I'm not sure it belongs on our site.
story645 commentedon May 12, 2023
Yeah I think @melissawm and/or the folks at scientific python wanted to write a kinda of modern gitwash for the community.
I think the tldr approach makes sense, but then I think we should commit to that consistently, which would mean reshuffling the development guide so that the commands are also at the top or the guidance list is interwoven with the steps they apply to - which honestly probably would resolve the original issue since we'd remove any bullets not explicitly related to a step we're describing.
I don't think that's in conflict though with having a small figure or graph that shows the commands since that's a skim. - also if we make a dev quick-start guide, it's a good way to visually separate but keep setting up and workflow on the same page.
matthew-brett commentedon May 12, 2023
Only to say - as the original author of Gitwash - that I'm totally happy for anyone to either - rewrite Gitwash itself - or start from scratch and suggest that we all use that instead of Gitwash.
melissawm commentedon May 15, 2023
As a note - my initial suggestion was to leverage existing documentation from git/github (which has gotten a lot better) instead of writing our own. That would also reduce maintainer workload and ensure we would have it up-to-date. My approach here would be to go with the minimal information needed for basic development and link out to official docs for other, more complicated workflows.
For example: https://docs.github.com/en/get-started/getting-started-with-git/about-remote-repositories
These also have the advantage that they are translated into a number of human languages, not just english.
tacaswell commentedon May 15, 2023
I am very much in favor of replacing as much of our "how to git" docs with links to github's (or git's) documentation. Compared to a decade ago, git and github/gitlab are orders of magnitude more mainstream than they were and we should not have the expectation of needing to document the basics.
We do need to keep a couple of special-to-us-things (like we like re basing more than many projects (but much less than others I know of)), but how to push/fetch, merge, commit, etc should just be links....
story645 commentedon Jun 26, 2023
#25948 closes the immediate issue and the rest of the discussion should be had on a "reorg dev docs" specific issue/PR