A UI Specification for "Locking"

This document describes a user interface of a new locking system for
Subversion.  It implements the set of features described in the
associated functional spec.

I. Introduction

   A. Goals/Audience

      There are two audiences we need to consider for a locking UI:

      1. The enlightened software developer

         - understands general VC concepts (required for job)
         - understands concurrency model
         - has already embraced Subversion (or at least CVS)

         - ITCH: Some files aren't mergeable, like image files or
                 spreadsheets.  Need to force serialized edits on such
                 things, as an occasional exception to concurrency.

      2. The reluctant user of version control

         - bright people, but no time or interest in learning VC concepts
         - doesn't understand concurrency
         - doesn't understand "out-of-dateness" or merging procedures

         - typical examples:
            - coder who has only used VSS or Clearcase with 100% locking
            - website developer being forced to use VC
            - manager being forced to use VC

         - ITCH: VC system should be effortless, transparent, and
                 idiot proof.  VC system should prevent people from
                 wasting editing time, destroying each others
                 changes, all while avoiding concurrency concepts such
                 as "merging" and "out of dateness".


   B. The "Hijack" Scenario

       This is specific use-case which is particularly important to
       making version control usable by the second type of user
       described above.

       In this scenario, the user has a tool that circumvents whatever
       system is in place to enforce serialized editing.  In systems
       like VSS or Clearcase 'copy' views, this usually means an
       editor that ignores the read-only attribute on a file.  When
       the user goes to commit, they discover that they were supposed
       to lock the file, and the repository version has changed.  What
       now?

       The power-svn user would certainly have no problem knowing what
       to do seeing an error that "the file must be locked to commit",
       nor would such a user be confused by seeing a subsequent error
       that the "file is out-of-date".  The power user would run 'svn
       update', resolve conflicts, then lock the file and commit.

       But the reluctant or ignorant svn user shouldn't (and doesn't
       need to) be forced to deal with merging and out-of-dateness
       when working in an "all locking" environment.  Here are a few
       usability case-studies:

         - Clearcase dynamic views

             The workspace is always up-to-date, all of the time.  And
             it's impossible to circumvent the read-only bit.  So the
             hijack scenario can't happen at all.

         - Clearcase copy-based views
 
             In the hijack scenario, the user attempts to commit and
             the client responds by attempting an interactive
             contextual merge.  If not possible, the whole commit
             fails and a guru is phoned to fix the situation.

         - Visual Source Safe

             in the hijack scenario, the user remembers to lock the
             file long after editing it;  VSS asks whether to use the
             server version or local version of the file.  Somebody's
             edits are lost.

       It is the recommendation of this document that the command line
       client produce normal conflicts when 'svn up' is run on a
       hijacked file;  but that for a GUI such as TortoiseSVN, a more
       friendly (or interactive) procedure is followed -- perhaps one
       that allows the user to choose between versions of files.


II. New Client Behaviors

   A. Overview

      This section describes a user interface to accomplish "locking",
      as described in the functional spec.  A new property is used to
      enforce locking and prevent people from wasting time; lock
      tokens are objects, stored in the working copy, that represent a
      lock; and two new subcommands (lock/unlock) are described.

   B. The "svn:needs-lock" property

      Create a new "svn:needs-lock" property to indicate that a file
      should be locked before committing.  Just like "svn:executable",
      the value of the property is irrelevant and the property can be
      created (or deleted) by any user or administrator.

      Note that this property doesn't enforce locking.

      When the Subversion client encounters the "svn:needs-lock"
      property on a path (on checkout or update), it sets the
      working-copy path to a read-only state by default.  This
      serves as a reminder to the user that she should lock this
      path before editing it.  When a user locks the path, the
      Subversion client makes the working-copy path read-write.
      When the user releases the lock, or if the lock is found to
      be defunct (see next section), the Subversion client makes
      the path read-only again.

   C. Lock manipulation via client

      1. Lock Tokens

         When a user successfully locks a path, the working copy
         receives a "lock token" from the server.  This token is an
         object that connects your exclusive right to commit to a path
         with your working copy.

         You can think of a lock token as a form of authentication for
         a certain working copy.  Why is it important or useful for
         lock tokens to be attached to only one working copy?

         [An example: you might lock an unmergeable file using a
         computer at your office, perhaps as part of a changeset in
         progress.  It should not be possible for a working copy on
         your home computer to accidentally commit a change to that
         same file, just because you've authenticated as the user
         which owns the lock.  If you really want to change the file
         from home, you'd have to "steal" the lock from your other
         working copy, which is discussed later in this document.]

         Because locks can be broken or stolen, it is possible for a
         lock token to become "defunct".  A defunct lock cannot be
         used or released--it is useless and is cleaned up when you
         next run 'svn update'.

      2. New client subcommands
          
         Summary:

              svn lock   [--force]:   lock (or steal)
              svn unlock [--force]:   release (or break)


         a. Creating a lock

            To lock a path, use the 'svn lock' command:

              $ svn lock foo.c
              username: harry
              password: XXXXX
              [...]
              'foo.c' locked by user 'harry'.
        
            In order for this command to work,

               - You *must* provide a username to the server.
                 'anonymous' locks are not allowed.
               - The path must not already be locked.
               - The path must not be out-of-date.  

            The lock command accepts -m or -F to add a lock comment, so
            others can see why the file was locked.  The lock comment
            is optional.

         b. Using a lock

            A lock can be used to make an exclusive commit to a path.
            Also, if you have a lock, you can opt to "release"
            (destroy) it when you're done.

            To make use of a lock, two forms of authentication must be
            provided to the server:

               - The authenticated username that owns the lock
               - A non-defunct lock token

            If either of these forms of authentication are missing or
            incorrect, the lock cannot be used.

            1. Using a lock to Commit

               $ svn commit foo.c
               
               Upon successful commit, a locked path is released by
               default.  The Subversion client provides an option to
               retain the lock after commit:

               $ svn commit foo.c --no-unlock

               If --no-unlock is not specified, even unmodified files
               will be considered part of the commit and shown to the
               user in the list of files to commit.  Such files will
               also be unlocked after the commit.

            2. Releasing a lock
 
               $ svn unlock foo.c
               Lock on 'foo.c' has been released.

               After successful release, the working copy's lock token
               is gone.

         c. Breaking a lock

            "Breaking" a lock is a means of releasing a lock when:

               - The authenticated username is not the same as the
                 lock owner, or
               - The working-copy lock representation is unavailable.

             Use the --force option to the unlock subcommand to
             break a lock.  For example:

             $ svn unlock foo.c
             username:  sally
             password:  XXXX
             svn:  error:  'foo.c' is locked by user 'harry'.

             $ svn unlock foo.c --force
             username:  sally
             password:  XXXX
             Lock on 'foo.c' has been broken.

             The --force option also accepts a URL, so that the lock
             can be
             released without a working copy.

         d. Stealing a lock

            "Stealing" a lock is a means of creating a lock when:

               - The path is locked by you, but you don't have a
                 representation of the lock in your current working
                 copy, or
               - The path is locked by someone else.

            In order to steal a lock, a user must be authenticated to
            the server.

            Use the --force option to the lock command to steal a
            lock.  For example:

              $ svn lock foo.c
              username:  sally
              password:  XXXX
              svn:  error:  'foo.c' is locked by user 'harry'.

              $ svn lock foo.c --force
              username:  sally
              password:  XXXX
              'foo.c' locked by user 'sally'.

              Remember that the 'svn lock' command still requires that the
              target be up-to-date to succeed.


         e. Discovering/examining locks

            1. seeing lock tokens in a working copy

               'svn status' considers a lock token "interesting", and
               displays it using some new symbol, in a new column:

                   $ svn status
                   M      foo.c
                   M    K bar.c
                   A      baz.c 

               Note that K (locKed) is used instead of the more
               intuitive L, since L is already in use for another purpose.

            2. seeing locks in a repository.

               'svn status -u' adds out-of-date information from the
               server;  in a similar manner, this command shows any
               locks that exist on the server:

                  $ svn status -u
                  M                   foo.c
                  M    K              bar.c
                  A      *            baz.c
                         *            file1
                       O              file2
                  M    B             file3
                   M   T             file42

               As with "svn status", the sixth column indicates lock
               state.  The letters have the following meanings:
               ' ': No lock in either WC or repository.
               'K': Locked in the WC and lock token valid in
                    repository.
               'O': No lock in WC, lock in repository. (Locked in
                    Other WC.)
               'B': Lock in WC, but no lock in repository. (Lock
                    Broken.)
               'T': Locked in WC, but locked with another token in
                    repository.  (Lock was sTolen.)
            
            3.  'svn info', describes the attributes of a lock-token,
                if attached to a working object.  If invoked on a URL,
                it displays information about any remote lock
                attached. 

                   $ svn info foo.c
                   Path: foo.c
                   Name: foo.c
                   URL: http://..../
                   [...]
                   Lock Token: 465610b1-33eb-0310-8a02-cae41507c13a
                   Lock Owner: lundblad
                   Lock Comment: Refactoring.
                   Lock Creation Date: 2004-12-14 14:49:36 +0100 (Tue, 14 Dec 2004)
                 

                   $ svn info http://host/repos/file2
                   Path: /file2
                   Name: file2
                   URL: http://..../
                   [...]
                   Lock Token: 465610b1-33eb-0310-8a02-cae41507c13b
                   Lock Owner: fitz
                   Lock Comment: Don't touch my file!
                   Lock Creation Date: 2004-12-25 14:49:36 +0100 (Tue, 14 Dec 2004)

            4. 'svn update' changes

                At the start of an update, the client reports any
                lock-tokens to the server.  If a lock token has become
                "defunct", the client is instructed to destroy the lock
                token.

                A new column will be added to the update output to indicate
                removed lock tokens:

                svn up
                U     path1
                 U    path2
                  B   path3
                C B   path4

                In the above example, lock tokens for path3 and path4
                were removed.  Note that 'B' is used even if there is
                a new lock in the repository.

III. New Server Behaviors

   A. Overview

      This section describes new server UIs for locking:  two new hook
      scripts, a new 'svnlook' subcommand, and a new 'svnadmin' subcommand.

   B. Tracking locks

      The Subversion server holds the master list of all locks for a
      repository.  It responds to client requests to create, release,
      break and steal locks.  

   C. Enforcement

      During a commit, the server checks for locks the same way that
      it checks for out-of-dateness:

        $ svn commit
        Sending foo.c
        Sending bar.c
        svn: error:  'bar.c' is locked by user 'harry'.


   D. Configurable Mechanisms

      1. New "pre-" hook scripts

        a. pre-lock

           Used to authorize lock creation.  Invoked whenever a user
           creates a lock ('svn lock') or steals a lock ('svn lock
           --force').  If an administrator wants the locking feature
           completely disabled, just set this hook to always return failure.

             - input: REPOS, PATH, USER
             - successful exit means lock is allowed, else deny lock creation.
             - if path is already locked, hook script can deduce 
               that USER is "stealing" the lock and decide what to do.

        b. pre-unlock

           Used to authorize lock releasing.  Invoked whenever a user
           releases a lock ('svn unlock) or breaks a lock ('svn
           unlock' --force).

             - input: REPOS, PATH, USER
             - successful exit means release is allowed, else deny.
             - if path is already locked, hook script can deduce 
               that USER is "breaking" the lock and decide what to do.

      2. New "post-" hook scripts

        a. post-lock

           Used to report lock creation.  Invoked whenever a user
           creates a lock ('svn lock') or steals a lock ('svn lock
           --force'). 

             - input: REPOS, PATH, USER
             - exit code ignored
             - can be used to send email, collect statistics, etc.

        b. post-unlock

           Used to report lock release.  Invoked whenever a user
           releases a lock ('svn unlock') or breaks a lock ('svn unlock
           --force').

             - input: REPOS, PATH, USER
             - exit code ignored
             - can be used to send email, collect statistics, etc.


   E. Lock manipulation with svnadmin

      1. Discovering locks

         A new 'svnlook listlocks' subcommand shows all current locks
         in a repository:

           $ svnlook listlocks /usr/local/svn/repos
            #     harry    Aug 16 15:13   /trunk/bar.c
            #     sally    Sep 07 09:30   /trunk/doc/foo.doc


      2. Unconditional release of locks

         A new 'svnadmin unlock' subcommand to unconditionally
         release a lock.  Note that this command circumvents hook
         scripts, much like other svnadmin actions:

           $ svnadmin unlock /usr/local/svn/repos /trunk/doc/foo.doc
           Lock on '/trunk/doc/foo.doc' has been released.