Improve git setup instructions #20102
Conversation
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
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. |
13790cb to
caba923
Compare
|
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. |
1. Gitwash should be dropped for various reasonsIt's outdated. It's not maintained. It's too long (13 pages!). It's not targeted enough. 2. We still need basic instructions how to set everything upSetting 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 ourselvesWhile in principle
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.
I do have:
|
|
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). |
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:
(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. |
If you only work with your repo, you don't need a second remote. If you work with any larger project you do.
The |
|
What about a small line/section: Get latest changes: 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. |
| .. code-block:: | ||
|
|
||
| git remote add upstream https://github.com/matplotlib/matplotlib.git | ||
|
|
There was a problem hiding this comment.
I guess I'm just thinking a bit of explanation beyond the amorphous "connect". i.e.
| Adding the `upstream` remote allows you to `rebase`_ your version of the code against any changes that are made to main project after you start your changes. | |
| .. _rebase: link to wherever we describe rebasing... | |
|
I'll check later. |
|
This is superseeded. All relevant information is now in the docs. |
PR Summary
Inspired by NumPy and pandas.
This is aims at eventually removing the somewhat outdated and fuzzy gitwash docs.