just what is the level of fluency with git that we expect & into how much detail do we want to go?

Little fluency, little detail 😄 :

Users should be able to follow the first steps by copying the commands we show them without having to understand git. With that they should manage to

1. set up the repo
2. to create a branch, add a commit and push
3. change back to master and pull updates

Points 2. and 3 are still to write. https://pandas.pydata.org/docs/development/contributing.html#creating-a-branch and https://numpy.org/doc/stable/dev/index.html#development-process-summary are good templates.

I think it's kinda hard to commit this without 2 & 3. Where does this stand with respect to gitwash? What is the advantage over what we already have?

Fwiw I think the gitwash stuff should be dropped. So far as I can tell it is abandonware and we can't have a big chunk of our docs depend on something we can't push changes to. OTOH the idea is good. It's silly for every project on the planet to have slightly different, but fundamentally the same, guide to GitHub just with different project names. But we probably should have a plan, perhaps in coordination with other projects.

I think it's kinda hard to commit this without 2 & 3. Where does this stand with respect to gitwash? What is the advantage over what we already have?

1. Gitwash should be dropped for various reasons

It's outdated. It's not maintained. It's too long (13 pages!). It's not targeted enough.
I think we agree here.

2. We still need basic instructions how to set everything up

Setting everything up is not trivial. We don't want to loose potential contributors because the give up on getting the dev install to work or on making a PR. What we currently have outside of gitwash is not sufficient; e.g. it describes direct cloning from matplotlib/matplotlib and not using a fork.

3. We'll have to write these ourselves

While in principle

OTOH the idea is good. It's silly for every project on the planet to have slightly different, but fundamentally the same, guide to GitHub just with different project names. But we probably should have a plan, perhaps in coordination with other projects.

Gitwash died for lack of interest. Why should a new coordinated attempt work? I believe the level of detail and context of a getting started guide is too project specific and subjective, e.g. numpy is more terse than pandas. Both projects have really thought about their docs, and IMHO the difference is justified and on purpose: Numpy contributors are most likely more experienced than pandas contributors (and possibly also have to be as the numpy codebase is more difficult). IMHO any coordination would either iron over project needs or end up in endless discussion.

I'm willing to invest a couple of hours to wirte a concise guide for Matplotlib, but I'm not going to make this a larger scale project. If you have ambitions there, I'll stop the project and let you take over.

But we probably should have a plan

I do have:

1. Write a basic intro for

   • set up the repo (this PR)
   • create a branch, add a commit and push (next PR - not enough time to make everything at once)
   • change back to master and pull updates (next PR ...)

   As written above, I'll take pandas/numpy as a template and cook up a version that seems right for Matplotlib.

2. Drop gitwash

3. Move on

No that makes sense to me.

I do feel that the write up needs to be complete though. Merging 1/3 of it would be confusing if the other 2/3 got forgotten for a while.

I plan to write these in the next few weeks, definitively before 3.5.

I fell that the three parts are largely indepenent and this PR would still be a net gain (the only downside being that it overlaps with gitwash, but I don't think many people would read that anyway).

and this PR would still be a net gain

maybe? It read to me like it stopped in the middle of the subject. It goes from adding an upstream remote to installing, which seemed a non-sequitur. Maybe it'd make sense if you just took adding the remote out?

I see cloning and adding a remote as belonging closely together. While you could start without the remote, you'll need it eventually when you want to pull in recent changes. Thus I believe this belongs in "Setting up git" and also that you should do it right away to have a "standard configuration".

I find the sequence of operations as laid out in the section titles quite natural:

1. Setting up git and retrieving the latest version of the code
2. Creating a dedicated environment
3. Installing Matplotlib in editable mode
4. Installing additional dependencies for development

(Well, you can debate if you want to switch 3 and 4. There's reason for both.)

If you don't tell people what to do with the remote they are going to wonder why you have this relatively obscure extra step and skip it.

I would guess that 95% of GitHub users never set a second remote, because they don't need one for their own repos. The idea of multiple remotes is super confusing for the first little while. I think it would be better to leave this off, and intorduce when needed, or explain why it's needed here.

I would guess that 95% of GitHub users never set a second remote, because they don't need one for their own repos.

If you only work with your repo, you don't need a second remote. If you work with any larger project you do.

or explain why it's needed here.

The GitHub help: add remote link is right there for further information. This is intentionally brief to not clutter the docs. Compare the numpy and pandas docs linked above which are also adding the remote immediately (I cite them as sort of a reference because both projects have put significant thought into their docs recently).

What about a small line/section:

Get latest changes:

git checkout master 
git pull upstream master

Or are you supposed to rebase against master?

Somewhere before this should probably be a make a branch section so it's be ok to use checkout here.

@jklymak @story645 thank you for your feedback.

It appears, I cannot get my idea across in this step-wise approach and it's causing unnecessary discussion. I'll hold of until I find time to write up the full changes. Feel free to take over before that if you want to move this forward more quickly.

Given #23588 and #24662 what do we want to do with this PR?

I'll check later.

has this pr been superseded by #26201 and #23588?

This is superseeded. All relevant information is now in the docs.