Wednesday, 30 January 2008

AccuRev - another story how to screw UI

A few days ago I found an article about new AccuRev plugin for VS 2005 and by the way I decided to describe the pain I've experienced using AccuRev. In general I love AccuRev or to be more precise I love its back-end. The whole AccuRev architecture is based on streams that are structured as a tree. Every stream except the root has a single parent stream and 0 or many child streams. Click at the image to see more details.

A child stream inherits content from its parent which makes branching/merging a non-issue. Let's say you have the production version of a product in the main stream and all the new features are being implemented as child streams. Whenever there is a code change (bug fix, small improvement) in the main stream all child streams get it automatically. Developers don't even have to think explicitly about merging. They just update their workspace, get changes from the parent stream and resolve simple conflicts and that's it. I said simple conflicts because the more often you merge the less time you spend on it. Additionally, in most cases all inherited changes are incorporated seamlessly because AccuRev does a really good job at merging.
If you need to include an external dependency (which is exposed as a stream as well) you just need to create a link between your stream and the stream where the dependency is. This means that if you have a data access component then the New Feature 1 stream can consume version 1.0 of it whereas the New Feature 2 stream can upgrade to version 2.0 in complete isolation. As you can see AccuRev is powerful and there is no doubt about that.
The only problem is that all described features are exposed to the end user by a crappy UI. The UI has been written in the way that makes it useless in so many cases that it's not even funny. I'm going to show a few examples how you must not write UI. All of them made the AccuRev adoption in my company very hard. Fortunately we have a brilliant build team which basically created a new web based UI that sits on top of AccuRev and hides many of the "innovative" ideas you will see.
The order of the list does not matter because different people hate passionately different AccuRev UI "features". The list is based on version 4.5.4 of AccuRev.

  1. UI is based on Eclipse which is written in Java. I have nothing against Java but I haven't seen a really good UI written in that language. The AccuRev UI is not as responsive as the average native Windows app. From time to time it starts rendering everything in gray. Click at the image to see more details.
  2. AccuRev comes with its own vocabulary that describes the source code management. 
    Common term AccuRev term
    update update & populate
    check in/commit promote
    delete defunct
    move cut & paste
    conflict overlap
  3. In order to make sure that you've got all recent changes you need to update and populate your workspace. Of course there is no single button that does both of them in one go. What is more both actions are launched in two completely different ways. The update button is the best hidden button I've ever seen. Nearly every single developer that starts using AccuRev can not find it. Note that the update action is accessible neither from the main menu nor the context menu.
  4. Whenever AccuRev can not update your workspace because there is something wrong with it you get a cryptic error message. In most cases it is the same error message. Click at the image to see more details.
  5. When someone promotes changes to the parent stream then all children get it by inheritance. From time to time the changes introduce conflicts that need to be resolved. The problem is that in order to find them you need to look for them using two different searches - overlap and deep overlap. I know why there are two different types of them but I don't get why this is so explicitly exposed to the end user.
  6. As I said before you can include other streams into you stream. The problem is that the window that lists all available streams is just a list view without any way of filtering items in the current view. I can spend 15 minutes trying to find the stream I'm interested in. Click at the image to see more details.
  7. Whenever you edit a text box the Ctrl-Z shortcut does not work.
  8. Let's say you are done with your task and you want to promote all your changes. In order to do this you need to remember to execute 3 different searches(external, modified, pending) to find all your changes. Again there is no single search that can do this for you. Needless to say that you can not define your own searches. 
  9. There are always some files that are part of your workspace but you never want to add them to the repository. The obj and bin folders are a good example. Unfortunately the AccuRev UI does not let you exclude neither files nor folders. Instead you need to create an environment variable where you specify all patterns for files and folders that AccuRev should ignore. What a user friendly solution. Even free TortoiseSvn has that feature built in.
  10. When you want to move a file that is already in the repository you need to right click on it, choose cut, navigate to the new location, right click and choose paste.  Why is there no explicit move command?
  11. Until recently the AccuRev integration with Visual Studio has been very poor and only recently AccuRev has released a plugin that more or less works with VS 2005(what about 2008?). My biggest problem with AccuRev plugin is the fact that from time to time when I compile my solution it does something in the background that causes the compilation process to freeze for a few seconds. From my perspective this is unacceptable behaviour. I don't mind if the plugin does its housekeeping when the IDE is idle but it must not interfere in the compilation process.
I see the current AccuRev UI as a low level API that should be completely hidden and should be used only to build a higher level abstraction that is simple and user friendly. Our build guys should sell their system back to AccuRev because it fixes many of the current AccuRev UI shortcomings. At the end I want to emphasize that as I said before the AccuRev back-end is great but its front-end makes you think that the whole product is half-baked to say the least.
Since recently a happy AccuRev user :).


  1. Agreed. The AccuRev backend rocks. The AccuRev UI blows chunks.

  2. Dear Pawel,

    Thank you for your kind words about the AccuRev approach to SCM (ie. its back end). We hope that with AccuRev 4.6 and future versions you will become fonder of the GUI as well. We take customer feedback seriously and wish to share some information on some of the points that you brought up as well as information about where we are headed.

    The “gray screen” is a known Java problem called the “Gray Rect issue”. Sun has fixed it in Java 6. As of AccuRev 4.6, the default JRE is Java 6.

    You shouldn’t need to run both update and populate, an update alone should do it. If you find you need both for some reason, please contact support, they will help to troubleshoot the root cause.

    There is an update menu item on the File menu, but we certainly apologize for hiding the Update button so well. We’re not sure why that hasn’t been pointed out before, but we will certainly see what we can do.

    You will be happy to know that in AccuRev 4.6 we have made it so that Update no longer complains about modified files unless they contain conflicts. If you like automatically merging conflicting files, then you can also run “Update and auto merge” which will automatically merge all files that can be automatically merged.

    We currently make overlap and deep overlap separate searches for performance reasons. Simplifying this is in our product backlog.

    We agree that searching for streams in some of the dialogs can be frustrating. We are actively working on providing more options. If you are not already aware of it, one existing option that you may find helpful is to go to the StreamBrowser and use the zoom in feature to zoom down to just the sub-tree that you usually use. Then, only that subset will be listed in stream dialogs.

    When doing a promote, you can just go to the pending and external search. Modified is a sub-set of pending. We agree that this could be simpler and have started moving towards implementing a simpler solution starting with the Eclipse plug-in. The Eclipse plug-in for AccuRev provides support for the Synchronize view. In this case the ‘Outgoing’ tab in the Synchronize view displays a combination of external and pending files. You can expect to see this move to other UIs over time.

    Improvements to ACCUREV_IGNORE_ELEMS via the GUI and updates to the Visual Studio integration are also high on our product backlog. I think you will be pleasantly surprised with the changes in 4.6. We appreciate your detailed feedback and look forward to providing additional updates.

  3. Hi Damon,

    Thanks for your update and please find below a few more details about my AccuRev experience.

    1. Java
    Actually I'm using Java 6 as that's the version recommend by our build team. It didn't help.
    2. Update and Populate
    When you delete files from your workspace then from time to time Update does not download them and then you need to use Populate.
    I just don't get why there are two commands.
    3. Update
    I would never expect to find it under File menu :).

    I'm happy that you are listening to your customers and I'm looking forward to AccuRev 4.6. I hope it will make my life much easier.

  4. 1. (for bullet #3) Do you need to "update and populate"!!?? I don't I just "update" my workspace whenever needed. If you do there's something wrong on how you use the tool.

    2. (for bullet #8) You only need to look for "pending" and "external", and that's because "pending" = "kept" + "modified", no need to go looking at "modified" again, duh!

    3. (for bullet #9) Totally agree, the current mechanism for ignoring/un-ignoring externals is cumbersome (even with the v4.6 improvements), Damon for your attention.

    All in all Accurev is a superb tool, with a lot of strengths, more attention to users needs and it will be even better.

  5. Hi Mo3e,

    Ad1. There were cases where I had to use both. The fact that you haven't experienced that behaviour doesn't prove it's impossible.
    Ad2. Again, there were cases where "pending" didn't show "modified" files. Very rarely but still.


  6. I don't think that the problem with AccuRev UI showing in gray rect is related to the gray rect fix in Java 6. Chet Haase's blog entry ( ) states clearly it was Swing's double buffering problem, not generic Java problem. So, AccuRev UI being SWT couldn't benefit from the fix.

  7. Actually, the main AccuRev UI is in Swing. Only the Eclipse plugin uses SWT and to my knowledge the Eclipse plug-in doesn't have this problem. I'm not sure why Pawel doesn't see an improvement with JRE 6, most people have. It will require some additional investigation. The good news for Pawel though is that we are focusing on adding all main GUI functionality to the Eclipse and Visual Studio plug-ins which don't have this issue.

  8. There is an important difference between 'update' and 'populate' and understanding this is fundamental to AccuRev's timesafe nature. When you are working in a private workspace, the commands you execute (e.g. revert, diff) are relative to the last time you updated the workspace. So regarding populate, if you accidentally (or intentionally!) physically delete a file from your local disk, you want to retrieve it from the AccuRev server. The important distinction here is that you want the version your workspace last knew of... NOT the version that is newer in the stream hierarchy above you. The 'update' command -ONLY- is only responsible for scanning your parent stream hierarchy and looking for new files to bring down on disk. If there are no newer versions of files, you get nothing. Thus, if you accidentally delete a file, then perform an update, it's likely that you will NOT get that file on disk... simply because no newer version was available at the time.

    Thus, the short answer is that populate is a 'time safe' update.

    HTH! _ dave

  9. Dave,
    I see your point but I still think that this feature introduces complexity/confusion with no additional value. It's like UAC in Vista. Sure, it's safe but it's extremely annoying. I don't really see a valid use case for that feature. If I delete a file that
    I haven't changed then why not to get the most fresh copy of it? Even if I've changed a file and I delete it then
    my changes are gone anyway and again I have nothing against getting the latests version of that file. I like AccuRev
    because I merge changes all the time without even knowing that I'm doing this. I've used Subversion for years and I've had no problems with its "single" update command. Just keep it simple :).

  10. Pawel -

    There is a slight learning curve to understanding AccuRev private workspaces -- but in the end, the timesafe nature of the configuration is REALLY what you want and need. Like everyone else, I also used the traditional update (ala CVS and SVN).... the problem is that if you accidentally delete a file on disk and update to the most recent version, you take on the risk of introducing more changes than your ready for -- more specifically, you can get changes in your single, updated file that the rest of your entire configuration are not compatible with. If you're working with trivial languages with no file includes / uses / imports then maybe the risk is low because your files/features may be mutually exclusive. But if you're using a bona-fide programming language where the web of compile-time and run-time dependencies tends to be much greater -- the risk will be greater.

    I think you'll also find that the benefits of private workspaces increases with the number of contributors on the project. The more people you have, the higher probability of conflict -- and this is where timesafety truly becomes your best friend.

    HTH _ dave

  11. Hmm, very informative post. Thanks.

  12. I guess another frustrating thing is not only do you have to update and populate to ensure your workspace is completely up to date, you also need to be sure to do this in the correct order.

    E.g. If you have deleted a file in your workspace, and you update and then populate you will be left with a (backed)(stale) version of this file.

    Naturally, you would assume that an update followed by a populate would ensure everything is current but in Accurev this isn't the case.

    I have also come across issues where I am unable to add files to the depot because they are 'excluded. When I try to change my include/exclude rules, I do not have the option of including this new directory. Even making all the folders at the same level 'incldo' I cannot add new files. The UI definitely does not work in a natural way that a user would expect. I also find that the generic error messages that appear are useless.

  13. I'm new to accurev, Can i update a single file rather than for whole workspace?

  14. Hi Vivek,
    As far as I know you can update entire workspace only.


  15. Automatic flowing of code to downstream is one feature I like very much in Accurev. But like said, the strength is in it's weakest link. For Accurev, the weak link is its UI.

    One specific issue I faced is, say you work for a release and you get a production issue to work on. You have left with no choice other than creating another branch from prod stream and switch your workspace. You cant remain in same worksapce and do a branch switch, like in Git.

    Another issue is, you do not get to see what files are getting update with the update is done. the Log it generates seems to be too much of info and doesnt always contains information I want.

  16. Hi Pawel,

    Could you please explain overlap and deep overlap? An example will help.