[v3,0/4] Documentation for common user misconceptions
mbox series

Message ID 20191102192615.10013-1-sandals@crustytoothpaste.net
Headers show
Series
  • Documentation for common user misconceptions
Related show

Message

brian m. carlson Nov. 2, 2019, 7:26 p.m. UTC
This series includes four patches that update the documentation to
address common user misconceptions.

Changes from v2:
* Move author and committer information to git-commit(1) where people
  will look for it.
* Move guidance on user.name format to git-commit(1) as well and mention
  a shortened form of the advice in the `user.name` description.
* Use a parenthetical to describe a "personal name" without contrasting
  it with a username.
* Offer a potential solution for people who want to ignore tracked
  files by recommending a templating mechanism.
* Be slightly more verbose about why memory is wasted with
  http.postBuffer.

Changes from v1:
* Remove parenthetical which was confusing.
* Add two more patches.

brian m. carlson (4):
  doc: move author and committer information to git-commit(1)
  doc: provide guidance on user.name format
  doc: dissuade users from trying to ignore tracked files
  docs: mention when increasing http.postBuffer is valuable

 Documentation/config/http.txt      |  8 ++++++
 Documentation/config/user.txt      |  7 +++++-
 Documentation/git-commit-tree.txt  | 39 ++++-------------------------
 Documentation/git-commit.txt       | 40 +++++++++++++++++++++++++++---
 Documentation/git-update-index.txt | 16 ++++++++++++
 5 files changed, 72 insertions(+), 38 deletions(-)

Range-diff against v2:
1:  603a9f8f9a < -:  ---------- doc: provide guidance on user.name format
-:  ---------- > 1:  b39b365f54 doc: move author and committer information to git-commit(1)
-:  ---------- > 2:  b7d805427c doc: provide guidance on user.name format
2:  0da41623a5 ! 3:  7644af0b07 doc: dissuade users from trying to ignore tracked files
    @@ Commit message
         pitfalls in the documentation for git update-index so that users know
         they should explore alternate solutions.
     
    +    In additon, let's provide a recommended solution to dealing with the
    +    common case of configuration files, since there are well-known
    +    approaches used successfully in many environments.
    +
         Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
     
      ## Documentation/git-update-index.txt ##
    @@ Documentation/git-update-index.txt: The untracked cache extension can be enabled
     +the index when performing certain operations.  In general, Git does not
     +provide a way to ignore changes to tracked files, so alternate solutions
     +are recommended.
    ++
    ++If the file you want to change is some sort of configuration file (say,
    ++for a build tool, IDE, or editor), a common solution is to use a
    ++templating mechanism, such as Ruby's ERB, to generate the ignored
    ++configuration file from a template stored in the repository and a source
    ++of data using a script or build step.
     +
      SEE ALSO
      --------
3:  89fe11b951 ! 4:  d096763e7a docs: mention when increasing http.postBuffer is valuable
    @@ Documentation/config/http.txt: http.postBuffer::
     +server or a proxy only supports HTTP/1.0 or is noncompliant with the
     +HTTP standard.  Raising this is not, in general, an effective solution
     +for most push problems, but can increase memory consumption
    -+significantly.
    ++significantly since the entire buffer is allocated for even small
    ++pushes.
      
      http.lowSpeedLimit, http.lowSpeedTime::
      	If the HTTP transfer speed is less than 'http.lowSpeedLimit'

Comments

Jeff King Nov. 4, 2019, 10:26 p.m. UTC | #1
On Sat, Nov 02, 2019 at 07:26:11PM +0000, brian m. carlson wrote:

> This series includes four patches that update the documentation to
> address common user misconceptions.
> 
> Changes from v2:
> * Move author and committer information to git-commit(1) where people
>   will look for it.
> * Move guidance on user.name format to git-commit(1) as well and mention
>   a shortened form of the advice in the `user.name` description.
> * Use a parenthetical to describe a "personal name" without contrasting
>   it with a username.
> * Offer a potential solution for people who want to ignore tracked
>   files by recommending a templating mechanism.
> * Be slightly more verbose about why memory is wasted with
>   http.postBuffer.

Thanks. I think this is an improvement over v1, but I'm still a little
iffy on some of the other movement in the first patch.

TBH, I don't think it's making anything _worse_, but I think it
highlights how some of our documentation is a mish-mash of low-level and
high-level details. ;) So it might be a good opportunity to at least
clean up the documentation around ident environment variables.

-Peff
Junio C Hamano Nov. 6, 2019, 1:58 a.m. UTC | #2
Jeff King <peff@peff.net> writes:

> Thanks. I think this is an improvement over v1, but I'm still a little
> iffy on some of the other movement in the first patch.
>
> TBH, I don't think it's making anything _worse_, but I think it
> highlights how some of our documentation is a mish-mash of low-level and
> high-level details. ;) So it might be a good opportunity to at least
> clean up the documentation around ident environment variables.

Yeah, I hate to suggest another round, but agree with your comments
on 1/4 wrt the way how and the place where the environment variables
are explained, which invalidates the changes in 2/4.  Fortunately
3/4 and 4/4 are unaffected ;-)

Thanks.
brian m. carlson Nov. 6, 2019, 2:19 a.m. UTC | #3
On 2019-11-06 at 01:58:33, Junio C Hamano wrote:
> Jeff King <peff@peff.net> writes:
> 
> > Thanks. I think this is an improvement over v1, but I'm still a little
> > iffy on some of the other movement in the first patch.
> >
> > TBH, I don't think it's making anything _worse_, but I think it
> > highlights how some of our documentation is a mish-mash of low-level and
> > high-level details. ;) So it might be a good opportunity to at least
> > clean up the documentation around ident environment variables.
> 
> Yeah, I hate to suggest another round, but agree with your comments
> on 1/4 wrt the way how and the place where the environment variables
> are explained, which invalidates the changes in 2/4.  Fortunately
> 3/4 and 4/4 are unaffected ;-)

Yeah, I agree another round is warranted, and it's not the end of the
world: it'll get into 2.25 either way.  I'll try to get a reroll out in
the next few days.
Junio C Hamano Nov. 6, 2019, 3:15 a.m. UTC | #4
"brian m. carlson" <sandals@crustytoothpaste.net> writes:

> On 2019-11-06 at 01:58:33, Junio C Hamano wrote:
>> Jeff King <peff@peff.net> writes:
>> 
>> > Thanks. I think this is an improvement over v1, but I'm still a little
>> > iffy on some of the other movement in the first patch.
>> >
>> > TBH, I don't think it's making anything _worse_, but I think it
>> > highlights how some of our documentation is a mish-mash of low-level and
>> > high-level details. ;) So it might be a good opportunity to at least
>> > clean up the documentation around ident environment variables.
>> 
>> Yeah, I hate to suggest another round, but agree with your comments
>> on 1/4 wrt the way how and the place where the environment variables
>> are explained, which invalidates the changes in 2/4.  Fortunately
>> 3/4 and 4/4 are unaffected ;-)
>
> Yeah, I agree another round is warranted, and it's not the end of the
> world: it'll get into 2.25 either way.  I'll try to get a reroll out in
> the next few days.

Thanks.  I also agree with what Peff and you said on 3/4 wrt the
addition of "ship template, tweak it into an untracked config that
gets used".
Emily Shaffer Jan. 16, 2020, 9:08 p.m. UTC | #5
On Sat, Nov 02, 2019 at 07:26:11PM +0000, brian m. carlson wrote:
> This series includes four patches that update the documentation to
> address common user misconceptions.

Hm, is this still waiting for a reroll? Someone just ran into the
user.name/username confusion in #git-devel today:
https://colabti.org/irclogger/irclogger_log/git-devel?date=2020-01-16#l79

 - Emily
brian m. carlson Jan. 16, 2020, 11:35 p.m. UTC | #6
On 2020-01-16 at 21:08:57, Emily Shaffer wrote:
> On Sat, Nov 02, 2019 at 07:26:11PM +0000, brian m. carlson wrote:
> > This series includes four patches that update the documentation to
> > address common user misconceptions.
> 
> Hm, is this still waiting for a reroll? Someone just ran into the
> user.name/username confusion in #git-devel today:
> https://colabti.org/irclogger/irclogger_log/git-devel?date=2020-01-16#l79

Yeah, it is.  I have one, but haven't sent it out.  I'll plan to do so
this weekend.