[Patch] Documentation: enhanced "git for CVS users" doc about shared repositories

[Patch] Documentation: enhanced "git for CVS users" doc about shared repositories

[Francesco Pretto]

More detailed instructions on how to set up shared repositories.
Added a reference to "git for CVS users" doc in git-init manual.

Signed-off-by: Francesco Pretto <ceztkoml@gmail.com>
---
 Documentation/cvs-migration.txt |   72 ++++++++++++++++++++++++++++++--------
 Documentation/git-init.txt      |    7 ++++
 2 files changed, 64 insertions(+), 15 deletions(-)

diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt
index 3b6b494..c92ed49 100644
--- a/Documentation/cvs-migration.txt
+++ b/Documentation/cvs-migration.txt
@@ -13,12 +13,12 @@ link:tutorial.html[tutorial introduction to git] should be sufficient.
 Developing against a shared repository
 --------------------------------------
 
-Suppose a shared repository is set up in /pub/repo.git on the host
+Suppose a shared repository is set up in /pub/scm/repo.git on the host
 foo.com.  Then as an individual committer you can clone the shared
 repository over ssh with:
 
 ------------------------------------------------
-$ git clone foo.com:/pub/repo.git/ my-project
+$ git clone foo.com:/pub/scm/repo.git/ my-project
 $ cd my-project
 ------------------------------------------------
 
@@ -68,37 +68,79 @@ other than `master`.
 Setting Up a Shared Repository
 ------------------------------
 
-We assume you have already created a git repository for your project,
-possibly created from scratch or from a tarball (see the
-link:tutorial.html[tutorial]), or imported from an already existing CVS
-repository (see the next section).
+We assume you have admin privilege on the remote machine. Moreover, we assume
+you have already created a git repository for your project, possibly created
+from scratch or from a tarball (see the link:tutorial.html[tutorial]),or
+imported  from an already existing CVS repository (see the next section).
 
-Assume your existing repo is at /home/alice/myproject.  Create a new "bare"
-repository (a repository without a working tree) and fetch your project into
-it:
+First, let's create a common directory for all the projects you'll want to
+track with git:
+
+-----------------------------------------------
+$ mkdir -p /pub/scm
+-----------------------------------------------
+
+It's recommended, but not necessary, to create a specific group of commiters
+for every project/repository. With root credentials launch:
+
+------------------------------------------------
+$ groupadd $group
+------------------------------------------------
+
+Assume your existing repository is at /home/alice/myproject.  Create a new
+"bare" repository (a repository without a working tree) and fetch your project
+into it:
 
 ------------------------------------------------
-$ mkdir /pub/my-repo.git
+$ mkdir /pub/scm/my-repo.git
 $ cd /pub/my-repo.git
 $ git --bare init --shared
 $ git --bare fetch /home/alice/myproject master:master
 ------------------------------------------------
 
+Now, set the group ownership of the git repository you've just created to the
+same group of the commiters:
+
+------------------------------------------------
+$ chgrp -R $group /pub/scm/my-repo.git
+------------------------------------------------
+
 Next, give every team member read/write access to this repository.  One
 easy way to do this is to give all the team members ssh access to the
 machine where the repository is hosted.  If you don't want to give them a
 full shell on the machine, there is a restricted shell which only allows
 users to do git pushes and pulls; see gitlink:git-shell[1].
 
-Put all the committers in the same group, and make the repository
-writable by that group:
+First, enable it putting on the trusted shells list of the system:
+
+------------------------------------------------
+$ echo `which git-shell` >> /etc/shells
+------------------------------------------------
+
+Ensure users will not have write permission on /pub/scm. Now, let's create
+them with the following command launched with root credentials:
 
 ------------------------------------------------
-$ chgrp -R $group /pub/my-repo.git
+$ useradd -g $group -d /pub/scm -s `which git-shell` $username
 ------------------------------------------------
 
-Make sure committers have a umask of at most 027, so that the directories
-they create are writable and searchable by other group members.
+They will be enabled to push on repositories owned by the group $group.
+Later, you can give users access to other projects simply by adding them to
+other groups.
+
+[NOTE]
+================================
+With previous versions of git, it could be necessary to set umask variable of
+all commiters with values like 002 or 007. If you still need to support them,
+you can do it in the following way; assuming that all users have their home
+positionated at /pub/scm, like in the previous example, launch the command:
+
+------------------------------------------------
+$ echo "umask 022" >> /pub/scm/.profile
+------------------------------------------------
+
+At the next login, users will have their umask variable automatically set.
+================================
 
 Importing a CVS archive
 -----------------------
diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index 07484a4..f5f363d 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -101,6 +101,13 @@ $ git-add .     <2>
 <2> add all existing file to the index
 
 
+SHARED REPOSITORIES
+-------------------
+
+Please refer to link:cvs-migration.html[git for CVS users], section "Setting Up
+a Shared Repository", for details on how to set up shared repositories.
+
+
 Author
 ------
 Written by Linus Torvalds <torvalds@osdl.org>

Re: [Patch] Documentation: enhanced "git for CVS users" doc about shared repositories

[Junio C Hamano]

Francesco Pretto <ceztkoml@gmail.com> writes:

> More detailed instructions on how to set up shared repositories.
> Added a reference to "git for CVS users" doc in git-init manual.
>
> Signed-off-by: Francesco Pretto <ceztkoml@gmail.com>
> ---
>  Documentation/cvs-migration.txt |   72 ++++++++++++++++++++++++++++++--------
>  Documentation/git-init.txt      |    7 ++++
>  2 files changed, 64 insertions(+), 15 deletions(-)
>
> diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt
> index 3b6b494..c92ed49 100644
> --- a/Documentation/cvs-migration.txt
> +++ b/Documentation/cvs-migration.txt
> @@ -13,12 +13,12 @@ link:tutorial.html[tutorial introduction to git] should be sufficient.
>  Developing against a shared repository
>  --------------------------------------
>  
> -Suppose a shared repository is set up in /pub/repo.git on the host
> +Suppose a shared repository is set up in /pub/scm/repo.git on the host
>  foo.com.  Then as an individual committer you can clone the shared
>  repository over ssh with:
>  
>  ------------------------------------------------
> -$ git clone foo.com:/pub/repo.git/ my-project
> +$ git clone foo.com:/pub/scm/repo.git/ my-project
>  $ cd my-project
>  ------------------------------------------------

This part seems an unnecessary change.

> @@ -68,37 +68,79 @@ other than `master`.
>  Setting Up a Shared Repository
>  ------------------------------
>  
> -We assume you have already created a git repository for your project,
> -possibly created from scratch or from a tarball (see the
> -link:tutorial.html[tutorial]), or imported from an already existing CVS
> -repository (see the next section).
> +We assume you have admin privilege on the remote machine. Moreover, we assume
> +you have already created a git repository for your project, possibly created
> +from scratch or from a tarball (see the link:tutorial.html[tutorial]),or
> +imported  from an already existing CVS repository (see the next section).

Don't assume the "admin privilege" part, as you do not have to.

You are newly hired to work on project-X, and the sysadm throws
you into projectx group.  Thesysadm further prepares a directory
'/pub/project-X' and makes it mode 2775 (aka ug=rwx,o=rx,g+s).

Do you want to create a new repository for projext-X group's
use?  You do:

	$ cd /pub/project-X
        $ GIT_DIR=mine.git git init --shared

and you now have a usable /pub/project-X/mine.git repository for
project members.  I do not think you would need any chmod/chgrp
after this step.

> +First, let's create a common directory for all the projects you'll want to
> +track with git:
> +
> +-----------------------------------------------
> +$ mkdir -p /pub/scm
> +-----------------------------------------------

An organization may use different SCM depending on the projects'
needs, and there is no reason members of projects A and B should
be in the same group 'git' while having members of project C in
group 'hg' only because A and B happen to use git.  It would
make more sense to either (1) make members of all three projects
belong to 'src' group, or (2) make three groups, one for each
project.

IOW, I do not think the above is a good suggestion.

Also with the "create new --shared repository for the project in
a group's directory that has mode 2755" approach, I do not think
there is any need to muck with umask either.

Re: [Patch] Documentation: enhanced "git for CVS users" doc about shared repositories

[Francesco Pretto]

Junio C Hamano ha scritto:
>>  ------------------------------------------------
>> -$ git clone foo.com:/pub/repo.git/ my-project
>> +$ git clone foo.com:/pub/scm/repo.git/ my-project
>>  $ cd my-project
>>  ------------------------------------------------
> 
> This part seems an unnecessary change.
> 

Ironically, that's the same configuration of git.kernel.org. And I think is better
to put immediately the project in a appropriate directory than to move it later.

> Don't assume the "admin privilege" part, as you do not have to.
> 

Admin privilege SHALL be assumed, as this is a first time configuration, and the best
we can do is to assume it's done on a default *nix installation. Moreover, it's
what HEAD documentation is already doing when it suggests to give users ssh access.

Let's suppose the user "user1" create its own repository on a remote machine.
Now, he wants to selectively give write access on its repository to "user2".
There's 2 cases:
    1) "user2" have a local/ssh account on the machine. In this case, "user1" want
       to be sure only "user2" can write to the repository, so he can ask the admin
       to put "user1" and "user2" in the same group "projectx" or ask him to enable
       ACLs, still turned off in the majority of *nix systems.
    2) "user2" haven't a local/ssh account. Here:
	- a local/ssh account should be given to "user2", returning to 1)
        - mod_dav module has to be enabled for public http dirs of "user1"
        - git daemon has to be started and enabled to write on the repository.

The last 3 tasks all require admin privilege on default linux/bsd/macosx
installations. However, a little distinction can be made. I'll see.

>
> needs, and there is no reason members of projects A and B should
> be in the same group 'git'

I agree!

> while having members of project C in
> group 'hg' only because A and B happen to use git.

I agree!

> belong to 'src' group, or (2) make three groups, one for each
> project.
> 

It's exactly the point of:

+It's recommended, but not necessary, to create a specific group of commiters
+for every project/repository. With root credentials launch:
+
+------------------------------------------------
+$ groupadd $group
+------------------------------------------------

What you have understood here?

> Also with the "create new --shared repository for the project in
> a group's directory that has mode 2755" approach, I do not think
> there is any need to muck with umask either.
> 

umask requirement is referred to previous version of git. It's still referred as actual
in HEAD documentation. If it's ok for you, we could just cut away that reference.

Conclusion: i can try to amend my patch to be even more clearer. What i am saying
is that official documentation, commands manuals/syntaxes should be easy enough to the
first time user to set up git repositories without looking up the web for
"git tutorial"/"git installation"/"git umask 002", etc. (and consider that even an
expert sysadmin is a first time user, when he install and set up git the first time).
Or was better a "Documentation S**KS!" bug report?

Re: [Patch] Documentation: enhanced "git for CVS users" doc about shared repositories

[Johannes Schindelin]

Hi,

On Tue, 6 Nov 2007, Francesco Pretto wrote:

> Junio C Hamano ha scritto:
> >>  ------------------------------------------------
> >> -$ git clone foo.com:/pub/repo.git/ my-project
> >> +$ git clone foo.com:/pub/scm/repo.git/ my-project
> >>  $ cd my-project
> >>  ------------------------------------------------
> > 
> > This part seems an unnecessary change.
> > 
> 
> Ironically, that's the same configuration of git.kernel.org. And I think 
> is better to put immediately the project in a appropriate directory than 
> to move it later.

For most people, neither path is correct.  So I really don't see your 
point.

Ciao,
Dscho

Re: [Patch] Documentation: enhanced "git for CVS users" doc about shared repositories

[Francesco Pretto]

Johannes Schindelin ha scritto:
> 
> For most people, neither path is correct.

Yeah, I agree. I'll try to reflect this with a neutral wording :-)
In the context of the documentation, we should just take care of logical
following the example.

Re: [PATCH] Documentation: enhanced "git for CVS users" doc about shared repositories

[Francesco Pretto]

Signed-off-by: Francesco Pretto <ceztkoml@gmail.com>
---
 More detailed instructions on how to set up shared repositories.
 Removed an old reference to the need of setting umask of ssh
 users of shared repositories.
 Added a reference to "git for CVS users" doc in git-init manual.

 Documentation/cvs-migration.txt |   61 +++++++++++++++++++++++++++++++++++----
 Documentation/git-init.txt      |    7 ++++
 2 files changed, 62 insertions(+), 6 deletions(-)

diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt
index 3b6b494..849b403 100644
--- a/Documentation/cvs-migration.txt
+++ b/Documentation/cvs-migration.txt
@@ -71,7 +71,40 @@ Setting Up a Shared Repository
 We assume you have already created a git repository for your project,
 possibly created from scratch or from a tarball (see the
 link:tutorial.html[tutorial]), or imported from an already existing CVS
-repository (see the next section).
+repository (see the next section). Moreover, we assume you can write in a
+public accessible directory and give other users the permission to do so.
+You could need or not admin privileges to do so, depending on your
+system configuration and how you decide to export the repository.
+
+It's recommended, but not strictly necessary, to create a specific group for
+every project/repository you'll want to create, so it will be easier to give
+or prevent access of users to specific repositories. With admin privilege launch:
+
+------------------------------------------------
+$ groupadd $group
+------------------------------------------------
+
+If you want to add an user to this group, launch:
+
+------------------------------------------------
+$ usermod -a -G $group $username
+------------------------------------------------
+
+In our example, we will store the shared repository in the /pub dir, so the
+user creating it will need write permission there. There's no problems if you
+choose another directory, but you'll have to ensure it will be accessible by
+other users, on local or by remote (this could be not the case of home
+directories).
+
+If you just want to create a directory that is writable by every users that have
+a local account, launch with privileged credentials:
+
+------------------------------------------------
+$ mkdir /pub
+$ chmod a+w,+t /pub
+------------------------------------------------
+
+Now you can proceed with an unprivileged user.
 
 Assume your existing repo is at /home/alice/myproject.  Create a new "bare"
 repository (a repository without a working tree) and fetch your project into
@@ -84,21 +117,37 @@ $ git --bare init --shared
 $ git --bare fetch /home/alice/myproject master:master
 ------------------------------------------------
 
+If you previously decided to create a specific group for the committers of the
+repository, assign its ownership to that group (you'll have to be a member of it
+or switch to privileged credentials):
+
+------------------------------------------------
+$ chgrp -R $group /pub/my-repo.git
+------------------------------------------------
+
 Next, give every team member read/write access to this repository.  One
 easy way to do this is to give all the team members ssh access to the
 machine where the repository is hosted.  If you don't want to give them a
 full shell on the machine, there is a restricted shell which only allows
 users to do git pushes and pulls; see gitlink:git-shell[1].
 
-Put all the committers in the same group, and make the repository
-writable by that group:
+The following two commands will require admin privileges; first, enable
+git-shell putting it on the trusted shells list of the system:
 
 ------------------------------------------------
-$ chgrp -R $group /pub/my-repo.git
+$ echo `which git-shell` >> /etc/shells
+------------------------------------------------
+
+Now, let's create the commit users:
+
+------------------------------------------------
+$ useradd -g $group -s `which git-shell` $username
 ------------------------------------------------
 
-Make sure committers have a umask of at most 027, so that the directories
-they create are writable and searchable by other group members.
+These users will be enabled to push on repositories owned by the group $group.
+Later, you can give access to other projects simply by adding them to
+other groups. Similarly, you can prevent access to repositories simply
+removing those users from related groups.
 
 Importing a CVS archive
 -----------------------
diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index 07484a4..f5f363d 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -101,6 +101,13 @@ $ git-add .     <2>
 <2> add all existing file to the index
 
 
+SHARED REPOSITORIES
+-------------------
+
+Please refer to link:cvs-migration.html[git for CVS users], section "Setting Up
+a Shared Repository", for details on how to set up shared repositories.
+
+
 Author
 ------
 Written by Linus Torvalds <torvalds@osdl.org>

Re: [PATCH] Documentation: enhanced "git for CVS users" doc about shared repositories

[Junio C Hamano]

Francesco Pretto <ceztkoml@gmail.com> writes:

> Signed-off-by: Francesco Pretto <ceztkoml@gmail.com>
> ---
>  More detailed instructions on how to set up shared repositories.
>  Removed an old reference to the need of setting umask of ssh
>  users of shared repositories.
>  Added a reference to "git for CVS users" doc in git-init manual.

Honestly speaking, I am not too thrilled about making the
cvs-migration document much longer than what it currently is.

Having said that, let's take a look at each hunk.

> @@ -71,7 +71,40 @@ Setting Up a Shared Repository
>  We assume you have already created a git repository for your project,
>  possibly created from scratch or from a tarball (see the
>  link:tutorial.html[tutorial]), or imported from an already existing CVS
> -repository (see the next section).
> +repository (see the next section). Moreover, we assume you can write in a
> +public accessible directory and give other users the permission to do so.
> +You could need or not admin privileges to do so, depending on your
> +system configuration and how you decide to export the repository.

I do not think the above helps anybody.  Later sections say
"make it writable by foo group" and such specifically, and from
such descriptions, the reader either (1) understands what are
prerequisite for being able to do so, or (2) is clueless enough
to get puzzled by failure message from "chgrp git foo", and would
not even make the connection to the above text after seeing such
a failure anyway.

> +It's recommended, but not strictly necessary, to create a specific group for
> +every project/repository you'll want to create, so it will be easier to give
> +or prevent access of users to specific repositories.

I'd say this is not git specific nor cvs migrant specific advice
but falls into a common sense category.  Better not clutter the
document with such, and keep it short and readable in one
sitting.

> +... With admin privilege launch:
> +
> +------------------------------------------------
> +$ groupadd $group
> +------------------------------------------------
> +
> +If you want to add an user to this group, launch:
> +
> +------------------------------------------------
> +$ usermod -a -G $group $username
> +------------------------------------------------

I tend to edit /etc/group with vi ;-) and I suspect these two
commands are specific to the distro you happen to use.

For something like "cvs migration", I really do not want a set
of step-by-step hand holding instructions.  Just telling them to
"pick a group for the project, make repositories belonging to
the project owned by that group, and make them writable by the
group members" should be enough.  CVS migrants may not know how
the world works with respect to git, but they are not idiots.
Introductory UNIX command guide is not the goal of the document.
Try to tell them _what_ needs to happen, not _how_, when that
level of the detail is sufficient.

> +In our example, we will store the shared repository in the /pub dir, so the
> +user creating it will need write permission there. There's no problems if you
> +choose another directory, but you'll have to ensure it will be accessible by
> +other users, on local or by remote (this could be not the case of home
> +directories).

Everything up to "by other users" is good, but ", on local or
by..." are unnecessary.  If your stress is on shared
repositories, do not even mention "home", unless you are very
convinced that it is a very typical use case, in which case you
should be certain about what you recommend and there is no place
for expression like "this could be ..." for such a sure
recommendation.

> +If you just want to create a directory that is writable by every users that have
> +a local account, launch with privileged credentials:
> +
> +------------------------------------------------
> +$ mkdir /pub
> +$ chmod a+w,+t /pub
> +------------------------------------------------

Unneeded --- again, this is not a UNIX command guide --- and
wrong.  You do not necessarily need to "launch with privileged
credentials" to do this anyway.  As long as you can chmod the
directory, that is all that is needed.

>  Next, give every team member read/write access to this repository.  One
>  easy way to do this is to give all the team members ssh access to the
>  machine where the repository is hosted.  If you don't want to give them a
>  full shell on the machine, there is a restricted shell which only allows
>  users to do git pushes and pulls; see gitlink:git-shell[1].

This part is a very good advice.  It is git specific knowledge
new cvs migrants need to learn.  Oops, the reason this part is
good is because it is from the original text --- no wonder ;-).

> -Put all the committers in the same group, and make the repository
> -writable by that group:
> +The following two commands will require admin privileges; first, enable
> +git-shell putting it on the trusted shells list of the system:
>  
>  ------------------------------------------------
> -$ chgrp -R $group /pub/my-repo.git
> +$ echo `which git-shell` >> /etc/shells
> +------------------------------------------------

Saying that /etc/shells may control what shells are allowed as
the login shell on many systems is probably a very good idea.
However, there is no need for an introductory UNIX guide that is
even WRONG.  Why "echo `foo`" when just "foo" would work?  Why
aren't you checking if /etc/shells already have git-shell
defined?

> +
> +Now, let's create the commit users:
> +
> +------------------------------------------------
> +$ useradd -g $group -s `which git-shell` $username
>  ------------------------------------------------
>  
> -Make sure committers have a umask of at most 027, so that the directories
> -they create are writable and searchable by other group members.
> +These users will be enabled to push on repositories owned by the group $group.
> +Later, you can give access to other projects simply by adding them to
> +other groups. Similarly, you can prevent access to repositories simply
> +removing those users from related groups.

The original text's point about umask does not apply to modern
git anymore, so the above lines can simply deleted.  Almost
everything else you added to this hunk is unnecessary UNIX
guide.

> --- a/Documentation/git-init.txt
> +++ b/Documentation/git-init.txt
> @@ -101,6 +101,13 @@ $ git-add .     <2>
>  <2> add all existing file to the index
>  
>  
> +SHARED REPOSITORIES
> +-------------------
> +
> +Please refer to link:cvs-migration.html[git for CVS users], section "Setting Up
> +a Shared Repository", for details on how to set up shared repositories.
> +
> +
>  Author
>  ------
>  Written by Linus Torvalds <torvalds@osdl.org>

This part is a good idea, but instead of putting it at the
bottom, it may make it more prominent to have this at the end of
option description for "--shared".

Re: [PATCH] Documentation: enhanced "git for CVS users" doc about shared repositories

[Francesco Pretto]

Junio C Hamano ha scritto:
> 
> Honestly speaking, I am not too thrilled about making the
> cvs-migration document much longer than what it currently is.
> 

Honestly speaking, you've spent too much time in looking for every possible
objections against these simple additions. At least it should be less than the
time I've spent in measuring every single word of this patch, hoping you could
consider them for inclusion. You gave me lot of attentions (I am grateful of this,
really) so I should probably be surprised of the cleanliness of git code, of the
rigor of the code style, of the clarity of the documentation. But unfortunately,
I am not. I simply tried to make this document more useful and helpful for a
wider audience of people that could ever consider of using git in their life.
And yes, I decided to so because I had trouble myself during initial configurations.
What's the problem if a document called "git for CVS users" is more explicated?
What's the problem if it contains as many as possible informations to set up
git in a viable way and, hopefully, to learn something on how it does work?

I'm sad. Not only because you refused a documentation patch, but because i could
have sent a "Bug: Documentation Sucks!" to the ml and i would have obtained the
same thing: nothing.

Francesco

P.S.:

>> +------------------------------------------------
>> +$ usermod -a -G $group $username
>> +------------------------------------------------
> 
> I tend to edit /etc/group with vi ;-) and I suspect these two
> commands are specific to the distro you happen to use.

You were right with usermod (groupadd is ok): that "-a" switch is redhat syntax.
Six years of Linux Standard Base and this is still an unsolved problem...

Re: [PATCH] Documentation: enhanced "git for CVS users" doc about shared repositories

[Johannes Schindelin]

Hi,

On Wed, 7 Nov 2007, Francesco Pretto wrote:

> I simply tried to make this document more useful and helpful for a wider 
> audience of people that could ever consider of using git in their life. 
> And yes, I decided to so because I had trouble myself during initial 
> configurations. What's the problem if a document called "git for CVS 
> users" is more explicated? What's the problem if it contains as many as 
> possible informations to set up git in a viable way and, hopefully, to 
> learn something on how it does work?

I refrained from commenting on that patch until now, but alas, you force 
me to.

I was pretty unimpressed by the additions, as they seemed large in volume, 
but small in content.

Remember, those who read "git for CVS users" are _unwilling_ to spend the 
time reading git documentation (at least for the most part).  If they 
encounter something which is not useful to them, they will not just ignore 
it, they will stop reading.

Ciao,
Dscho

Re: [PATCH] Documentation: enhanced "git for CVS users" doc about shared repositories

[Francesco Pretto]

Johannes Schindelin ha scritto:
> Remember, those who read "git for CVS users" are _unwilling_ to spend the 
> time reading git documentation (at least for the most part).  If they 
> encounter something which is not useful to them, they will not just ignore 
> it, they will stop reading.
>

That's document isn't for CVS users only. It's referred on the "Git User's Manual"
speaking about shared repositories in general. I hope you agree that the time to
make your eyes jump a little below is less than the time spent googling around
if you don't find what you are looking for.

Re: [PATCH] Documentation: enhanced "git for CVS users" doc about shared repositories

[Aghiles]

Hello,
>
> Remember, those who read "git for CVS users" are _unwilling_ to spend the
> time reading git documentation (at least for the most part).  If they
> encounter something which is not useful to them, they will not just ignore
> it, they will stop reading.
>

I must disagree with this analysis (although I didn't read the content of the
patch you are commenting). People that are not really interested in git will
find many reasons to stop reading the manual anyway. Those who really
want to migrate (such as we did) are looking for every tiny bit of information.
(We googled git commands and error messages because we didn't
find what we needed in the docs)
The docs are not perfect and somewhat unequal in content but I prefer
more information than less, at this particular stage of git development.

- Aghiles.

Re: [PATCH] Documentation: enhanced "git for CVS users" doc about shared repositories

[Steffen Prohaska]

On Nov 7, 2007, at 2:36 AM, Aghiles wrote:

> Hello,
>>
>> Remember, those who read "git for CVS users" are _unwilling_ to  
>> spend the
>> time reading git documentation (at least for the most part).  If they
>> encounter something which is not useful to them, they will not  
>> just ignore
>> it, they will stop reading.
>>
>
> I must disagree with this analysis (although I didn't read the  
> content of the
> patch you are commenting). People that are not really interested in  
> git will
> find many reasons to stop reading the manual anyway. Those who really
> want to migrate (such as we did) are looking for every tiny bit of  
> information.
> (We googled git commands and error messages because we didn't
> find what we needed in the docs)

Could you be a bit more specific? What are the most important
points that you did not found in the documentation?

It would be interesting if you could share some details. Sending
patches that would fix the deficiencies would even be
superior ;)


> The docs are not perfect and somewhat unequal in content but I prefer
> more information than less, at this particular stage of git  
> development.

I agree if it is git specific information. But, personally,
I'd get a bit annoyed if a git specific document tried to
teach me how to manage Unix accounts. BTW, useradd and such
would not help me at all, because I need to talk to my admin
anyway and he adds an account to the LDAP database.

	Steffen

Re: [PATCH] Documentation: enhanced "git for CVS users" doc about shared repositories

[Andreas Ericsson]

Steffen Prohaska wrote:
>  BTW, useradd and such
> would not help me at all, because I need to talk to my admin
> anyway and he adds an account to the LDAP database.
> 

I suspect this is the case for most companies looking to switch
to git. It certainly is here. Personally, I tend to find documents
stooping to toddler-level a bit insulting unless they're marked
as "walkthrough" or "for beginners" or some such. Especially if
they are obviously not correct for all environments.

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se
Tel: +46 8-230225                  Fax: +46 8-230231

Re: [PATCH] Documentation: enhanced "git for CVS users" doc about shared repositories

[David Kastrup]

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

> Remember, those who read "git for CVS users" are _unwilling_ to
> spend the time reading git documentation (at least for the most
> part).  If they encounter something which is not useful to them,
> they will not just ignore it, they will stop reading.

People who read documentation do this only in order to avoid reading
documentation, anyway?  This must be about the most stupid argument to
refrain from augmenting documentation I have heard in a long time.

It may well be possible that some of the proposed additions don't have
a good place in the document.  I have not checked so myself.  But the
above criticism is not constructive for documentation writers since
its logical conclusion would boil down to "don't bother writing any
documentation".

-- 
David Kastrup

Re: [PATCH] Documentation: enhanced "git for CVS users" doc about shared repositories

[J. Bruce Fields]

On Wed, Nov 07, 2007 at 12:55:49AM +0000, Johannes Schindelin wrote:
> Remember, those who read "git for CVS users" are _unwilling_ to spend the 
> time reading git documentation (at least for the most part).  If they 
> encounter something which is not useful to them, they will not just ignore 
> it, they will stop reading.

That might overstate the case a little, but I definitely agree that we
should get people to the information they need as quickly as possible,
and that adding more beginning-unix-administration will interfere with
that goal for the intended audience.

And it's not just here--there's probably lots of basic unix-commandline
stuff that we could include with the user-manual (how find/xargs pipes
work, etc...), and that would similarly help one possible audience at
the expense of bogging it down for another audience.

I think the way to help people without those prerequisites is by clearer
statements of prerequisites, and references to documentation elsewhere
where appropriate.

--b.

Re: [PATCH] Documentation: enhanced "git for CVS users" doc about shared repositories

[Wincent Colaiuta]

El 7/11/2007, a las 1:46, Francesco Pretto escribió:

> Junio C Hamano ha scritto:
>>
>> Honestly speaking, I am not too thrilled about making the
>> cvs-migration document much longer than what it currently is.
>>
>
> Honestly speaking, you've spent too much time in looking for every  
> possible
> objections against these simple additions. At least it should be  
> less than the
> time I've spent in measuring every single word of this patch, hoping  
> you could
> consider them for inclusion. You gave me lot of attentions (I am  
> grateful of this,
> really) so I should probably be surprised of the cleanliness of git  
> code, of the
> rigor of the code style, of the clarity of the documentation. But  
> unfortunately,
> I am not. I simply tried to make this document more useful and  
> helpful for a
> wider audience of people that could ever consider of using git in  
> their life.
> And yes, I decided to so because I had trouble myself during initial  
> configurations.
> What's the problem if a document called "git for CVS users" is more  
> explicated?
> What's the problem if it contains as many as possible informations  
> to set up
> git in a viable way and, hopefully, to learn something on how it  
> does work?
>
> I'm sad. Not only because you refused a documentation patch, but  
> because i could
> have sent a "Bug: Documentation Sucks!" to the ml and i would have  
> obtained the
> same thing: nothing.

On the contrary, I think you received some excellent, high-quality  
feedback. The process that you've been participating in over the last  
few days is exactly why the Git codebase is as good as it is; only the  
very best patches get accepted, and those which aren't "the very best"  
receive detailed feedback that help the submitter to turn weak patches  
into strong ones. The process works very well and the proof is in the  
pudding (the quality of the product).

Cheers,
Wincent

Re: [PATCH] Documentation: enhanced "git for CVS users" doc about shared repositories

[Steffen Prohaska]

On Nov 7, 2007, at 1:46 AM, Francesco Pretto wrote:

> Junio C Hamano ha scritto:
>>
>> Honestly speaking, I am not too thrilled about making the
>> cvs-migration document much longer than what it currently is.
>>

Maybe the description of setting up a shared repository should
go to the user-manual and cvs-migration should refer to the
user-manual, instead of the other way round. I don't like the
idea that the user-manual is referring to a CVS specific guide.
The user manual should be as self-contained as possible.


> Honestly speaking, you've spent too much time in looking for every  
> possible
> objections against these simple additions. At least it should be  
> less than the
> time I've spent in measuring every single word of this patch,  
> hoping you could
> consider them for inclusion. You gave me lot of attentions (I am  
> grateful of this,
> really) so I should probably be surprised of the cleanliness of git  
> code, of the
> rigor of the code style, of the clarity of the documentation. But  
> unfortunately,
> I am not. I simply tried to make this document more useful and  
> helpful for a
> wider audience of people that could ever consider of using git in  
> their life.
> And yes, I decided to so because I had trouble myself during  
> initial configurations.
> What's the problem if a document called "git for CVS users" is more  
> explicated?
> What's the problem if it contains as many as possible informations  
> to set up
> git in a viable way and, hopefully, to learn something on how it  
> does work?
>
> I'm sad. Not only because you refused a documentation patch, but  
> because i could
> have sent a "Bug: Documentation Sucks!" to the ml and i would have  
> obtained the
> same thing: nothing.

Don't be unfair. Junio made clear that the documentation
should not be cluttered with an introduction to Unix commands.
But at least two points (git-shell, git-init.txt) would be
accepted if you sent an cleaned-up patch.

I have no good idea how to reconcile your idea of giving more
guidance to Unix commands with the idea of having a concise
document that assumes a reader with decent Unix knowledge

Maybe you could just add some references to the distribution
specific information, or just refer to the man pages.

Maybe you could move the introductory comments to a FAQ-like
appendix. It could give brief hints on
"How to set up a user account?",
"How to setup a world-writable directory?"
I'm a bit reluctant to this because we'd need to maintain such
information. But I suspect that some users would find them
helpful.

One last comment: discussing patches is how the world works on
the git mailing list. It happend to me, too, that patches were
rejected after a brief or after a lengthy discussion. So, yes,
finally sometimes there is no change. But often the discussions
reveal a better way of achieving the original goal. Nonetheless,
it can be frustrating to the original author.

Thanks for you effort of improving the documentation.

	Steffen

Re: [PATCH] Documentation: enhanced "git for CVS users" doc about shared repositories

[J. Bruce Fields]

On Wed, Nov 07, 2007 at 09:07:58AM +0100, Steffen Prohaska wrote:
> On Nov 7, 2007, at 1:46 AM, Francesco Pretto wrote:
>
>> Junio C Hamano ha scritto:
>>>
>>> Honestly speaking, I am not too thrilled about making the
>>> cvs-migration document much longer than what it currently is.
>>>
>
> Maybe the description of setting up a shared repository should
> go to the user-manual and cvs-migration should refer to the
> user-manual, instead of the other way round. I don't like the
> idea that the user-manual is referring to a CVS specific guide.
> The user manual should be as self-contained as possible.

I'd be interested in patches that did that.  If somebody wants to work
on that, they might want to start with

	git://linux-nfs.org/~bfields/git.git docwork-foreign-scms

which has the skeleton of an "interoperating with foreign scms" chapter.

The thing that's kept me from working on this in the past is that it's a
bit of a step backwards for someone that *just* wants to get to the
cvs-migration stuff, since now it may appear you have to plow through
the rest of the manual to get to it.

We could address that with clearer dependency information ("before
reading this chapter, read chapters 1 and 3..."), and/or by providing
some more links (e.g. repopulate the howto directory with links to some
chapters that address popular questions).

--b.