[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Re: Tip of the day: Cheatsheet for common cmdline client operations

From: Pavel Lyalyakin <pavel.lyalyakin_at_visualsvn.com>
Date: Thu, 14 Sep 2017 18:27:47 +0300

Hello,

On Wed, Aug 30, 2017 at 11:22 PM, Johan Corveleyn <jcorvel_at_gmail.com> wrote:
>
> On Tue, Aug 29, 2017 at 2:15 PM, Pavel Lyalyakin
> <pavel.lyalyakin_at_visualsvn.com> wrote:
> > Hello,
> >
> > On Fri, Aug 25, 2017 at 2:03 PM, Johan Corveleyn <jcorvel_at_gmail.com> wrote:
> >>
> >> [ cc -= svnbook-dev, as I guess this will not become book-material.
> >> More below ... ]
> >>
> >> On Thu, Jul 13, 2017 at 6:34 PM, C. Michael Pilato
> >> <cmpilato_at_red-bean.com> wrote:
> >> > On Thu, Jul 13, 2017 at 11:21 AM, Daniel Shahaf <d.s_at_daniel.shahaf.name>
> >> > wrote:
> >> >>
> >> >> [moving from users@ ]
> >> >>
> >> >> Daniel Shahaf wrote on Fri, 30 Jun 2017 09:15 +0000:
> >> >> > I just ran into the following cheatsheet:
> >> >> >
> >> >> > http://www.chim.unifi.it/~signo/did/etc/subversion/neat.html
> >> >> >
> >> >> > It covers the normal multi-user workflow, branching, etc..
> >> >> >
> >> >> > (Kudos to the author, Giorgio Signorini, not to me.)
> >> >>
> >> >> As some of you know, the author gave us permission to incorporate that
> >> >> cheatsheet into the official documentation. Any volunteers to start the
> >> >> process?
> >> >>
> >> >> Cheers,
> >> >>
> >> >> Daniel
> >> >>
> >> > With respect to the author and the work he's done, I'm not really interested
> >> > in us maintaining yet another collection of the same information already
> >> > covered -- in some cases multiple times, when you factor in the reference
> >> > sections -- by the book. At best this cheatsheet would be an appendix. I'm
> >> > happy to link to the cheatsheet from from the book website, though.
> >> >
> >> > -- Mike
> >>
> >> FWIW, I think this cheatsheet is quite good and valuable (though I
> >> agree there is a lot of overlap with existing documentation),
> >> especially for newcomers. Just to have a good summary / reminder of
> >> common things you'll encounter.
> >>
> >> We have our own quickstart page: http://subversion.apache.org/quick-start
> >>
> >> How about:
> >>
> >> - Putting a link at the bottom of that page (there is already a link
> >> to the quickstart section of the book), linking to the original
> >> webpage of the author.
> >>
> >> or
> >>
> >> - Incorporating (some of) the content of that cheatsheet directly on
> >> http://subversion.apache.org/quick-start, so it's right there in front
> >> of you ...
> >>
> >>
> >> The latter option would be my personal preference (putting my user /
> >> admin hat on) -- I like having short info right in front of me in the
> >> right place -- but obviously imposes some amount of doc-maintenance
> >> work on "us".
> >>
> >> Maybe someone on this list would be willing to take this doc-task
> >> (migrating the current content, and keep an eye on keeping it up to
> >> date)?
> >>
> >> --
> >> Johan
> >
> > IMO, this doc-task has to be reworded into composing a walkthrough for SVN end
> > user who wants to start performing basic version control tasks over remote
> > repository, but did not read SVNBook or other SVN-related documentation. What do
> > you think?
> >
> > I feel that the cheatsheet[1] needs to be reworked or at least restructured. In
> > the current state I feel that it is just personal notes that describe various
> > common SVN tasks, actions and tricks. Cheatsheet or personal notes is not
> > a "quick start" guide.
>
> Hm, I guess you're right. Though I think there is also a place for
> snippets / reminders / recipes (common SVN tasks, actions and tricks),
> I suppose a good walkthrough is even better for bootstrapping new
> users.
>
> > Anyway, I like the idea of adding some of the content from the cheatsheet to
> > the quick start page[2] and I would be glad to take this task.
>
> That would be great!

I've spent some time to materialize the Quick Start document that I
think will be helpful for novice SVN users. At the moment, it provides
the most basic guidance which should be enough for "quick start".
However, it lacks "Viewing the history of changes" section that is not
ready yet. As of merging, I'd better provide a link to relevant
SVNBook sections. Merging is not a basic topic and should not be
described in a Quick Start guide, IMO.

I'm attaching two patches. I would greatly appreciate a review,
comments and suggestions. Here we go:
1. svn-quick-start-eol-native-v1.patch.txt
   Log Message:
   [[[
   Add missing svn:eol-style=native property to publish/quick-start.html
   ]]]
2. svn-updated-quick-start-v1.patch.txt
    Log Message:
   [[[
   * publish/quick-start.html:
     Updating the SVN Quick Start guide as suggested in
     https://lists.apache.org/thread.html/ea3462042131baac9c702fd4f19ae292c25ef20527d27db449e90f0e@%3Cdev.subversion.apache.org%3E
   ]]]

> > The question is: what kind of topics should the quick start page cover?
> >
> > My idea is that the page should provide task-based guidance for SVN end user on
> > how to
> > * checkout a working copy,
> > * update the working copy,
> > * modify the data in the working copy and commit it,
> > * make a branch or tag,
> > * perform a simple merge.
>
> Sounds terrific.
>
> The current quickstart page focuses on "how do I quickly set up a my
> own little repository, locally (with file:///) and put some stuff in
> there". Like a beginning user / student / ... perhaps would like to
> version his own files. I think it's a good way to introduce the
> concepts of repository and working copy, and help them get started by
> versioning some of their own files locally.

SVNBook has a High-Speed Tutorial that provides such instructions:
http://svnbook.red-bean.com/en/1.8/svn.intro.quickstart.html

> Do you think you can start from that "setup", and continue with the
> topics you listed above? Or would you like to take a different angle?

I'm thinking about taking a different angle. I think that the document
should assume that a remote Subversion repository is already in place
and the user simply wants to start working with the existing versioned
data. Or he wants to import non-versioned data to the new remote
repository or repository sub-path.

In my experience, a beginning user or a student already has a
repository that he access via HTTP(S) or svnserve protocol. For
example, a first-year student gains access to his private SVN
repository and never has to use file:// schema or `svnadmin` tool.
There is another case, when a user should first request to create a
repository for him or for his project (here is an example:
http://information-technology.web.cern.ch/book/how-start-working-svn/requesting-new-svn-repository).
He won't use file:// schema and `svnadmin` in this case, too.

> > BTW, don't miss SVN-related docs on StackOverflow Documentation[3]. I'm pretty
> > sure that some of the topics from that doc will be useful.
>
> Interesting! Maybe we can link to that, or look what of those topics
> we can cover as well.
>
> > [1]: http://www.chim.unifi.it/~signo/did/etc/subversion/neat.html
> > [2]: http://subversion.apache.org/quick-start
> > [3]: https://stackoverflow.com/documentation/svn/topics
> >
> > --
> > With best regards,
> > Pavel Lyalyakin
> > VisualSVN Team
>
> Thanks for taking a look at this.
>
> Cheers,
> --
> Johan

--
With best regards,
Pavel Lyalyakin
VisualSVN Team


Received on 2017-09-14 17:28:37 CEST

This is an archived mail posted to the Subversion Dev mailing list.