| Message ID | 20210811045727.2381-1-felipe.contreras@gmail.com (mailing list archive) |
|---|---|
| Headers | show |
| Series | stage: officially start moving to "staging area" | expand |
Felipe Contreras venit, vidit, dixit 2021-08-11 06:57:20: > In the last 13 years of discussions virtually *everyone* has agreed that > the term "the index" is not a good approximation to how most users > perceive and utilize this feature. For a summary of the discssions see > my blog post [1]. > > This is particularly true of newcomers, which is why everyone that > teaches git uses the term "staging area". > > Among all the proposals for a better name "staging area" is by far the > one with the most consensus. > > Everyone except two people agreed that "the index" is not a good term. > > All non-official documentation already uses the term "staging area" [2] > [3] [4], including what is considered by most people the best > documentation out there: the Pro Git book. > > There is absolutely no reason not to start using the term "staging area" > officially. > > Let's start by making the staging area a first-class citizen and making > 'git stage' a prominent command, similar to 'git branch'. Additionally > add 'git unstage' too. > > Only *one* person expressed discontent with the term "staging area". > > In favor: > > * Felipe Contreras > * Scott Chacon > * Jonathan Nieder > * Matthieu Moy > * Jeff King > * Miles Bader > * Ævar Arnfjörð Bjarmason > * Jay Soffian > * Pete Harlan > * Aghiles > * Piotr Krukowiecki > * Phil Hord > * Victor Engmark > * David (bouncingcats) > * Alexey Feldgendler > * Alexei Sholik > * Zbigniew Jędrzejewski-Szmek > * Sebastien Douche > * Thiago Farina > * Mark Lodato > * Philip Oakley > * William Swanson > * Ping Yin > * Hilco Wijbenga > * Lars Vogel > * David A. Wheeler > > [1] https://felipec.wordpress.com/2021/08/10/git-staging-area-rename/ > [2] https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository > [3] https://www.atlassian.com/git/tutorials/saving-changes > [4] https://coderefinery.github.io/git-intro/04-staging-area/ Of the many possible ways to restart this discussion, calling out names and pitching people against each other is quite possibly the worst. Incidentally, this proves (again) what I wrote back then. Git (the project) has always been about the strive for the "best" solution, and different people have different views about the metrics (technically sound, user friedly, consistency, backwards compatibility ...), their scales and their relative weights - and the same is true for judging a particular suggested solution in these metrics. There are definitely more than two "staging camps" in this community - you can come up with a count of "2" only if you conflate a multitude of aspects, such as: - use the term staging area in documentation - scratch the term index from the documentation - use "--staged" option aliases - rename "--cached" option to "--staged" - use "stage" command alias for "add" - rename "add" to "stage" (and possibly revamp) - use pseudorev STAGE (and dump "--cached") - use pseudorev INDEX (and dump "--cached") - one of the above plus WORKTREE - ... I would in fact think that this community is comprised of individuals rather than camps, and that overall it does not object against the use of "stage/staging area". At the same time, the fact that 13 years on we still have the same "git diff --cached" etc. indicates that we never had an alternative concept and implementation which the majority agreed on. So, depending on how you conflate the aspects above into two, either the "pro" or the "contra" camp consists of 1 person, and you can certainly reach most 2-partitionings. Just imagine someone who thinks purely in terms of "technically sound" and "backwards compatible" (you know who you are ;) ): that person will never be "pro stage" or "contra stage", but if they don't like your implementation of "git stage" you will put them in the "contra camp", giving up all chances of winning them over technically. [As a side note, index might be more l10n-friendly than stage because of its latin origin (so it's there in more languages already).] I have been away from the project quite a bit (merely for lack of time), but some people will remember me as striving for "consistency" in the UI (e.g., favouring "git diff [HEAD] INDEX" over "git diff --cached [HEAD]"). Independent of my remarks about the restart of the discussion, I had a quick glance at this series. The questions which arose already around "stage/staged" seem to indicate that the series is more about renaming, some reorganising but not so much about a fresh look at a consistent user experience. In other words (and to show a way forward), a cover letter with the potential to bring many on board could start with: ## It has been 13 years that we discussed about "the index", "the cache", "staging" and the "staging area". There seemed to be overall consensus that the concept of "put something on stage that is to be committed [to]" serves well in training and documentation when we explain git's index and related commands which change the index (git add) and compare to it (git diff --cached). Let's try and find a common ground for implementing this in user facing commands. Here are a few possible appoaches: - command/option aliases - command/option renaming - revamping of the command structure (as we did "checkout->switch") - revamping the rev UI (from "--cached" to "INDEX" or "STAGE") - you name it To kick start this, here are a few more thoughts on some of these/an example implemenation for one of these/... ## Cheers Michael
Michael J Gruber wrote: > Felipe Contreras venit, vidit, dixit 2021-08-11 06:57:20: > > In the last 13 years of discussions virtually *everyone* has agreed that > > the term "the index" is not a good approximation to how most users > > perceive and utilize this feature. For a summary of the discssions see > > my blog post [1]. > > > > This is particularly true of newcomers, which is why everyone that > > teaches git uses the term "staging area". > > > > Among all the proposals for a better name "staging area" is by far the > > one with the most consensus. > > > > Everyone except two people agreed that "the index" is not a good term. > > > > All non-official documentation already uses the term "staging area" [2] > > [3] [4], including what is considered by most people the best > > documentation out there: the Pro Git book. > > > > There is absolutely no reason not to start using the term "staging area" > > officially. > > > > Let's start by making the staging area a first-class citizen and making > > 'git stage' a prominent command, similar to 'git branch'. Additionally > > add 'git unstage' too. > > > > Only *one* person expressed discontent with the term "staging area". > > > > In favor: > > > > * Felipe Contreras > > * Scott Chacon > > * Jonathan Nieder > > * Matthieu Moy > > * Jeff King > > * Miles Bader > > * Ævar Arnfjörð Bjarmason > > * Jay Soffian > > * Pete Harlan > > * Aghiles > > * Piotr Krukowiecki > > * Phil Hord > > * Victor Engmark > > * David (bouncingcats) > > * Alexey Feldgendler > > * Alexei Sholik > > * Zbigniew Jędrzejewski-Szmek > > * Sebastien Douche > > * Thiago Farina > > * Mark Lodato > > * Philip Oakley > > * William Swanson > > * Ping Yin > > * Hilco Wijbenga > > * Lars Vogel > > * David A. Wheeler > > > > [1] https://felipec.wordpress.com/2021/08/10/git-staging-area-rename/ > > [2] https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository > > [3] https://www.atlassian.com/git/tutorials/saving-changes > > [4] https://coderefinery.github.io/git-intro/04-staging-area/ > > Of the many possible ways to restart this discussion, calling out > names and pitching people against each other is quite possibly the > worst. Incidentally, this proves (again) what I wrote back then. Everyone already agrees that "staging area" is a better term than "the index". > Git (the project) has always been about the strive for the "best" > solution, and different people have different views about the metrics > (technically sound, user friedly, consistency, backwards compatibility ...), > their scales and their relative weights - and the same is true for > judging a particular suggested solution in these metrics. > > There are definitely more than two "staging camps" in this community - > you can come up with a count of "2" only if you conflate a multitude of > aspects, such as: For any question there's always three camps: in favor, against, neutral. In the particular question of "staging area" versus "the index" the consensus is overwhelmingly in favor, very very few are neutral, and only one person is against. > - use the term staging area in documentation > - scratch the term index from the documentation > - use "--staged" option aliases > - rename "--cached" option to "--staged" > - use "stage" command alias for "add" > - rename "add" to "stage" (and possibly revamp) > - use pseudorev STAGE (and dump "--cached") > - use pseudorev INDEX (and dump "--cached") > - one of the above plus WORKTREE > - ... Each one of these questions has different people in favor/against/neutral and they are mostly orthogonal to each other. For example a person can be in favor of adding the term "staging area" in the documentation but neutral to the "stage" command alias. Either way the whole point of my proposal was to shine a light to the question we have all agreed to: "staging area" versus "the index". This means by extension that everyone (except one person) would be in favor of using the term "staging area" in the documentation, which is your first point. Each one of those points could be implemented in a different patch series, and each patch series can be discussed separately. But my main concern is the *first* patch series, regardless of which it is, so the term finally becomes official. If you don't like the first patch series that I chose, then please state which would it be easier for you to get behind and I'll gladly work on that. I also have a patch series that implements --stage everywhere, and that series already received feedback in 2014. The reason why I chose this point is that 1) it's the one that I find more useful, 2) it's the one that it's easier to implement, 3) already received positive feedback, and 4) I wasn't the only one who suggested this. In case you don't remember, you yourself stated "in principle I like this a lot" [1] back in 2011. > I would in fact think that this community is comprised of individuals > rather than camps, and that overall it does not object against the use of > "stage/staging area". Junio objects to the use of the term "staging area". > At the same time, the fact that 13 years on we still have the same > "git diff --cached" etc. indicates that we never had an alternative > concept and implementation which the majority agreed on. No it doesn't. Git is not a democracy: the majority can agree on something and yet if Junio disagrees, that's the end of that (as is the case here). > So, depending on how you conflate the aspects above into two, either the > "pro" or the "contra" camp consists of 1 person, and you can certainly > reach most 2-partitionings. > > Just imagine someone who thinks purely in terms of "technically sound" > and "backwards compatible" (you know who you are ;) ): that person will > never be "pro stage" or "contra stage", but if they don't like your > implementation of "git stage" you will put them in the "contra camp", > giving up all chances of winning them over technically. No. Being against a particular patch series doesn't necessarily mean against the spirit of the patch series. If that person would rather start with the --stage aliases, or using "staging area" in the documentation, then that person can simply state so on this patch series, and I will work on that instead. > [As a side note, index might be more l10n-friendly than stage because of > its latin origin (so it's there in more languages already).] We don't need to go into the hypotheticals of "might" because this has already been discussed, and translators already agreed that "staging area" is better. Additionally Ævar Arnfjörð Bjarmason explained [2] that it makes no sense to look for a term in English that is easier to translate, but instead the better term in English should be picked, and then that meaning is what gets translated. All this is mentioned in my blog post. > I have been away from the project quite a bit (merely for lack of time), > but some people will remember me as striving for "consistency" in the UI > (e.g., favouring "git diff [HEAD] INDEX" over "git diff --cached [HEAD]"). > > Independent of my remarks about the restart of the discussion, I had a > quick glance at this series. The questions which arose already around > "stage/staged" seem to indicate that the series is more about renaming, > some reorganising but not so much about a fresh look at a consistent > user experience. I did have a "fresh look" at a consistent user experience, and I did send those patches in 2014 [3]. However, those patches had no hope of going anywhere until Junio agrees to start using the term "staging area" officially. So that's what this patch series attempts to do (although I'm not hopeful in the least). > In other words (and to show a way forward), a cover letter with the > potential to bring many on board could start with: Once again everyone is already on board. > ## > > It has been 13 years that we discussed about "the index", "the cache", > "staging" and the "staging area". There seemed to be overall consensus > that the concept of "put something on stage that is to be committed [to]" > serves well in training and documentation when we explain git's index > and related commands which change the index (git add) and compare to it > (git diff --cached). It didn't "seem" there was overall consensus, there *was* close to 100% consensus. > Let's try and find a common ground for implementing this in user facing > commands. Here are a few possible appoaches: > - command/option aliases > - command/option renaming > - revamping of the command structure (as we did "checkout->switch") > - revamping the rev UI (from "--cached" to "INDEX" or "STAGE") > - you name it Most of these are not practical. For example why start renaming if we can start with aliases, and then later on deprecate the old ones, and finally obsolete them? And again, these have already been discussed before and what people seemed to gravitate towards are: * Officially use "staging area" instead of "the index" in the documentation * Add --stage aliases instead of --cache and --index * Make `git stage` more prominent Anything else would require more discussion, and that's not my goal here (not yet). > To kick start this, here are a few more thoughts on some of these/an > example implemenation for one of these/... > > ## I'm all in favor of changing the cover letter and even pick another point on the list to officially start moving to the term "staging area", but I think you are missing the main point: Consensus has *already* been reached. In fact, in all my years working on git I have never seen a UI change proposal with more consensus. Cheers. [1] https://lore.kernel.org/git/4D594911.40409@drmicha.warpmail.net/ [2] https://lore.kernel.org/git/CACBZZX7LOKqKNe09636N0xJ_VvmKP58BMDtjoKn1t5e9hJ0OiQ@mail.gmail.com/ [3] https://lore.kernel.org/git/1398449567-16314-1-git-send-email-felipe.contreras@gmail.com/