subversion-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Mark Mielke <m...@mark.mielke.cc>
Subject Re: format of svn:author
Date Wed, 04 Jan 2012 19:20:54 GMT
This is great, Julian. It is pretty good for a draft. I'll get back to 
you with the detailed answers tonight - just wanted to give my thumbs up.

I'm ok with a simpler solution that just sets the attributes on commit, 
but what you have described looks like a good step up from the minimum 
and solves additional requirements which fall under "would be nice" for 
me... Thanks!


On 01/04/2012 01:42 PM, Julian Foad wrote:
> Hi Mark.
>
> I think I can see to some extent what you are getting at, but not clearly.  We all need
a common frame of reference for understanding why and how some sort of extended author information
could be useful.  To help us get there, I put
> together the following tentative proposal to act as a basis for
> discussion.  Perhaps we can now move on to talking about specific requirements and designs.
 What parts of it are aligned with your thinking and what
> have I got wrong or missed out?
>
> Please note that this draft is purely an invention of my mind and I do not expect it
to be an accurate reflection of your or anyone else's requirements.
>
>
> A PROPOSAL FOR EXTENDED AUTHOR IDENTIFICATION
>
> USE CASES
>
> 1.[This one I am aware of.]
>
>    A large company has authenticated user ids that are numeric.  That means the "log"
and "blame" information shown by most Subversion clients is not easy to understand.  Therefore
they use a (post-commit?) hook to change
> the svn:author property to a more friendly string, which (mostly) solves the display
issue.  However, it causes other problems.  [What problems?]
>
>
> 2. [This one is a guess.]
>
>    The leader of a small development team sharing a Subversion repository with other
teams wants to set up a build slave that will send an email to the users who committed revisions
leading to a build failure.  The machine can see the Subversion user id but how can it get
the user's email address?  The team leader could ask the repository administrator to add a
post-commit hook that adds an email address to a revision property after every commit, but
that
>
>      * requires involving the server admin;
>      * won't get updated when the user changes their email address;
>      * won't work for testing old revisions that were already committed before that time;
>      * won't work if the build slave software needs to read a list of all user id->email
mappings at once.
>
>
> 3. [This one is a guess.]
>
>    An administrator wants to integrate Subversion with an issue tracker.  Users have
different user ids on the two tools.  The admin wants to configure the tracker so that it
automatically annotates an already committed Subversion revision with some status information.
 How can the tracker know with what user id to contact the Subversion server?
>
> The rest of the proposal addresses UC1 and part of UC2 but not UC3.  (UC3 looks like
it needs some totally separate solution, outside of Subversion.)
>
>
>
> REQUIREMENTS
>
>    A Subversion client (of any kind so designed) shall be able to read extended information
about the author of a revision.  This information shall consist of a (possibly empty) set
of fields.  The set of possible extended author fields shallinclude at least:
>
>      * authenticated user id
>
>      * display name
>      * email address
>
>    It shall be possible to add other fields on the server side (by software upgrade and/or
by configuration), and for a client (of any kind so designed) to discover and read these fields
without any software upgrade on the client side.
>    The svn:author property shall continue to exist.  When not using the extended author
fields, the svn:author property must continue to operate as before.  When using the extended
author fields, the design may restrict the use of the svn:author field.  Example: the design
could require that if extended author fields are to be usable then the svn:author field always
holds the authenticated user id and must always be present and non-empty.
>
>
>    A client shall access the extended author fields through the Subversion server, through
the existing client-server protocols, possibly with protocol extensions.  Any protocol extensions
shall be backward compatible in that an old server with a new client or an old client with
a new server shall (without user intervention) use the old 'svn:author' property.
>
>
>    The fields that are available from a particular server or repository are determined
by the administrator.  For any particular committed revision, the server may provide any or
all or none of the extended author fields.  A client cannot rely on any particular field being
available except to the extent that the administrator gives such an assurance.  Example: if
the client requests the authenticated user id and email address for a revision whose author
has no email address recorded,the server shall provide the authenticated user id but no email
address.  If the server is temporarily unable to look up any information about a user, the
server should respond with no extended author fieldsinstead of waiting.
>
>
>    The extended author fields are dynamic in the sense that the server need not always
return the same values for the same committed revision.  For example,a client might repeat
exactly the same request for information about revision 1234 twice in quick succession, and
the server might provide the email address as "a@b.c" the first time and "dd@ee.ff" the second
time.  Even the "authenticated user id" field could change.
>
>
> DESIGN
>
>    The extended author fields are delivered through revision properties.  The values
are UTF-8 text.  These revision properties are readable but not writable by clients.
>
>    Three property names are initially designated  as "well known":
>
>      * prop name: "svn:author:authn-id"
>        purpose: authenticated user id
>        format: as used by Subversion's authentication (the default
>          value of svn:author)
>
>      * prop name: "svn:author:display-name"
>        purpose: display name
>        format: a single line (no line breaks), e.g. person's full
>          name or shortened name or nickname
>
>      * prop name: "svn:author:email"
>        purpose: email address
>        format: [TO BE SPECIFIED HERE]
>
>
>    Other property names in this name space beginning with "svn:author:" can be designated
as "well known" in the future, by an official announcement from the Subversion project.
>
>    An administrator can configure other extended author fields to use property names
that are not in the "svn:" name space.  Example: an administrator could configure the property
name "author:pgp-sig" to hold the author's PGP signature.
>
>
>
> SERVER DESIGN
>    Any time the server is about to send a set of revision properties to
> the client, the server looks up the extended author fields and adds
> corresponding properties to the set of revision properties that it
> reports to the client.  These property values override any values The server looks up
the extended author fieldsthrough some mechanism not defined here,using the value of the"svn:author"
property as a key.  The server may cache the results, provided that there is a way for the
administrator to make the server use updated information.
>
>
>    If the client attempts to set any revision property in the "svn:author:" name space,
the server shall report an error to the client.  This applies even if the property value matches
the value that was last read from the server or is currently known to the server, and even
if the
> specific property name is not known to the server.  If the client attempts to set any
revision property that is not in the "svn:author:" name space but might be configured as an
extended author field, the server records that revision property in the normal way.  If a
revision property (of any name) has a stored value and the extended author field look-up also
provides a value for the same property name, the latter takes priority.
>
>
>    The extended author fields [are | are not] available to the following hook scripts:
pre-commit, ...
>
>
> CLIENT DESIGN
>
>    Just an example.  The "svn log" and "svn blame" commands could request the revision
property named "svn:author:display-name", and if that is returned then use it instead of "svn:author",
otherwise use the value of "svn:author".  Further, a client-side configuration option could
specify which property name should be used for these display purposes, so for example some
users in a particular team could choose to have the "author:nickname" revision property displayed
instead of "svn:author:display-name".
>
>
>
> FURTHER SCOPE
>
>    Does a client need to be able to look up the information in other ways, such as starting
from svn:author rather than a revision number, or starting from an extended author field?
>
>
> - Julian


-- 
Mark Mielke<mark@mielke.cc>


Mime
View raw message