[PATCH] cvs-migration document: make the need for "push" more obvious

It really is an important concept to grasp for people coming
from CVS. Even if it is briefly mentioned, it is not obvious
enough to sink in.

Signed-off-by: Johannes Schindelin <redacted>
---

	On Wed, 6 Dec 2006, Werner LEMBERG wrote:
	
	> It took me a while to realize that a git repository, as soon as 
	> you've cloned it, is *self-contained*, and that commiting to the 
	> repository and synchronizing with a different git repository are 
	> two completely different things (contrary to CVS).  This should 
	> be pronounced more in the CVS->git guide.

 Documentation/cvs-migration.txt |    5 +++++
 1 files changed, 5 insertions(+), 0 deletions(-)

diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt
index 6812683..8e610c7 100644
--- a/Documentation/cvs-migration.txt
+++ b/Documentation/cvs-migration.txt

@@ -24,6 +24,11 @@ First, note some ways that git differs from CVS:
     single shared repository which people can synchronize with; see below
     for details.
 
+  * Since every working tree contains a repository, a commit will not
+    publish your changes; it will only create a revision. You have to
+    "push" your changes to a public repository to make them visible
+    to others.
+
 Importing a CVS archive
 -----------------------
 

-- 

On Wed, Dec 06, 2006 at 01:32:32PM +0100, Jakub Narebski wrote:

Johannes Schindelin wrote:

quoted

+  * Since every working tree contains a repository, a commit will not
+    publish your changes; it will only create a revision. You have to
+    "push" your changes to a public repository to make them visible
+    to others.
+

I'm not sure about context of this addition, but it is simply not
true if you publish your working repository. Granted, usually one
sets up bare public publishing repository...

That's true, but this document is focused on the cvs-like case of
multiple private repos pushing to a single common public repo.

But we could replace "a commit will not publish" by "a commit in your
private repository will not publish"--which would make the statement
true without distracting from the main point.

On Wed, Dec 06, 2006 at 03:52:26PM +0100, Han-Wen Nienhuys wrote:

Johannes Schindelin escreveu:

quoted

It really is an important concept to grasp for people coming
from CVS. Even if it is briefly mentioned, it is not obvious
enough to sink in.

I think the goal is laudable, but IMO it would be better to shorten
the document rather adding more text.

OK, but...

 Documentation/cvs-migration.txt |   34 +++++++++++++++++++++++-----------
 1 files changed, 23 insertions(+), 11 deletions(-)

... that lengthens it even more than the proposed addition.

+    Hence, there is a difference between creating a revision
+    (the "commit" command) and submitting it (the "push" command).

I'd rather leave that introduction as it is--just as a section that
advertises the git features without trying to explain much.  And I'd
rather not mention push until we have a chance to explain how to use it.

Johannes Schindelin wrote:

+  * Since every working tree contains a repository, a commit will not
+    publish your changes; it will only create a revision. You have to
+    "push" your changes to a public repository to make them visible
+    to others.
+

I'm not sure about context of this addition, but it is simply not
true if you publish your working repository. Granted, usually one
sets up bare public publishing repository...

By publish I mean set up http(s):// or git://, or ssh+git://, or local
transport.
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Hi,

On Wed, 6 Dec 2006, J. Bruce Fields wrote:

I'd rather leave that introduction as it is--just as a section that 
advertises the git features without trying to explain much.  And I'd 
rather not mention push until we have a chance to explain how to use it.

You talk like you'd have an eternity to explain Git. But that is not true. 
A developer, especially those whom Git is forced upon, have an attention 
span shorter than their pub1c hair.

I _know_ that _I_ did not read the whole document about "Branching and 
merging in Git".

Ciao,
Dscho

On Wed, Dec 06, 2006 at 12:19:50PM -0500, J. Bruce Fields wrote:

On Wed, Dec 06, 2006 at 04:16:57PM +0100, Johannes Schindelin wrote:
Definitely, I agree.  So that argues for locating the most import stuff
as close to start of the document as possible.  But obviously there's
lot of important stuff and you can't do that with everything, so you
also have to rely on keeping things organized so people can more easily
skip to the middle.

Hm, but, come to think of it, I agree with you that the "how to commit
and push" really should come earlier, since that's the stuff most people
need to know; currently the order is roughly:

	importing a cvs archive
	creating a shared repository
	committing to a shared repository

We should start out with the assumption that a shared repo is already
set up and make it:

	committing to a shared repository
	creating a shared repository
	importing a cvs archive

which puts it in stuff-most-people-need-to-know to
stuff-less-people-need-to-know order.  Maybe the current introduction
should even be postponed to later.

And some day we should move that whole final CVS annotate section
elsewhere.

Hi,

On Wed, 6 Dec 2006, Jakub Narebski wrote:

Johannes Schindelin wrote:

quoted

Give them a chance to get used to the concepts of Git.

Well, it would be best to teach them concepts of git along.

NOOOOO!

It might surprise you that most users are not at all interested in how Git 
works. They just want to use the thing. And we should not try to make life 
hard on them. Teach them what they have to know _as quickly as possible_ 
so that they can continue to work. They'll come back for more.

If you make it as complicated as Malbolge to them, you will never know you 
lost a happy camper, because they _will not tell you_!

Ciao,
Dscho

Johannes Schindelin escreveu:

It really is an important concept to grasp for people coming
from CVS. Even if it is briefly mentioned, it is not obvious
enough to sink in.

I think the goal is laudable, but IMO it would be better to shorten
the document rather adding more text.

here is my try
 
From 980a0ca1b274e1219c24c3138f95e42206c72875 Mon Sep 17 00:00:00 2001
From: Han-Wen Nienhuys <redacted>
Date: Wed, 6 Dec 2006 15:50:13 +0100
Subject: [PATCH] another try at  rephrasing cvs doc.


Signed-off-by: Han-Wen Nienhuys <redacted>
---
 Documentation/cvs-migration.txt |   34 +++++++++++++++++++++++-----------
 1 files changed, 23 insertions(+), 11 deletions(-)

diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt
index 6812683..3270c57 100644
--- a/Documentation/cvs-migration.txt
+++ b/Documentation/cvs-migration.txt

@@ -6,24 +6,36 @@ this document is to put you on the road to recovery, by helping you
 convert an existing cvs repository to git, and by showing you how to use a
 git repository in a cvs-like fashion.
 
-Some basic familiarity with git is required.  This
-link:tutorial.html[tutorial introduction to git] should be sufficient.
-
-First, note some ways that git differs from CVS:
+Git differs from CVS:
 
   * Commits are atomic and project-wide, not per-file as in CVS.
 
-  * Offline work is supported: you can make multiple commits locally,
+  * Branching is fast and easy.
+
+  * GIT is a distributed version control system:
+    This has several consequences:
+
+    - Every working tree contains a repository with a full copy of the
+    project history.
+    
+    - Offline work is supported: you can create revisions locally,
     then submit them when you're ready.
 
-  * Branching is fast and easy.
+    Hence, there is a difference between creating a revision
+    (the "commit" command) and submitting it (the "push" command).
+
+    - No repository is inherently more important than
+    any other.
+    
+    Of course, a project may still designate one central repository as
+    the True Master that contributors synchronize with.
+
+    See below for details.
 
-  * Every working tree contains a repository with a full copy of the
-    project history, and no repository is inherently more important than
-    any other.  However, you can emulate the CVS model by designating a
-    single shared repository which people can synchronize with; see below
-    for details.
+Some basic familiarity with git is required.  This
+link:tutorial.html[tutorial introduction to git] should be sufficient.
 
+    
 Importing a CVS archive
 -----------------------
 

-- 
1.4.4.1.gc9922-dirty


-- 

J. Bruce Fields escreveu:

On Wed, Dec 06, 2006 at 03:52:26PM +0100, Han-Wen Nienhuys wrote:

quoted

Johannes Schindelin escreveu:

quoted

It really is an important concept to grasp for people coming
from CVS. Even if it is briefly mentioned, it is not obvious
enough to sink in.

I think the goal is laudable, but IMO it would be better to shorten
the document rather adding more text.

OK, but...

quoted

 Documentation/cvs-migration.txt |   34 +++++++++++++++++++++++-----------
 1 files changed, 23 insertions(+), 11 deletions(-)

... that lengthens it even more than the proposed addition.

Yes, but with white space.

I'd rather leave that introduction as it is--just as a section that
advertises the git features without trying to explain much.  And I'd
rather not mention push until we have a chance to explain how to use it.

As was mentioned in another thread, it make more sense to split this file up 
into separate documents for project contributors and project admins.

-- 

On Wed, Dec 06, 2006 at 04:16:57PM +0100, Johannes Schindelin wrote:

Hi,

On Wed, 6 Dec 2006, J. Bruce Fields wrote:

quoted

I'd rather leave that introduction as it is--just as a section that 
advertises the git features without trying to explain much.  And I'd 
rather not mention push until we have a chance to explain how to use it.

You talk like you'd have an eternity to explain Git. But that is not true.
A developer, especially those whom Git is forced upon, have an attention 
span shorter than their pub1c hair.

Definitely, I agree.  So that argues for locating the most import stuff
as close to start of the document as possible.  But obviously there's
lot of important stuff and you can't do that with everything, so you
also have to rely on keeping things organized so people can more easily
skip to the middle.

The rest of the introduction is all git marketing: why you should like
using git instead of cvs.  So someone skimming for the quickest possible
"how do I make changes?" stuff may skip it entirely.

The thing that might help such a skimmer the most, actually, would be
a more helpful title for the section that actually does have what
they're looking for.  And making sure that particular section has the
right stuff.  How about something like this?

--b.

cvs-migration: improved section titles, better push/commit explanation

Rename the section titles to make the "how-to" content of the section
obvious.  Also clarify that changes have to be commited before they can
be pushed.

---

 cvs-migration.txt |   19 ++++++++++++-------
 1 file changed, 12 insertions(+), 7 deletions(-)

diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt
index 6812683..726b48d 100644
--- a/Documentation/cvs-migration.txt
+++ b/Documentation/cvs-migration.txt

@@ -76,8 +76,8 @@ variants of this model.
 With a small group, developers may just pull changes from each other's
 repositories without the need for a central maintainer.
 
-Emulating the CVS Development Model
------------------------------------
+Creating a Shared Repository
+----------------------------
 
 Start with an ordinary git working directory containing the project, and
 remove the checked-out files, keeping just the bare .git directory:

@@ -105,7 +105,10 @@ $ GIT_DIR=repo.git git repo-config core.
 Make sure committers have a umask of at most 027, so that the directories
 they create are writable and searchable by other group members.
 
-Suppose this repository is now set up in /pub/repo.git on the host
+Performing Development on a Shared Repository
+---------------------------------------------
+
+Suppose a repository is now set up in /pub/repo.git on the host
 foo.com.  Then as an individual committer you can clone the shared
 repository:
 

@@ -134,15 +137,17 @@ Pull: master:origin
 ------------
 ================================
 
-You can update the shared repository with your changes using:
+You can update the shared repository with your changes by first commiting
+your changes, and then using:
 
 ------------------------------------------------
 $ git push origin master
 ------------------------------------------------
 
-If someone else has updated the repository more recently, `git push`, like
-`cvs commit`, will complain, in which case you must pull any changes
-before attempting the push again.
+to "push" those commits to the shared repository.  If someone else has
+updated the repository more recently, `git push`, like `cvs commit`, will
+complain, in which case you must pull any changes before attempting the
+push again.
 
 In the `git push` command above we specify the name of the remote branch

Hi,

On Wed, 6 Dec 2006, Jakub Narebski wrote:

Johannes Schindelin wrote:

quoted

+  * Since every working tree contains a repository, a commit will not
+    publish your changes; it will only create a revision. You have to
+    "push" your changes to a public repository to make them visible
+    to others.
+

I'm not sure about context of this addition, but it is simply not
true if you publish your working repository.

Remember, you are talking to CVS users. They are not dumb, but sooo used 
to the CVS ways. So, they do not publish their working directory.

Later, when they became familiar with Git, you can tell them: "BTW you can 
also publish your working directory, but then you have to be extra careful 
with git-commit --amend, and if you allow pushing into your repo you have 
to add hooks to prevent updating your current HEAD, etc."

Give them a chance to get used to the concepts of Git.

Ciao,
Dscho

J. Bruce Fields wrote:

We should start out with the assumption that a shared repo is already
set up and make it:

	committing to a shared repository
	creating a shared repository
	importing a cvs archive

which puts it in stuff-most-people-need-to-know to
stuff-less-people-need-to-know order.  Maybe the current introduction
should even be postponed to later.

Yes, definitely!

I'm not complaining about changing to git, but Dscho's comment really 
rings true:

 > A developer, especially those whom Git is forced upon, have an
 > attention span shorter than their pub1c hair.

I'm in the middle of exam period, I have a term papers to write, and I 
have two weeks of lilypond bug reports and doc typos to process.  I 
don't care if git can do branches really nicely or walk my dog or cure 
cancer.  I can look at that stuff later -- right now I just want to fix 
things and upload them.

Cheers,

On Wed, Dec 06, 2006 at 01:02:58PM -0800, Graham Percival wrote:

I'm in the middle of exam period, I have a term papers to write, and I 
have two weeks of lilypond bug reports and doc typos to process.  I 
don't care if git can do branches really nicely or walk my dog or cure 
cancer.  I can look at that stuff later -- right now I just want to fix 
things and upload them.

Yeah.  It's a tricky problem; different people need different things,
and to cover everything (and explain it correctly) the documentation
needs to be long; but to ensure that impatient people can get to what
they need quickly, there needs to be a short, clear path to their
particular need.

A few down-to-earth approaches that could help:

	- Clearer section/chapter titles, so we can generate tables of
	  contents where people can quickly find stuff--so, titles that
	  explain what the section will show you how to do with
	  minimized use of jargon that the user doesn't know yet ("how
	  to keep a repository up-to-date" as opposed to "git-fetch and
	  remotes").

	- As in "Everyday Git", think about what different groups of
	  users need.  But where possible, try to order documentation
	  with the stuff needed by the largest group of people first.
	  (For example, right now all the tutorials start with "git
	  init-db" and "git commit", assuming people are starting a
	  project from scratch, when the more typical usage is probably
	  someone joining an existing project, and possibly doing only
	  read-only stuff at first.)

	- Clearer ordering and dependencies, so when people find the "how
	  to resolve merges" section, they can quickly see what else
	  they'd need to read before that.  (And, yeah, I realize 99% of
	  the time they won't actually do that--they'll just dive right
	  in and try a few examples.  But at least they'll know where to
	  turn if that gets them in trouble....)

Hi!

Johannes Schindelin wrote:

On Wed, 6 Dec 2006, Jakub Narebski wrote:

quoted

Johannes Schindelin wrote:

quoted

+  * Since every working tree contains a repository, a commit will not
+    publish your changes; it will only create a revision. You have to
+    "push" your changes to a public repository to make them visible
+    to others.
+

I'd perhaps add here that it doesn't "push" your changes to a repository
you cloned from / you fetch from.
 

quoted

I'm not sure about context of this addition, but it is simply not
true if you publish your working repository.

Remember, you are talking to CVS users. They are not dumb, but sooo used 
to the CVS ways. So, they do not publish their working directory.

So we are talking in context of having CVS-like one central repository
from which they pull / fetch, and to which they push?
 

Later, when they became familiar with Git, you can tell them: "BTW you can 
also publish your working directory, but then you have to be extra careful 
with git-commit --amend, and if you allow pushing into your repo you have 
to add hooks to prevent updating your current HEAD, etc."

I'd rather say that "publish your working repository", not "working
directory" here.

Give them a chance to get used to the concepts of Git.

Well, it would be best to teach them concepts of git along.

-- 
Jakub Narebski