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

From: J. Bruce Fields <bfields@fieldses.org>
Date: Dec 6, 2006, 17:19 UTC
Message-ID: <20061206171950.GD1714@fieldses.org>
In-Reply-To: <Pine.LNX.4.63.0612061613460.28348@wbgn013.biozentrum.uni-wuerzburg.de>

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

Show 11 quoted lines

> 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.

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