Milestone 1 user-interface

[Ben Collins-Sussman <su...@newton.collab.net>]

Here are some thoughts on the client user-interface for Milestone 1.

to resemble cvs as much as possible;  it should be obvious to any cvs
user how to use the `svn' binary.

However, for Milestone 1, the client and server will be communicating
through XML files rather than through a network.  This means we have
to add some new switches to the command-line relating to reading and
writing XML files.

There are two independent questions to consider here:

      1.  Are we sending or receiving changes?

          Specifically, the client can either "commit" a tree-delta
          and create an XML file, or it can "update" (or "checkout") a
          tree-delta from an existing XML file.

      2.  Are the changes "official", or are they "under the table"?

          Let's define these terms:  By "official", we mean that the
          commit or update is documented in the working copy
          administrative files.  "Under the table" means that the
          commit or update took place, but nothing was recorded about
          it. 


These questions can give us a cute little chi-square of permutations,
describing all the possible behaviors of the client:

* Sending "officially"

  The client commits a tree-delta into an XML file.  The relevant
  entries in admin files are updated to a single version number.

      --> Note that in normal circumstances, the repository would
          return the new version number to the client.  In the case of
          XML files, it will be necessary for the user to manually
          specify a new version number on the command line.

* Sending "under the table"

  The client commits a tree-delta into an XML file.  No admin files
  change at all.  As far as the working copy is concerned, nothing
  ever happened.

      --> This is a method for generating an XML "patch" that you
          might want to give to someone else.  Actually, it's an
          extension of the whole patch concept: it not only contains
          file diffs, but tree changes as well.

* Receiving "officially"

  The client updates (or checks-out) a working copy from an XML file.
  All administrative files record this event.

      --> Nothing special about this, just an ordinary update.

* Receiving "under the table"

  The client updates a working copy from an XML file, but no
  administrative records are made.

      --> Again, this is the other side of our "extended patch" idea.
          Just as people apply patches to CVS working copies to test
          somebody's contribution (before committing it), Subversion
          users can patch *whole trees* in an SVN working copy and
          test behaviors as well.


We need a good name for an "extended patch" object, and right now
we're thinking about calling it a "delta".  Instead of posting patches
to mailing lists, developers can trade "deltas" informally in the same
way.   (Is this a good name?)


Ideas for command line switches that deal with XML files:

* Sending "officially"

    svn commit -o file.xml -v 38

    (The -v flag defines an imaginary version number that would
    normally returned by the repository upon a successful commit.
    This new version number is recorded in administrative files.)

* Sending "under the table"

    svn commit -o file.xml

    (Without a -v flag, the admin files aren't changed at all;  this
    command does nothing but generate a delta.)

* Receiving "officially"

    svn update -o file.xml
    svn checkout -o file.xml

    (A normal working copy update or checkout.)

* Receiving "under the table"

    svn update -o file.xml -p

    (? Perhaps the -p means "patch only, don't actually record an update.")



So there's a first draft, a blueprint for the bike-shed.

Thoughts?  :)

Re: Milestone 1 user-interface

[Karl Fogel <kf...@galois.collab.net>]

Ben Collins-Sussman <su...@newton.collab.net> writes:
> The XML file doesn't need a version number; the working copy
> administrative files do!  After the working copy has sent a "commit"
> into a file, it needs to update its own administrative files to
> reflect the new version.  (In the real world, this version number
> would be returned by the respository after a successful commit.)

I.e., this is a temporary hack for Milestone 1, because the repository
has no way of telling this new version number to the wc right now. :-)

Re: Milestone 1 user-interface

[Ben Collins-Sussman <su...@newton.collab.net>]

Bob Miller <kb...@jogger-egg.com> writes:

> Ben Collins-Sussman wrote:
> 
> >       --> Note that in normal circumstances, the repository would
> >           return the new version number to the client.  In the case of
> >           XML files, it will be necessary for the user to manually
> >           specify a new version number on the command line.
> 
> Why does the XML file need to have a version number?
> Each changed file and directory has a ancestor version, isn't
> that sufficient?
> 

The XML file doesn't need a version number; the working copy
administrative files do!  After the working copy has sent a "commit"
into a file, it needs to update its own administrative files to
reflect the new version.  (In the real world, this version number
would be returned by the respository after a successful commit.)

Re: Milestone 1 user-interface

[Bob Miller <kb...@jogger-egg.com>]

Ben Collins-Sussman wrote:

>       --> Note that in normal circumstances, the repository would
>           return the new version number to the client.  In the case of
>           XML files, it will be necessary for the user to manually
>           specify a new version number on the command line.

Why does the XML file need to have a version number?
Each changed file and directory has a ancestor version, isn't
that sufficient?

-- 
                                        K<bob>
kbob@jogger-egg.com, http://www.jogger-egg.com/

Re: Milestone 1 user-interface

[RADICS Peter <mi...@deneb.lbcons.net>]

On Thu, Oct 05, 2000 at 11:39:21AM -0500, Ben Collins-Sussman wrote:
[SNIP]
> Ideas for command line switches that deal with XML files:
> 
> * Sending "officially"
> 
>     svn commit -o file.xml -v 38

 Since this is the "standard" behaviour, I think it's not wise to use a
 switch here (-v) to specify that it's the "official" one. Or at least,
 this would only be a temporary switch that would go away once the
 version number is automatically generated.  I think, instead the "under
 the table" behaviour should be flagged, since it's some extended
 feature, that CVS doesn't have, and is usually not the "standard"
 commit.

> 
>     (The -v flag defines an imaginary version number that would
>     normally returned by the repository upon a successful commit.
>     This new version number is recorded in administrative files.)
> 
> * Sending "under the table"
> 
>     svn commit -o file.xml

 So, according to the previous explanation, this should look like
      svn commit -p -o file.xml

 The -p switch is chosen here 'cos that's what you proposed for 
 "under the table checkouts.  I think these should be consistent
 (although, the exact switch should probly be something else, IMO, since
 -p is already defined for CVS checkouts and updates, and means
 something else, that you might want to implement later to svn anyway.
 Finding a good switch for the "delta" (ie. extended patch) generation
 won't be easy :)

 And I also agree with Karl, that the -o is not the best choice
 either...

 Summary: I'd like the "default" behaviour to work without additional
 switches (the -v at this point is probly unavoidable, but it should go
 away), and I'd like to use the same switch for checkins and
 checkouts/updates when I wan't to use the "extended patch" feature.


[SNIP]
> Thoughts?  :)

ps: Sorry to just shout out from the bushes :) I've been lurking around
    since a while, and maybe later I can contribute some code as well...
    Till then I'll just keep my eyes open, and tell you my thoughts, if
    nobody minds.

cheers,
mitch

-- 
// RADICS Peter <mi...@lbcons.net> (http://lbcons.net)
//
// "If human beings don't keep exercising their lips, 
//  their brains start working." -- Ford Prefect

Re: Milestone 1 user-interface

[Karl Fogel <kf...@galois.collab.net>]

Ben Collins-Sussman <su...@newton.collab.net> writes:
> Ideas for command line switches that deal with XML files:
> 
> * Sending "officially"
>     svn commit -o file.xml -v 38
>     (The -v flag defines an imaginary version number that would
>     normally returned by the repository upon a successful commit.
>     This new version number is recorded in administrative files.)
> 
> * Sending "under the table"
>     svn commit -o file.xml
>     (Without a -v flag, the admin files aren't changed at all;  this
>     command does nothing but generate a delta.)
> 
> * Receiving "officially"
>     svn update -o file.xml
>     svn checkout -o file.xml
>     (A normal working copy update or checkout.)
> 
> * Receiving "under the table"
>     svn update -o file.xml -p
>     (? Perhaps the -p means "patch only, don't actually record an update.")
> 
> So there's a first draft, a blueprint for the bike-shed.
> 
> Thoughts?  :)

I like it.  Recommend that the xml-file switch be the same in all
cases, but that it not be "-o", since that's a mnemonic for
"--output-file", which is the wrong direction for updates.

How about "--xml-file"? :-)