[Secure-testing-commits] r12667 - doc

[Michael S. Gilbert]

On Mon, 24 Aug 2009 14:20:59 +0200, Nico Golde wrote:
> Hi,
> * Michael Gilbert <gilbert-guest at alioth.debian.org> [2009-08-23 21:05]:
> > Author: gilbert-guest
> > Date: 2009-08-23 18:47:17 +0000 (Sun, 23 Aug 2009)
> > New Revision: 12667
> > 
> > Modified:
> >    doc/narrative_introduction
> > Log:
> > add some additional info on revision control
> > 
> > Modified: doc/narrative_introduction
> > ===================================================================
> > --- doc/narrative_introduction	2009-08-23 18:06:58 UTC (rev 12666)
> > +++ doc/narrative_introduction	2009-08-23 18:47:17 UTC (rev 12667)
> > @@ -54,17 +54,52 @@
> >  at home. To do this, you need an Alioth account, and then you just
> >  need to do the following:
> >  
> > -svn co svn+ssh://svn.debian.org/svn/secure-testing
> > +svn co svn+ssh://<alioth user name>@svn.debian.org/svn/secure-testing
> >  
> > -This will check out our working repository into a directory called
> > -secure-testing. Inside this directory are a number of subdirectories.
> > -The data directory is where we do most of our work. 
> > +This will check out our working repository after asking for your alioth
> > +password twice. This is normal and to be expected. After successfully
> > +downloading, you will have a new directory called secure-testing. Inside
> > +this directory are a number of subdirectories.  The data directory is
> > +where we do most of our work.  If you don't have Alioth account, you can
> > +create one at:
> >  
> > +https://alioth.debian.org/account/register.php
> > +
> >  If you don't need write access, you can of course check out our files
> >  without an Alioth account as well:
> >  
> >  svn co svn://svn.debian.org/svn/secure-testing
> >  
> > +If you are a git fan, you can also use git-svn. Once you have the
> > +git-svn package installed, you can clone the subversion repository into
> > +your own local git repository with:
> > +
> > +git svn clone svn+ssh://<alioth user account>@svn.debian.org/svn/secure-testing
> > +
> > +Note that this will take a very long time (expect over two hours) since
> > +every commit from the very beginning (over 12,000 at this point) is
> > +checked out individually and merged into your git repository.
> > +
> > +Subversion and git-svn Crash Course
> > +-----------------------------------
> > +
> > +The following table lists the most common/useful commands for working
> > +with the secure-testing repository:
> > +
> > +  subversion       | git-svn           | action
> > +  -----------------+-------------------+------------------------------
> > +  svn update       | git svn rebase    | sync your local repo from
> > +                   |                   | remote secure-testing repo
> > +  -----------------+-------------------+------------------------------
> > +  svn commit       | git commit -a     | commit your changes to the
> > +                   | git svn dcommit   | remote secure-testing repo
> > +                   |                   | (note that 'git commit -a'
> > +                   |                   | only updates your local repo)
> > +  -----------------+-------------------+------------------------------
> > +  svn diff         | git diff          | compare your local repo to
> > +                   |                   | remote secure-testing repo
> > +  -----------------+-------------------+------------------------------
> > +
> 
> Do we really need to reproduce content which is present in 
> any documentation online in our narrative introduction? I 
> can't remember anyone having problems with the rcs we use so 
> far.

i see no harm in reproducing this information (except for the fact
that variable-width fonts mangle the formatting). it maybe takes up
500 additional bytes. is that worth worrying over? i purposefully made
it succinct and compact because i felt that verbosity was unnecessary,
and as you point out, more comprehensive information is available
elsewhere. however, providing complete getting started documentation
will lower the barrier-to-entry for potential casual/beginner
contributors; who will hopefully learn to contribute at a useful level
after some time -- kind of like the evolution i am going through now.

also, i figured it would be useful to share my knowledge of how to use
git-svn in case others are interested in using or switching to that.

however, i understand that it's your call.  if you don't want it, remove
it.

mike