Bugs / Issues ¶

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.

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 ¶

• If the bug is in Subversion itself, send mail to users@subversion.apache.org. Once it's confirmed as a bug, someone, possibly you, can enter it into the issue tracker. (Or if you're pretty sure about the bug, go ahead and post directly to our development list, dev@subversion.apache.org. But if you're not sure, it's better to post to users@ first; someone there can tell you whether the behavior you encountered is expected or not.)

• If the bug is in the APR library, please report it to both of these mailing lists: dev@apr.apache.org, dev@subversion.apache.org.

• If the bug is in the Neon HTTP library, please report it to: neon@webdav.org, dev@subversion.apache.org.

• If the bug is in the Apache Serf HTTP library, please report it to: dev@serf.apache.org, dev@subversion.apache.org.

• If the bug is in Apache HTTPD 2.x, please report it to both of these mailing lists: dev@httpd.apache.org, dev@subversion.apache.org. The Apache httpd developer mailing list is high-traffic, so your bug report post has the possibility to be overlooked. You may also file a bug report at https://httpd.apache.org/bug_report.html.

• If the bug is in your rug, please give it a hug and keep it snug.

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.

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_it_for_that_reason(i)

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

      # Set priority, environment, component, 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 ¶