← Back to branch summary

~ubuntu-branches/ubuntu/trusty/subversion/trusty-proposed

« back to all changes in this revision

Viewing changes to notes/locking/locking-functional-spec.txt

  • Committer: Package Import Robot
  • Author(s): Andy Whitcroft
  • Date: 2012-06-21 15:36:36 UTC
  • mfrom: (0.4.13 sid)
  • Revision ID: package-import@ubuntu.com-20120621153636-amqqmuidgwgxz1ly
Tags: 1.7.5-1ubuntu1
* Merge from Debian unstable.  Remaining changes:
  - Create pot file on build.
  - Build a python-subversion-dbg package.
  - Build-depend on python-dbg.
  - Build-depend on default-jre-headless/-jdk.
  - Do not apply java-build patch.
  - debian/rules: Manually create the doxygen output directory, otherwise
    we get weird build failures when running parallel builds.

Show diffs side-by-side

added added

removed removed

Lines of Context:
notes/locking/locking-functional-spec.txt
1
 
A Functional Specification for "Locking"
2
 
 
3
 
This document describes the features of a new locking system for
4
 
Subversion.  It attempts to avoid specific design and implementation
5
 
choices wherever possible.
6
 
 
7
 
A separate document will outline a proposed implementation for this
8
 
specification.
9
 
 
10
 
I. Introduction
11
 
 
12
 
   A. Goals
13
 
 
14
 
      1. Provide a mechanism to ensure that a user has exclusive
15
 
         rights to commit changes to a file from a particular working
16
 
         copy.
17
 
 
18
 
      2. Provide a communication mechanism to decrease the chances of
19
 
         a user wasting time working on a file locked by someone else.
20
 
 
21
 
   B. Summary
22
 
 
23
 
      We recommend implementing a lightweight locking mechanism.
24
 
      Teach the server to track and enforce exclusive write locks.
25
 
      Provide means for repository administrators to manipulate locks
26
 
      and enforce locking policies.  Provide a series of client
27
 
      commands for creating, removing, breaking, and stealing locks.
28
 
      Lastly, create a new property to communicate that a path must be
29
 
      locked before committing.
30
 
 
31
 
      Note that Subversion is still an inherently concurrent system.
32
 
      The ability to lock paths is optional, and can even be prevented
33
 
      by the repository administrator.
34
 
 
35
 
 
36
 
II. New Client Behaviors
37
 
 
38
 
   A. Overview
39
 
 
40
 
      1. Definition of "lock"
41
 
 
42
 
         A lock grants one user the exclusive right to change a
43
 
         certain file from a specific working copy.
44
 
 
45
 
      2. Lock restrictions
46
 
 
47
 
         If a file is locked, the owner of the lock has the exclusive
48
 
         right to change the file's text and properties, to delete the
49
 
         file, and to move the file.
50
 
 
51
 
         The restriction on moving or deleting a locked file is a
52
 
         restriction on changing its full path name in any way,
53
 
         including by moving or renaming or deleting any of its
54
 
         parent directories.
55
 
 
56
 
         (A locked file can still be read and copied, and any copy of it
57
 
         will not automatically be locked.)
58
 
 
59
 
   B. Client requirements for locking
60
 
 
61
 
      1. Enforcement system
62
 
 
63
 
         It must be possible to declare that certain files absolutely
64
 
         require locks before committing.
65
 
 
66
 
      2. Communication system
67
 
 
68
 
         There must be a system in place that tells users when locking
69
 
         is necessary;  ideally, it would prevent a user from
70
 
         beginning work in the first place.  If a lock already exists,
71
 
         a user should be able to see who created it, when, and why.
72
 
 
73
 
   C. Lock manipulation via client
74
 
 
75
 
      1. Lock Representations in the Working Copy
76
 
 
77
 
         In order to associate a lock with a particular working copy,
78
 
         the working copy must store some representation of the lock,
79
 
         and occasionally synchronize this with the repository's
80
 
         master list of locks.
81
 
 
82
 
         Because locks can be broken or stolen, it is possible for a
83
 
         working copy's lock representation to become "defunct".  A
84
 
         defunct lock cannot be used or released--it is useless and is
85
 
         cleaned up when the client next synchronizes with the server.
86
 
 
87
 
      2. Actions
88
 
 
89
 
         This section defines specific terminology to describe the
90
 
         kind of lock-related actions that a Subversion client can
91
 
         perform.
92
 
 
93
 
         a. Creating a lock
94
 
 
95
 
            To lock a file:
96
 
 
97
 
               - A user must be authenticated to the server
98
 
               - The file must not already be locked.  
99
 
 
100
 
            Upon successfully locking a file, the working copy retains
101
 
            a representation of the lock.
102
 
 
103
 
         b. Using a lock
104
 
 
105
 
            To make use of a lock, two forms of authentication must be
106
 
            provided to the server:
107
 
 
108
 
               - The authenticated username that owns the lock
109
 
               - A non-defunct lock representation
110
 
 
111
 
            If either of these forms of authentication are missing or
112
 
            incorrect, the lock cannot be used.
113
 
 
114
 
            1. Using a lock to Commit
115
 
 
116
 
               Upon successful commit, a locked file is released by
117
 
               default.  The Subversion client provides an option to
118
 
               retain the lock after commit.
119
 
 
120
 
            2. Releasing a lock
121
 
 
122
 
               After successful release, the representation of the lock
123
 
               is removed from both the working copy and the server.
124
 
 
125
 
         c. Breaking a lock
126
 
 
127
 
            "Breaking" a lock is a means of releasing a lock when:
128
 
 
129
 
               - The authenticated username is not the same as the
130
 
                 lock owner, or
131
 
               - The working-copy lock representation is unavailable.
132
 
 
133
 
            (e.g. Harry locks file foo and is suddenly laid off.
134
 
            Sally decides to clean up his mess and breaks the lock on
135
 
            foo, without using Harry's username or lock
136
 
            representation.)
137
 
 
138
 
         d. Stealing a lock
139
 
 
140
 
            "Stealing" a lock is a means of creating a lock when:
141
 
 
142
 
               - The file is locked by you, but you don't have a
143
 
                 representation of the lock in your current working
144
 
                 copy, or
145
 
               - The file is locked by someone else.
146
 
 
147
 
            In order to steal a lock, a user must be authenticated to
148
 
            the server.
149
 
 
150
 
            (e.g. Harry locks file foo and goes on vacation.  Sally
151
 
            needs to make changes to foo and obtains a lock on foo by
152
 
            stealing Harry's lock, without using Harry's username or
153
 
            lock representation.)
154
 
 
155
 
         e. Discovering/examining locks
156
 
         
157
 
            The Subversion client provides interfaces to answer the
158
 
            following questions:
159
 
 
160
 
            - Ask working copy to display all lock representations
161
 
 
162
 
            - Examine a particular lock representation
163
 
 
164
 
            - Ask server to list all locks underneath a given path,
165
 
              optionally displaying all attributes of the locks
166
 
              (Possibly able to restrict this query to a single user)
167
 
 
168
 
            - Ask server whether a given file is locked
169
 
 
170
 
 
171
 
III. New Server Behaviors
172
 
 
173
 
   A. Overview
174
 
 
175
 
      1. Definition of a lock
176
 
 
177
 
         As noted in section II.A.1, a lock grants one user the
178
 
         exclusive right to change a certain file from a specific
179
 
         working copy.  
180
 
 
181
 
      2. Attributes of a lock
182
 
 
183
 
         A lock is an immutable data object.  It must contain: a
184
 
         unique identifier, the path being locked, the username that
185
 
         owns the lock, and a creation timestamp.  A lock comment is
186
 
         optional.
187
 
 
188
 
      3. Lock Restrictions
189
 
 
190
 
         See II.A.2 for details.  The server will enforce these
191
 
         behaviors.
192
 
 
193
 
   B. Tracking locks
194
 
 
195
 
      The Subversion server holds the master list of all locks for a
196
 
      repository.  It responds to client requests to create, release,
197
 
      break and steal locks.  
198
 
 
199
 
      When a client asks about a lock, the server reports whether the
200
 
      lock is valid or is defunct (i.e. the server no longer has a
201
 
      lock corresponding to the lock representation in question).
202
 
      When a client creates or steals a lock, the server returns a
203
 
      lock representation. 
204
 
 
205
 
   C. Enforcement
206
 
 
207
 
      During a commit, the server checks for locks the same way that
208
 
      it checks for out-of-dateness.  
209
 
 
210
 
      As each changed path arrives, the server checks to see if the
211
 
      path is locked.  If the path is locked, the server makes certain
212
 
      that the correct username and lock representation have been
213
 
      presented by the client.  If not, the entire commit is rejected
214
 
      immediately.
215
 
 
216
 
      In addition, the server re-checks and enforces locks during
217
 
      commit finalization.
218
 
 
219
 
   D. Configurable Mechanisms
220
 
   
221
 
      The server provides mechanisms to enable diverse administrative
222
 
      locking policies, including:
223
 
 
224
 
      1. Allow or disallow creating, breaking, and stealing of locks
225
 
         based on specific criteria (e.g. username, path, etc.)
226
 
 
227
 
      2. Perform tasks after creating, breaking, and stealing a lock
228
 
         (e.g. sending email, collecting stats, etc.)
229
 
 
230
 
   E. Lock manipulation with svnadmin
231
 
 
232
 
      1. Discovering locks
233
 
 
234
 
         svnadmin provides interfaces to answer the following
235
 
         questions:
236
 
 
237
 
         - List all locks in a repository underneath a given path
238
 
           (Possibly able to restrict this query to a single user)
239
 
 
240
 
         - Ask whether a given repository file is locked
241
 
 
242
 
      2. Unconditional release of locks
243
 
 
244
 
         svnadmin provides an interface to unconditionally release a
245
 
         specific lock.
246