Apache Software Foundation
[S] Subversion

[You can also view the single-page version of this document.]

Bugs / Issues

Subversion isn't perfect software. It contains bugs, lacks features, and has room for improvement like any other piece of software. Like most software projects, the Subversion project makes use of an issue tracking tool to manage known outstanding issues with the software. But perhaps unlike most software projects, we try to keep our issue tracker relatively free of debris. It's not that we don't want to hear about Subversion's problems — after all, we can't fix what we don't know is broken. It's just that we've found a mismanaged issue tracker to be more of a hindrance than a help.

This mail pretty much says it all (except that nowadays you should post to the users@ list before posting to the dev@ list):

   From: Karl Fogel <kfogel@collab.net>
   Subject: Please ask on the list before filing a new issue.
   To: dev@subversion.tigris.org
   Date: Tue, 30 Jul 2002 10:51:24 (CDT)
   
   Folks, we're getting tons of new issues, which is a Good Thing in
   general, but some of them don't really belong in the issue tracker.
   They're things that would be better solved by a quick conversation
   here on the dev list.  Compilation problems, behavior questions,
   feature ideas that have been discussed before, that sort of thing.
   
   *Please* be more conservative about filing issues.  The issues
   database is physically much more cumbersome than email.  It wastes
   people's time to have conversations in the issues database that should
   be had in email.  (This is not a libel against the issue tracker, it's
   just a result of the fact that the issues database is for permanent
   storage and flow annotation, not for real-time conversation.)
   
   If you encounter a situation where Subversion is clearly behaving
   wrongly, or behaving opposite to what the documentation says, then
   it's okay to file the issue right away (after searching to make sure
   it isn't already filed, of course!).  But if you're
   
      a) Requesting a new feature, or
      b) Having build problems, or
      c) Not sure what the behavior should be, or
      d) Disagreeing with current intended behavior, or
      e) Not TOTALLY sure that others would agree this is a bug, or
      f) For any reason at all not sure this should be filed,
   
   ...then please post to the dev list first.  You'll get a faster
   response, and others won't be forced to use the issues database to
   have the initial real-time conversations.
   
   Nothing is lost this way.  If we eventually conclude that it should be
   in the issue tracker, then we can still file it later, after the
   description and reproduction recipe have been honed on the dev list.
   
   Thank you,
   -Karl

The following are the policies that we ask folks to abide by when reporting problems or requested enhancements to Subversion.

How to report a bug

First, make sure it's a bug. If Subversion does not behave the way you expect, look in the documentation and mailing list archives for evidence that it should behave the way you expect. Of course, if it's a common-sense thing, like Subversion just destroyed your data and caused smoke to pour out of your monitor, then you can trust your judgement. But if you're not sure, go ahead and ask on the users mailing list first, users@subversion.apache.org, or ask in IRC, irc.freenode.net, channel #svn.

You should also search in the bug tracker to see if anyone has already reported this bug.

Once you've established that it's a bug, and that we don't know about it already, the most important thing you can do is come up with a simple description and reproduction recipe. For example, if the bug, as you initially found it, involves five files over ten commits, try to make it happen with just one file and one commit. The simpler the reproduction recipe, the more likely a developer is to successfully reproduce the bug and fix it.

When you write up the reproduction recipe, don't just write a prose description of what you did to make the bug happen. Instead, give a literal transcript of the exact series of commands you ran, and their output. Use cut-and-paste to do this. If there are files involved, be sure to include the names of the files, and even their content if you think it might be relevant. The very best thing is to package your reproduction recipe as a script; that helps us a lot. Here's an example of such a script: repro-template.sh for Unix-like systems and the Bourne shell, or repro-template.bat for Windows shell (contributed by Paolo Compieta); we'd welcome the contribution of a similar template script for other systems.

Quick sanity check: you *are* running the most recent version of Subversion, right? :-) Possibly the bug has already been fixed; you should test your reproduction recipe against the most recent Subversion development tree.

In addition to the reproduction recipe, we'll also need a complete description of the environment in which you reproduced the bug. That means:

  • Your operating system
  • The release and/or revision of Subversion
  • The compiler and configuration options you built Subversion with
  • Any private modifications you made to your Subversion
  • The version of Berkeley DB you're running Subversion with, if any
  • Anything else that could possibly be relevant. Err on the side of too much information, rather than too little.

Once you have all this, you're ready to write the report. Start out with a clear description of what the bug is. That is, say how you expected Subversion to behave, and contrast that with how it actually behaved. While the bug may seem obvious to you, it may not be so obvious to someone else, so it's best to avoid a guessing game. Follow that with the environment description, and the reproduction recipe. If you also want to include speculation as to the cause, and even a patch to fix the bug, that's great — see the patch submission guidelines.

Post all of this information to dev@subversion.apache.org, or if you have already been there and been asked to file an issue, then go to the Issue Tracker and follow the instructions there.

Thanks. We know it's a lot of work to file an effective bug report, but a good report can save hours of a developer's time, and make the bug much more likely to get fixed.

Where to report a bug

Milestone management

Issue tracker milestones are an important aspect of how the Subversion developers organize their efforts and communicate with each other and with the Subversion user base. With the exception of some milestones used primarily when doing high-level issue triage, the project's issue tracker milestones tend to be named to reflect release version numbers and variations thereof. Milestones are used for slightly different purposes depending on the state of the issue, so it's important to understand those distinctions.

Milestones for open issues

For open issues (those whose status is UNCONFIRMED, NEW, STARTED or REOPENED), the milestone indicates the Subversion release for which the developers are targeting the resolution of that issue. In the general case, we use milestones of the form MINORVERSION-consider to indicate that the resolution of an issue is being considered as something we'd like to release in MINORVERSION.0. For example, a feature we think we can and should add to Subversion 1.9.0 will get a 1.9-consider milestone. For obvious reasons, the accuracy of these release targets gets increasingly worse the farther into the future you look and, as such, users are encouraged to not treat them as binding promises from the developer community.

At any given time, there is work toward "the next big release" happening in the community. As that release begins to take shape, the developers will get a better feel for which issues are "must-haves" for the release (also known as "release blockers"), which ones are "nice-to-haves", and which ones should be deferred to a future release altogether. Issue milestones are the mechanism used to carry the results of those decisions. An issue that is deemed to be a release blocker will be moved from the MINORVERSION-consider milestone to the MINORVERSION.0 milestone; "nice-to-haves" will be left with the MINORVERSION-consider milestone; and issues deferred from the release will be re-milestoned either with ANOTHERMINORVERSION-consider or unscheduled, depending on whether we have a clear guess as to when the issue will be addressed.

Continuing the previous example, as development on Subversion 1.9.0-to-be progresses, developers will be evaluating that feature we planned for the release. If we believe that Subversion 1.9 should not be released without that feature, we'll change its milestone from 1.9-consider to 1.9.0; if we hope to release with that feature but don't want to commit to it, we'll leave the milestone as 1.9-consider; and if we know good and well we aren't going to get around to implementing the feature in the 1.9.x release series, we'll re-milestone the issue to something else (1.10-consider, perhaps).

The accuracy of the MINORVERSION.0 milestone is very important, as developers tend to use those issues to focus their efforts in the final days of a major release cycle.

Milestones for fixed issues

For fixed issues (those whose status is RESOLVED and the resolution is FIXED), the issue milestone takes on a new utility: tracking the Subvesion release version which first carries the resolution of that issue. Regardless of the targeted release version for a given issue, once it is resolved its milestone should reflect the exact version number of the release which will first carry that resolution.

Milestones for other closed issues

For other closed issues (those which aren't "open" and weren't really "fixed"), the issue milestone tends to mean pretty much nothing. There's little point in trying to maintain that tracker field when the issue itself is being effectively ignored because it's a duplicate, or because it's an invalid or inaccurate report.

Transitioning between states

Care must be taken when transitioning an issue between these states. An open issue that's been resolved needs to have its milestone adjusted to reflect the Subversion release which will first reflect that change. A resolved issue that gets backported to a previous release stream needs to have its milestone adjusted to point that previous release's version number. Finally, a resolved issue that gets REOPENED needs to have its milestone reevaluated in terms of whether the issue is a release blocker (MINORVERSION.0) or not (MINORVERSION-consider). In such situations, it can be helpful to consult the issue's change history to see what milestone was used before the issue was resolved as fixed.

Issue triage

When an issue is filed, it goes into the special milestone "---", meaning unmilestoned. This is a holding area that issues live in until someone gets a chance to look at them and decide what to do.

The unmilestoned issues are listed first when you sort by milestone, and issue triage is the process of trawling through all the open issues (starting with the unmilestoned ones), determining which are important enough to be fixed now, which can wait until another release, which are duplicates of existing issues, which have been resolved already, etc. For each issue that will remain open, it also means making sure that the various fields are set appropriately: type, subcomponent, platform, OS, version, keywords (if any), and so on.

Here's an overview of the process (in this example, 1.5 is the next release, so urgent issues would go there):

    for i in issues_marked_as("---"):
      if issue_is_a_dup_of_some_other_issue(i):
        close_as_dup(i)
      elif issue_is_invalid(i):
        # A frequent reason for invalidity is that the reporter
        # did not follow the "buddy system" for filing.
        close_as_invalid(i)
      elif issue_already_fixed(i):
        version = fixed_in_release(i)
        move_to_milestone(i, version)
        close_as_fixed(i)
      elif issue_unreproducible(i):
        close_as_worksforme(i)
      elif issue_is_real_but_we_won't_fix_it(i):
        close_as_wontfix(i)
      elif issue_is_closeable_for_some_other_reason(i):
        close_as_it_for_that_reason(i)

      # Else issue should remain open, so DTRT with it...

      # Set priority, platform, subcomponent, etc, as needed.
      adjust_all_fields_that_need_adjustment(i)

      # Figure out where to put it.
      if issue_is_a_lovely_fantasy(i):
        move_to_milestone(i, "blue-sky")
      if issue_is_not_important_enough_to_block_any_particular_release(i):
        move_to_milestone(i, "nonblocking")
      elif issue_resolution_would_require_incompatible_changes(i):
        move_to_milestone(i, "2.0-consider")
      elif issue_hurts_people_somewhat(i):
        move_to_milestone(i, "1.6-consider")  # or whatever
      elif issue_hurts_people_a_lot(i):
        move_to_milestone(i, "1.5-consider")
      elif issue_hurts_and_hurts_and_should_block_the_release(i):
        move_to_milestone(i, "1.5")

How to Handle Security Issues

This document is for information about how Subversion developers respond to security issues. To report an issue, please see the Security reporting instructions.

Subversion's first job is keeping your data safe. To do that, the Subversion development community takes security very seriously. One way we demonstrate this is by not pretending to be cryptography or security experts. Rather than writing a bunch of proprietary security mechanisms for Subversion, we prefer instead to teach Subversion to interoperate with security libraries and protocols provided by those with knowledge of that space. For example, Subversion defers wire encryption to the likes of OpenSSL. It defers authentication and basic authorization to those mechanisms provided by Cyrus SASL or by the Apache HTTP Server and its rich collection of modules. To the degree that we can leverage the knowledge of security experts by using the third-party libraries and APIs they provide, we will continue to do so.

This document describes the steps we take when receiving or finding an issue which may be classified as having security implications, and is meant to suppliment the Apache guidelines to committers for the same.