[prev in list] [next in list] [prev in thread] [next in thread] 

List:       git
Subject:    Re: Announcing 3 git docs: Best Practices, fixing mistakes, post-production editing
From:       Junio C Hamano <gitster () pobox ! com>
Date:       2012-02-29 1:00:53
Message-ID: 7v399uxxkq.fsf () alter ! siamese ! dyndns ! org
[Download RAW message or body]

Just a few I noticed that are dubious to be in a document that is meant to
describe "best practices".

"Do commit early and often"
---------------------------

* "Personally ... history of this repository!".  That looks somewhat out
  of place when you are trying to document "best practices".


"Don't panic"
-------------

* As we never "auto-stash", anything that is on stash is by definition
  what the user deliberately placed, just like a commit on a branch that
  the user may have forgotten.  So it is strange to count it as one of the
  three places that "lost" commit may be hiding.  If you make it four and
  add "a branch you might have forgotten" to the mix, it would make a bit
  more sense, though.

* The example command line for gitk passes --all and also everything from
  "log -g" output, which should be OK for toy history, but wouldn't be
  such a good idea when you can expect tons of data from "log -g".

  Doesn't "gitk" itself accept -g these days?

* Lost and found

  Why "git ls-tree -r"?  Doesn't "git show" work eqully well?

  Also, the name of the hash we happen to use to produce the "object name"
  is "SHA-1", so either of these two are fine, but do not say "SHA"
  (throughout the document).


"On Sausage Making"
-------------------

* The desription of "downside" shows a bias against efforts to strive for
  useful history, and also shows ignorance of the true motivation behind
  such discipline. It is _not_ blame or ego. It is all about leaving a
  history others can later use to understand _why_ the code became the way
  it is now, to make it less likely for others to break it.

  If I were writing this, I would either remove that one paragraph
  altogether, or tone it down dramatically.  There is a short-term
  downside that you would be spending time on perfecting the history
  instead of advancing the tip of the branch, especially when you know the
  tree at the tip of the perfected history will be identical to the tip of
  the messy history you currently have.  If you plan to leave the project
  in a month or so and will never look back, that is totally wasted effort
  as maintaining the result will be other people's problem.  But if you
  are planning to be involved in the project for a longer haul, the time
  and effort is worth spending to make less-than-useful history into
  useful one.


"Do keep up to date"
--------------------

* You explained in "Do choose a workflow" section that different workflows
  suite different projects.  It would read better to rephrase this
  paragraph in which you are admitting that not everybody agrees with your
  "pull --rebase".  Instead of saying "but they should agree with me", it
  would be more useful to say in what workflow and the workflow elements
  such as "pull --rebase" you advocate in this section are suited (you do
  not have to say in what other workflow they are inappropriate).

I stopped reading at this point, but will look at the rest some other day.
Thanks for a fun reading.




--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
[prev in list] [next in list] [prev in thread] [next in thread]