Great work on the first draft.
I'm forwarding this to the TortoiseSVN dev list for a wider discussion:
(Also cc'ing Michael from FogCreek Software, since he's also working on
the same task and might have ideas on this)
> ------------------------------------------------------------------------
>
>
> Integration of Subversion with Bug Tracking Tools:
>
> This document is primarily intended for writers of various GUI
> clients for Subversion. Clients such as TortoiseSVN, Subclipse,
> RapidSVN, PySVN and many others.
>
> The goal of this document is to outline a common technique for
> defining and then integrating these GUI clients with third party bug
> tracking software.
>
> It is very common in Software Development for changes to be related
> to a specific bug or issue ID. Users of bug tracking systems would
> like to associate the changes they make in Subversion with a specific
> ID in their bug tracking system. There are already a number of
> people that have integrated these systems with Subversion. They
> typically rely on the end user entering a log message on their
> commits in some kind of a specific format that can be parsed with a
> hook or in some cases just on-the-fly in a web-based presentation of
> the commit info. This option is OK, but it is not very user-friendly
> and it places all of the integration within the bug tracking tool.
> When using a Subversion client, you can see the log message info, but
> there is no way to jump to the bug system.
>
> TortoiseSVN has taken a preliminary step to add direct support for
> bug tracking systems in its GUI. They have an option now to add a
> Bug ID field directly on their commit dialog. Currently, when you do
> a commit, the Bug ID is appended to the commit message in a specific
> format. This saves the user from having to type it themselves and
> possibly making a mistake. I had some conversations with one of the
> developers of TortoiseSVN and they have a desire to add some
> additional functionality. Before they go too far down that path it
> would make sense to take a step back and try to define all of the
> functionality that might be needed, and further to define it in such
> a way that EVERY GUI client out there could eventually implement the
> feature exactly the same. Ultimately, the bug tracking integrators
> are still going to need to write some hook scripts so it would help
> greatly if all of the GUI's did stuff the same way and used the same
> configuration.
>
> I am working on integrating a bug tracking system with Subversion so
> I have already spent a lot of time thinking about the issues. This
> is how I think it ought to work:
>
> Log Messages: I think you always want something added to the log
> message as this will work best for command-line client users. What
For better clarification, you should say "added at the end of each log
message". Just "added" could also mean at the top of a log message or
(god forbid) somewhere in the middle.
> the GUI can do is hide this detail from the user using the technique
> currently employed by TortoiseSVN. Namely, the bug ID would be a
> field on the commit dialog, and the GUI would then append it to the
> end of the commit message that the user enters. The format of the
> message should be configurable to accomodate the proper terminlogy
> used by each system. More on this later.
>
> Validation: I propose that a regular expression can be provided to
> validate the bug ID. If one is not provided, then no validation
> would occur. The bug tracking system could supplement this
> validation with a pre-commit hook if desired.
Good idea. That way users can see an error message 'cause of an invalid
ID _before_ the hook script on the server rejects the commit, i.e.
without any network access.
> Revision Properties: Optionally, the GUI should set a revision
> property with the Bug ID after the commit. If I were going to
> support command line users, I would probably use a post-commit hook
> to extract this from the commit message and then add the revprop on
> the server. However, it would be nice for the GUI to do this
> directly. Issue: 1976 for Subversion exists to allow these to be
> provided directly on the commit command, but until then the svn
> propset --revprop command can be used to set the Revision property.
I guess this should later help to associate a revision with a BUG ID
when e.g. viewing the logs? Maybe you should mention that here too.
One problem with that approach: what happens if the commit itself
succeeds, but then an error occurs while trying to set the revprop? As
long as the Subversion core doesn't support this, those are _two_
separate steps and are therefore not atomic.
> File Properties: I do not think these are appropriate for this
> feature. File properties are inherited, so once one is set, future
> revisions inherit the property, although it can be modified to a
> different value. I just do not think this is what the feature was
> intended for. The primary value in using file properties is that
> most GUI clients already display arbitrary file properties making
> them easy to access. I see know reason, why those clients could not
> be enhanced to pull in the property from the revision property.
File properties have the advantage to be available in the working copy,
i.e. a client can use them without contacting the repository first.
To overcome the versioning of file properties, we could define that once
a property is set with a bug id, further bug id's get _added_ and must
not replace an already existing one. Example:
bug-ID: 1440, 1567
then, when a new issue gets fixed
bug-ID: 1440, 1567, 1833
> Configuration: There is a fair amount of configuration that needs to
> go into all of this. It makes sense for this to be stored in the
> Subversion repository itself. I have done some experimenting, and I
> think the best way to do this is store the configuration as revision
> props on revision 0 within the repository. This would allow all GUI
> clients to pull the configuration from the server and the user would
> only need to define the rules one time. Of course, this places the
> granularity of the rules at the repository level. Personally, I
> think that is fine, but I am open to ideas.
I don't like that idea very much. The problem with this approach is that
a client would have to contact the repository _before_ the actual
commit, i.e. the information stored is needed to show the commit dialog
right. And with slow connections, this would annoy the users. Especially
if they don't use any bugtrackers and the client just contacts the
repository to find out that there is no config data stored.
The config data could be stored in a special file (with a unique name)
inside the repository. This file would be versioned and handled by
subversion like any other file. That way, the config data is present in
the working copy of each user, and the clients doesn't need to contact
the repository to get that config data.
Another advantage is that the config data could be set on a folder
level, not just for the whole repository.
If a file is not wanted, we could also store that config data in folder
properties. We just had to define a unique property name for each config
option. This could then be handled like the svn:ignored property in
Subversion.
The only problem I see with the configfile/file-property approach is
that I can see users asking the same question every day:
"you already have a config file for the repository, why can't we store
the autoprops config in there too?" (replace "autoprops" with
"global-ignores" or any other Subversion config option which is now
stored in the users home dir).
So that feature (repository wide configs) should go into the Subversion
core API - see the Subversion issue 1974 for that. Greg Hudson already
partly rejected the idea, so if that's ever going to happen is questionable.
> Here is what I think needs to be stored in the configuration, I do
> not think the GUI clients need to provide a UI for setting this
> information. They obviously can if they choose to do so.
>
> Property Description ==========
> ======================================================= BugTracking
> true/false - a value of true turns on the general feature. The GUI
> would control the UI around this property.
Can't this be figured out by simply checking if any bugtracking config
is available? If no such config is available, then it's "false".
> BugLabel The label to show in the GUI. This lets the user define
> their own terminology. Default if not specified would be "Bug ID:"
What about different UI languages here? Shouldn't that be translated
too? And if yes, then it shouldn't be stored in the repository.
> BugRegEx Regular expression used to validate the bug ID. Default
> would be no validation.
>
> BugMessage The text to append to the commit message. Default would
> be "\n\nBug ID: $ \n" $ is meant to define a substitution
> placeholder for the Bug ID value. I do not know if $ is the best
> choice or something like %1 or %ID%. Suggestions welcomed.
I'm not sure about that, but isn't the "$" a special char which hasn't
the same bytecode in all different codepages? I think we should stick
here with chars which could be used in an URL. To to be safe when it
comes to non english systems.
> BugSetProp true/false whether to set a revision property with the
> commit. Default is false if not specified.
>
> BugProperty The name of the revision property to store the Bug ID.
> This would be used when setting the property on commit, but it would
> also be used by the GUI to know the revision property to retrieve and
> show in the GUI, if desired. Remember, it is possible this feature
> will be used but the properties will be set with a hook script.
> Default if not specified is "BugID".
This shouldn't be configurable. I think we just should define this value
so that all clients know what to look for.
> BugURL If the GUI shows the BugID associated with a revision,
> this is the URL to link to from the UI. Format would be something
> like this: url://address/%ID%. Where %ID% is the substitution
> format we agree upon.
>
> It would be nice if the user could define a BugProgram or something
> like that which links to another GUI app. However, it seems like the
> bug tracking program could, and should just write and register some
> URL handler. So maybe there would be a URL like:
> bug://localhost/DBName?%ID%
>
> And the local OS would route the URL through a handler that could
> pass it to a GUI??? Just an idea, I think most people use
> browser-based systems anyway.
Since the clients have to know the format of the bug id entered in a log
message, it could parse each log message itself and find out the bug id
itself. Then with the BugURL config option, the client could assemble
the bugtracking URL itself and start the webbrowser with that URL e.g.
from the log dialog.
> This property is likely the main property a user might need to vary
> at a level below the repository. Picture a repository hosting
> multiple projects. Depending on the bug system used, they could have
> different URL's.
> UI:
>
> Commit Process: This has been implicitly covered, but let's go back
> and review. The commit dialog should have a Bug ID field added.
> This would be conditioned on the revprop as well as get the text to
> display from a revprop. Additionally, a validation rule could be
> retrieved from the revprops.
>
> Upon commit, the Bug ID is appended to the commit message using the
> revprop with the message template. This would be mostly invisible to
> the user. Upon browsing a commit, the user would see the new message
> with the Bug ID info added.
>
> Optionally, after or during the commit, a revision property would be
> set which also contains the Bug ID.
>
> I do not know how the various GUI's out there currently handle a
> pre-commit-hook which prevents a commit, but this would be a good
> time to clean that up as it is likely the bug tracking system may add
> additional validation that can reject a commit.
>
> History Browsing: UI which shows history, such as log style history
> should be enhanced to treat the bug ID like a full-fledged citizen,
> as they do the author and date. The BugURL revprop should be used to
> provide a launch point to the Bug system.
I think once we got this worked out, we should send this to the
Subversion mailing list and simply _insist_ that this should be
implemented. If not in the Subversion core, then they should at least
define the standard and document it somewhere on their website so that
all Subversion clients will use the same standards. Otherwise, we might
end up in chaos.
Stefan
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tortoisesvn.tigris.org
For additional commands, e-mail: dev-help@tortoisesvn.tigris.org
Received on Wed Aug 18 08:52:22 2004