Merge lp:~mbp/bzr/doc-old into lp:~bzr/bzr/trunk-old

[Martin Pool]

[Martin Pool (mbp)]

This adds a summary of the threads about bug process, clarifies some of the points about targeting and severity, and moves content from http://bazaar-vcs.org/BugGuidelines (which I should delete when this is merged.)

[Vincent Ladeuil (vila)]

Thanks for all the clarifications.

I don't know if, exceptionally, more people should approve that patch ?

I do anyway.

review: Approve

[Aaron Bentley (abentley)]

It looks good to me. Sensible policy, clearly described.

review: Approve

=== added file 'doc/developers/bug-handling.txt'
--- doc/developers/bug-handling.txt	1970-01-01 00:00:00 +0000
+++ doc/developers/bug-handling.txt	2009-06-16 02:35:24 +0000
@@ -0,0 +1,298 @@
+***********************
+Tracking Bugs in Bazaar
+***********************
+
+This document describes the bug-tracking processes for developing Bazaar
+itself.  Bugs in Bazaar are recorded in Launchpad.
+
+
+See also:
+
+* `Bazaar Developer Documents <index.html>`_.
+
+* `The Bazaar Development Cycle <cycle.html>`_.
+
+* `The Bazaar User Guide <../en/user-guide/index.html>`_ -- for
+  information on integrating Bazaar with other bug trackers.
+
+
+Links
+*****
+
+* `bzr bugs home page <https://bugs.edge.launchpad.net/bzr>`_.
+
+* `Critical bugs <https://bugs.edge.launchpad.net/bzr/+bugs?search=Search&field.importance=Critical&field.status=New&field.status=Incomplete&field.status=Confirmed&field.status=Triaged&field.status=In+Progress&field.status=Fix+Committed>`_.
+
+* `Open bugs by importance <https://bugs.edge.launchpad.net/bzr/+bugs>`_.
+
+* `Open bugs most recently changed first
+  <https://bugs.edge.launchpad.net/bzr/+bugs?field.searchtext=&orderby=-date_last_updated&search=Search&field.status%3Alist=NEW&field.status%3Alist=INCOMPLETE_WITH_RESPONSE&field.status%3Alist=INCOMPLETE_WITHOUT_RESPONSE&field.status%3Alist=CONFIRMED&field.status%3Alist=TRIAGED&field.status%3Alist=INPROGRESS&field.status%3Alist=FIXCOMMITTED&field.assignee=&field.bug_reporter=&field.omit_dupes=on&field.has_patch=&field.has_no_package=>`_.
+
+
+Generalities
+************
+
+Anyone involved with Bazaar is welcome to contribute to managing our bug
+reports.  **Edit boldly**: try to help users out, assess importance or improve
+the bug description or status.  Other people will see the bugs: it's
+better to have 20 of them processed and later change the status of a
+couple than to leave them lie.
+
+When you file a bug as a Bazaar developer or active user, if you feel
+confident in doing so, make an assessment of status and importance at the
+time you file it, rather than leaving it for someone else.  It's more
+efficient to change the importance if someone else feel's it's higher or
+lower, than to have someone else edit all bugs.
+
+It's more useful to actually ship bug fixes than to garden the bug
+database.  It's more useful to take one bug through to a shipped fix than
+to partially investigate ten bugs.  You don't get credit for a bug until
+the fix is shipped in a release.  Users like getting a response to their
+report, but they generally care more about getting bugs fixed.
+
+The aim of investigating bugs before starting concentrated work on them is
+therefore only to: 
+
+* determine if they are critical or high priority (and
+  should displace existing work)
+
+* garden sufficiently to keep the database usable: meaningful summaries,
+  and duplicates removed
+
+It's OK to fix some bugs that just annoy you, even if they're not
+rationally high.
+
+You can use ``--fixes lp:12345678`` when committing to associate the
+commit with a particular bug.
+
+If there are multiple bugs with related fixes, putting "[master]" in the
+title of one of them helps find it
+
+It's often fastest to find bugs just using the regular Google search
+engine, rather than Launchpad's search.
+
+Martin Pitt says:
+
+ | One of the things you should not do often is to start asking
+ | questions/for more debug info and then forget about the bug. It's just
+ | a waste of the reporter's and your time, and will create frustration
+ | on the reporter side. 
+
+
+Priorities
+**********
+
+The suggested priorities for bug work are:
+
+1. Fix critical bugs.
+   
+2. Get existing fixes through review and landed.
+
+3. Fix bugs that are already in progress.
+
+4. Look at bugs already assigned to you, and either start them, or change
+   your mind and unassign them.
+
+5. Take new bugs from the top of the stack.
+
+6. Triage new bugs.
+
+It's not strict and of course there is personal discretion but our work
+should be biased to the top of this hierarchy.
+
+
+Clear Bugs
+**********
+
+Bugs should have clear edges, so that you can make a clear statement about
+whether a bug is fixed or not.  (Sometimes reality is complicated, but aim
+for each bug to be clear.)
+
+Bugs on documentation, performance, or UI are fine as long as they're
+clear bugs.
+
+Examples of good bugs:
+
+* "ValueError in frob_foo when committing changed symlink" - although
+  there may be many possible things that could cause a ValueError there,
+  you should at least know when you've fixed the problem described in this
+  bug.
+
+* "Unclear message about incompatible repositories" - even though the user
+  may not agree the new message is sufficiently clear, at least you know
+  when you've tried to fix it.
+
+Examples of bad bugs:
+
+* "Commit is too slow" - how fast is fast enough to close it?  "Commit
+  reads the working tree twice" is clearer.
+
+
+Bug Status
+**********
+
+New
+    The bug has just been filed and hasn't been examined by a developer
+    yet.
+Incomplete
+    The bug requires more information from the reporter to make progress.
+Confirmed
+    The bug report has been seen by a developer and we agree it's a bug.  
+    You don't have to reproduce the bug to mark it confirmed.  (Generally
+    it's not a good idea for a developer to spend time reproducing the bug
+    until they're going to work on it.)
+Triaged
+    We don't use this status.  If it is set, it means the same as
+    Confirmed.
+In Progress
+    Someone has started working on this.
+Won't Fix
+    The behaviour complained about is intentional and we won't fix it.
+    Needless to say, be thoughtful before using this status, and consider if
+    the user experience can be improved in some other way.
+Invalid
+    The reporter was confused, and this is not actually a bug.
+    Again, be sensitive in explaining this to the user.
+Fix Committed
+    A fix for this bug exists in a branch somewhere.  Ideally the bug will
+    be linked to the branch.
+Fix Released
+    The fix for this bug is now in the bzr trunk.  It's not necessarily
+    true that it's released yet, but it will be in the next release.  The
+    bug target milestone should be set to the release it went into, but
+    don't spend too much time updating this if you don't immediately know.
+
+
+Bug Importance
+**************
+
+Critical
+    This is a serious bug that could cause data loss, stop bzr being
+    usable in an important case, or represents a regression in something
+    previously working.  We should fix critical bugs before doing other
+    work, or seriously consider whether the bug is really critical
+    or whether the other change is more urgent.
+High
+    This is a bug that can seriously interfere with people's use of
+    Bazaar.  We should seriously consider fixing these bugs before
+    working on new features.
+Medium
+    A regular bug.  We'd like to fix them, but there may be a long delay.
+Low
+    Something suboptimal that may affect an unimportant case or have a
+    fairly easy workaround.
+Wishlist
+    These will basically never get done.
+
+Bugs rated Medium or lower are unlikely to get fixed unless they either
+pique the interest of a developer or are escalated due eg to many users
+being affected.
+
+Not every existing bug is correctly rated according to this scale, and we
+don't always follow this process, but we'd like to do it more.  But
+remember, fixing bugs is more helpful than gardening them.
+
+
+Assignment
+**********
+
+Assigning a bug to yourself, or someone else, indicates a real intention
+to work on that bug soon.
+
+
+Targetting Bugs
+***************
+
+It's possible to target a bug to a milestone, eg
+<https://bugs.edge.launchpad.net/bzr/+milestone/1.16>.  We use this mostly
+to help the release manager know what **must** be merged to make the
+release.
+
+Therefore, we don't target bugs that we'd like to have fixed or that could
+be fixed in a particular release, we only target bugs that must be fixed
+and that will or might cause us to decide to slip the release if they're
+not fixed.  At any time, very few if any of the bugs targetted to a
+release should be still open.  By definition, these bugs should normally
+be Critical priority.
+
+
+Backports
+*********
+
+Sometimes we'll want to make a special point-release update (eg 1.15.1)
+off an already-released branch including a fix for a particular bug.  To
+represent this, create a new bug task (ie link in the status table on the
+bug page) by clicking the `poorly-named
+<https://bugs.launchpad.net/bugs/132733>`_ "Target to Release" link.
+Target it to the appropriate series (ie 1.15) and then to the milestone
+within that release.  
+
+This bug task then has a separate status and importance to indicate the
+separate work to get it into that release.
+
+
+The News File
+*************
+
+Most bugs that are fixed should be mentioned in a `NEWS
+<../en/release-notes/NEWS.html>`_ file entry,
+including the bug number.
+(Exceptions might be bugs that are not at all user visible.)
+
+
+Tags
+****
+
+Here are some bug tags we use.  In Malone tags are currently of limited use, so don't feel obliged to tag bugs unless you're finding it useful.
+
+
+authentication
+    authenticating to servers
+
+backport 
+    candidate for backporting to an update of the previous release
+
+dirstate 
+    WorkingTree4
+
+easy 
+    should be possible to finish in an hour or two
+
+hpss 
+    bugs about the High-Performance Smart Server, i.e. bzr+ssh://, etc.
+
+launchpad 
+    bugs about interactions with launchpad (typically this means bzrlib.plugins.launchpad).
+
+locale 
+    problems using locales other than English
+
+memory 
+    problems where we use too much memory for some reason
+
+newformat 
+    fixing this would need a new disk format
+
+performance 
+    bugs about performance problems.
+
+test 
+    needs changes to the test framework
+
+transport 
+    virtual filesystem for http, sftp, etc
+
+trivial 
+    should be very easy to fix (10-20 minutes) and easily landed: typically just spelling errors and the like
+
+ui 
+    bugs relating to the bzr user interface, e.g. confusing error messages.
+
+win32 
+    bugs that mainly affects Windows. Also there is cygwin and win98 tags for marking specific bugs. 
+
+You can see the full list of tags in use at
+<https://bugs.edge.launchpad.net/bzr/+bugs>.  As of September 2008 the
+list is on the right. 
+
+.. vim: ft=rst

=== modified file 'doc/developers/cycle.txt'
--- doc/developers/cycle.txt	2008-10-17 08:05:03 +0000
+++ doc/developers/cycle.txt	2009-06-16 02:35:24 +0000
@@ -1,9 +1,32 @@
+============================
 The Bazaar Development Cycle
 ============================
 
 
-
-General process
+Overview
+--------
+
+Bazaar makes a release every four weeks, with one release candidate one
+week before the final release.  We may vary this schedule from time to
+time, amongst other things to respond to bugs reported in the release
+candidate or the final release.  Nevertheless, we value a regular release
+and we will normally slip only for serious bugs or regressions.
+
+See also:
+
+* `Bazaar Developer Document Catalog <index.html>`_
+
+* `Releasing Bazaar <releasing.html>`_ -- the process for actually making 
+  a release or release candidate.
+
+Longer-Term Planning
+--------------------
+
+Work spanning multiple releases is typically tracked in the bug tracker,
+and summarized in <http://bazaar-vcs.org/Roadmap>.
+
+
+General Process
 ---------------
 
 We normally have one person acting as the release manager, who 
@@ -93,13 +116,6 @@
    <releasing.html>`_ as the first RC.
 
 
-See also
---------
-
-* `Bazaar Developer Document Catalog <index.html>`_
-
-* `Releasing Bazaar <releasing.html>`_ -- the process for actually making 
-  a release or release candidate.
 
 
 ..

=== modified file 'doc/developers/index.txt'
--- doc/developers/index.txt	2009-04-03 01:34:58 +0000
+++ doc/developers/index.txt	2009-06-16 02:35:24 +0000
@@ -49,6 +49,9 @@
 * `EC2 resources <ec2.html>`_ |--| A team resource for 
   Windows packaging and testing, and Ubuntu testing.
 
+* `Tracking Bugs in Bazaar <bug-handling.html>`_ |--| How we use the bug 
+  tracker.
+
 Plans
 =====
 

=== modified file 'doc/developers/releasing.txt'
--- doc/developers/releasing.txt	2009-06-15 00:16:54 +0000
+++ doc/developers/releasing.txt	2009-06-16 02:35:24 +0000
@@ -166,8 +166,7 @@
      
       The Bazaar team is happy to announce availability of a new 
       release of the bzr adaptive version control system.
-      Bazaar is part of the GNU project to develop a complete 
-      free software system.
+      Bazaar is part of the GNU system <http://gnu.org/>.
      
       Thanks to everyone who contributed patches, suggestions, and
       feedback.

=== modified file 'doc/en/developer-guide/HACKING.txt'
--- doc/en/developer-guide/HACKING.txt	2009-06-10 05:00:47 +0000
+++ doc/en/developer-guide/HACKING.txt	2009-06-16 02:35:24 +0000
@@ -1558,16 +1558,6 @@
 Planning Releases
 =================
 
-Roadmaps
---------
-
-As the two senior developers, Martin Pool and Robert Collins coordinate
-the overall Bazaar product development roadmap. Core developers provide
-input and review into this, particularly during sprints. It's totally
-expected that community members ought to be working on things that
-interest them the most. The roadmap is valuable though because it provides
-context for understanding where the product is going as a whole and why.
-
 
 Using Releases and Milestones in Launchpad
 ------------------------------------------