aargh, b2 was b0rken

git-svn-id: http://svn.roundup-tracker.org/svnroot/roundup/trunk@1722 57a73879-2fb5-44c3-a270-3262357dd7e2

diff --git a/CHANGES.txt b/CHANGES.txt
index a06d2bad146f51e34aa7915d95258ba81ff09637..5b046f7e6a228a4ca553870418c322f56c1c2c2f 100644 (file)
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -1,7 +1,12 @@
 This file contains the changes to the Roundup system over time. The entries
 are given with the most recent entry first.
 
-2003-05-?? 0.6.0
+2003-06-10 0.6.0b3
+Fixed:
+- cgi client was broken during b2 fixing
+
+
+2003-06-09 0.6.0b2
 Feature:
 - added the start/stop/restart/condstart/status roundup-server control
   script
@@ -9,6 +14,7 @@ Feature:
 Fixed:
 - handle non-existant demo dir (thanks Ollie Rutherfurd)
 - strip whitespace from Role names so "User, Admin" will work
+- fixed template searching on Windows (thanks J Vickroy)
 
 
 2003-05-09 0.6.0b1

diff --git a/doc/announcement.txt b/doc/announcement.txt
index a8f64031921bef14b959fa380a2b8bea4020a960..25e6b8e1a66586c24a0b76033b2c8e7c5fc0ba4d 100644 (file)
--- a/doc/announcement.txt
+++ b/doc/announcement.txt
@@ -1,8 +1,8 @@
 ===================================================
-SC-Track Roundup 0.6.0b1 - an issue tracking system
+SC-Track Roundup 0.6.0b2 - an issue tracking system
 ===================================================
 
-This is the first release of the new version of Roundup which contains a
+This is the second release of the new version of Roundup which contains a
 lot of new features. This release may contain bugs, so please run this using
 a backup of your production tracker. Always follow the "Software Upgrade"
 guidelines given in the maintenance documentation. If you're upgrading from
@@ -17,8 +17,10 @@ backend.
 
 Roundup requires python 2.1.3 or later for correct operation.
 
-This release has all the bugfixes from the latest 0.5 maintnenance release
-plus lots of new goodies including:
+This release has a couple of bufixes mostly important to Windows users,
+making it possible for them to install new trackers!
+
+The 0.6 release has lots of new goodies including:
 
 - new instant-gratification Demo Mode ("python demo.py" :)
 - added mysql backend (see doc/mysql.txt for details)

diff --git a/doc/index.txt b/doc/index.txt
index 51ca8585411d17912f42924e7d96fc57dd46520b..d0f8d3d443e2de7259a87540ca4121c75c146a3e 100644 (file)
--- a/doc/index.txt
+++ b/doc/index.txt
@@ -83,7 +83,8 @@ Jeffrey P Shell,
 Joel Shprentz,
 Terrel Shumway,
 Nathaniel Smith,
-Mike Thompson.
+Mike Thompson,
+J Vickroy.
 
 
 

diff --git a/doc/overview.txt b/doc/overview.txt
new file mode 100644 (file)
index 0000000..e5ac037
--- /dev/null
+++ b/doc/overview.txt
@@ -0,0 +1,603 @@
+=======================================================
+Roundup: an Issue-Tracking System for Knowledge Workers
+=======================================================
+
+:Authors: Ka-Ping Yee (original_), Richard Jones (implementation)
+
+.. _original: original_overview.html
+
+.. contents::
+
+
+Introduction
+============
+
+Roundup is an issue-tracking system called which will manage a
+number of issues (with properties such as "description", "priority",
+and so on) and provides the ability to:
+
+(a) submit new issues,
+(b) find and edit existing issues, and
+(c) discuss issues with other participants.
+
+Roundup facilitates communication among the participants by managing
+discussions and notifying interested parties when issues are edited.
+
+
+Background
+----------
+
+A typical software project requires the management of
+many tasks, usually distributed among several collaborators.
+In fact, any project team
+could use a tool for sorting out and discussing all the
+relevant issues.  A common approach is to set up some kind
+of "to-do" list that people can share.
+
+However, to address the overall problem we need much more
+than just a shared to-do list; we need to
+manage a growing body of knowledge and experience to help a
+team collaborate effectively on a project.  The issue-tracking
+tool becomes a nexus for communication: the Grand Central
+Station of the group intelligence.
+
+The primary focus of this design is to help
+developers work together well, not to provide a customer
+service interface to the developers.  This is not to say that
+the design is to be made unsuitable for customers to use.
+Rather, it is assumed that many of the same qualities
+that are good for supporting development (see below)
+are also good for non-developers using the system.
+Additional niceties
+for providing a safe or simplified interface to clients are
+intentionally deferred for later consideration.
+
+A good issue-tracking system should have at least the
+following properties:
+
+**Low barrier to participation**
+  The usefulness of the tool depends entirely on the
+  information people contribute to it.  It must be made
+  as easy as possible to submit new issues and contribute
+  information about existing issues.
+
+**Straightforward navigation**
+  It should be easy for users to extract information they need
+  from the system to direct their decisions and tasks.
+  They should be able to get a decent overview of
+  things as well as finding specific information when
+  they know what they're after.
+
+**Controlled information flow**
+  The users must have control over how much information and
+  what information they get.  A common flaw of some issue-tracking
+  systems is that they inundate users with so much useless
+  e-mail that people avoid the system altogether.
+
+With a nod to the time-honoured computer science tradition
+of "filling in the fourth quadrant", we note that
+there are really four kinds of information flow
+going on here.  The three mentioned qualities
+really address the first three quadrants of this 2-by-2 matrix,
+respectively:
+
+1. User push: a user submits information to the system.
+2. User pull: a user queries for information from the system.
+3. System push: the system sends information out to users.
+4. System pull: the system solicits information from users.
+
+An example of the fourth kind of flow is voting.
+Voting isn't described in this design,
+but it should be noted as a potential enhancement.
+
+
+Guiding Principles
+------------------
+
+**Simplicity**
+  It is a strong requirement
+  that the tool be accessible and understandable.  It should
+  be fairly obvious what different parts of the interface do,
+  and the inner mechanisms should operate in ways that most
+  users can easily predict.
+
+**Efficiency**
+  We aim to optimize for minimum effort to do the most common
+  operations, and best use of resources like screen real estate
+  to maximize the amount of information that we summarize and present.
+
+**Generality**
+  We try to avoid making
+  unnecessary assumptions that would restrict the applicability
+  of the tool.  For example, there is no reason why one might
+  not also want to use this tool to manage a design process,
+  non-software projects, or organizational decisions.
+
+**Persistence** We
+  prefer hiding or reclassifying information to deleting it.
+  This helps support the collection of statistics later.
+  If records are never destroyed, there is little danger
+  in providing access to a larger community, and logging yields
+  accountability, which may encourage better behaviour.
+
+
+Data Model
+==========
+
+Roundup stores a number of *items*, each of
+which can have several properties and an associated discussion.
+The properties can be used to classify or search for items.
+The discussion is a sequence of e-mail messages.
+Each item is identified by a unique number, and has
+an activity log which
+records the time and content of edits made on its properties.
+The log stays fairly small since the design intentionally
+provides only small data types as item properties, and
+encourages anything large to be attached to
+e-mail where it becomes part of the discussion.
+The next section explains how items are organized.
+
+
+The Hyperdatabase
+-----------------
+
+Often when classifying information we are
+asked to select exactly one of a number of categories
+or to fit it into a rigid hierarchy.  Yet things
+only sometimes fall into one category; often,
+a piece of information may be related to several concepts.
+
+For example, forcing each item into a single topic
+category is not just suboptimal but counterproductive:
+seekers of that
+item may expect to find it in a different category
+and conclude that the item is not present in the
+database -- which has them *worse* off
+than if the items were not categorized at all.
+
+Some systems try to alleviate this problem by
+allowing items to appear at multiple locations
+in a tree, as with "aliases" or "symbolic links" in
+a filesystem, for example.  This does help somewhat,
+but we want to be even more flexible
+by allowing the
+organization of items into sets that may freely
+intersect.  Rather than putting each item at exactly
+one place in an overall "grand scheme", a item can
+belong to as many sets as are appropriate.
+
+If we choose to represent the sets themselves as items
+and set membership as a link between items,
+we're now ready to present the definition of a
+hyperdatabase.
+
+A *hyperdatabase* is a collection of *items*
+that may be hyperlinked to
+each other (hence the name "hyperdatabase").
+Each item carries a collection of key-value pairs,
+where some of the values may be links to other items.
+Any item may have an arbitrary number of outgoing and
+incoming links.  Hyperdatabases are able to efficiently
+answer queries such as "what items link to this item?"
+and "what items does this item link to?"
+
+Rationale
+---------
+
+There are several reasons for building our
+own kind of database for Roundup rather than using an existing one.
+
+Requiring the installation of a full-blown third-party
+SQL database system would probably deter many potential
+users from attempting to set up Roundup;
+yet a real relational database would be too
+complicated to implement on our own.
+
+On the other hand, a hyperdatabase can be implemented fairly easily
+using one of the Python DBM modules, so we can
+take the "batteries-included" approach and provide it
+as part of the system.  It's easier to build and understand
+than a true relational database (in accordance with our guiding
+principle of *simplicity*), but provides
+most of the query functionality we want.
+
+A hyperdatabase is well suited for finding the intersection
+of a number of sets in which items belong.  We expect that
+most of the queries people want to do will be of this
+form, rather than complicated SQL queries.  For example, a
+typical request might be
+"show me all critical items related to security".
+The ability to store arbitrary key-value pairs and links
+on items gives it more flexibility than an RDBMS.
+
+Users are not going to be making thousands of queries
+per second, so it makes sense to optimize for simplicity
+and flexibility rather than performance.
+
+.. img: images/hyperdb.png
+
+
+Roundup's Hyperdatabase
+-----------------------
+
+For our application, we store each item as a item in a
+hyperdatabase.  The item's properties are stored
+as key-value pairs on its item.
+Several types of properties are allowed:
+*string*, *number*, *boolean*, *date*, *interval, *link*,
+and *multlink*. Another type, *password*, is a special type
+of string and it's only used internally to Roundup.
+
+The *string* type is for short, free-form strings.
+String properties are not intended to contain large
+amounts of text, and it is recommended that they be presented
+as one-line fields to encourage brevity. A *number* is a special
+type of string that represents a numeric value. A *boolean* is
+further constrained to be a *true* or *false* value.
+
+The *date* type is for calendar dates and times. An *interval*
+is the time between two dates.
+
+The *link* type denotes a single selection from a number of
+options.  A *link* property entails a link from the item
+possessing the property to the item representing the chosen option.
+
+The *multilink* type is for a list of links to any
+number of other items in the in the database.  A *multilink*
+property, for example, can be used to refer to related items
+or topic categories relevant to an item.
+
+For Roundup, all items have four properties that are not customizable:
+
+1. a *date* property named **creation**
+2. a *link* property named **creator**
+3. a *date* property named **activity**
+
+These properties represent the date of the creation of the item, who
+created it, and when the last change was made.
+
+Further, all *issue* items have an additional four properties:
+
+1. a *string* property named **title**
+2. a *multilink* property named **nosy**
+3. a *multilink* property named **messages**
+4. a *multilink* property named **files**
+5. a *multilink* property named **superseder**
+
+The **title** property is a short one-line description of the item.
+The detailed description can go in the first e-mail message of the
+item's messages spool.
+
+The **nosy** property contains a list of
+the people who are interested in an item.  This
+mechanism is explained in the section on `Submission and Discussion`_.
+
+Each message added to the item goes in the **messages** spool - any
+attached files go in the **files** spool.
+
+The **superseder** property is used to 
+support the splitting, joining, or replacing of items.
+When several items need to be
+joined into a single item, all the old items
+link to the new item in their **superseder**
+property.
+When an item needs to be split apart, the item
+references all the new items in its **superseder**
+propety.
+We can easily list all active items just by checking
+for an empty **superseder** property, and trace
+the path of an item's origins by querying the hyperdatabase
+for links.
+
+Users of the system are also represented by items in the
+hyperdatabase, containing properties
+like the user's e-mail address, login name, and password.
+
+The Default Schema
+------------------
+
+It is hoped that the hyperdatabase together with the
+specializations mentioned above for Roundup will be
+applicable in a variety of situations
+(in accordance with our guiding principle of *generality*).
+
+To address the problem at hand, we need
+a specific schema for items applied particularly to software development.
+Again, we are trying to keep the schema simple: too many
+options make it tougher for someone to make a good choice::
+
+    # IssueClass automatically gets these properties:
+    #   title = String()
+    #   messages = Multilink("msg")
+    #   files = Multilink("file")
+    #   nosy = Multilink("user")
+    #   superseder = Multilink("issue")
+    #   (it also gets the Class properties creation, activity and creator)
+    issue = IssueClass(db, "issue", 
+                    assignedto=Link("user"), topic=Multilink("keyword"),
+                    priority=Link("priority"), status=Link("status"))
+
+The **assignedto** property assigns
+responsibility for an item to a person or a list of people.
+The **topic** property places the
+item in an arbitrary number of relevant topic sets (see
+the section on `Browsing and Searching`_).
+
+The **prority** and **status** values are initially:
+
+=========== =====================================
+Priority    Description
+=========== =====================================
+"critical"  panic: work is stopped!
+"urgent"    important, but not deadly
+"bug"       lost work or incorrect results
+"feature"   want missing functionality
+"wish"      avoidable bugs, missing conveniences
+=========== =====================================
+
+============= =====================================
+Status        Description
+============= =====================================
+"unread"      submitted but no action yet
+"deferred"    intentionally set aside
+"chatting"    under review or seeking clarification
+"need-eg"     need a reproducible example of a bug
+"in-progress" understood; development in progress
+"testing"     we think it's done; others, please test
+"done-cbb"    okay for now, but could be better
+"resolved"    fix has been released
+============= =====================================
+
+As previously mentioned, each item gets an activity log.
+Whenever a property on an item is changed, the log
+records the time of the change, the user making the change,
+and the old and new values of the property.  This permits
+the later gathering of statistics (for example, the average time
+from submission to resolution).
+
+We do not specify or enforce a state transition graph,
+since making the system rigid in that fashion is probably more
+trouble than it's worth.
+Experience has shown that there are probably
+two convenient automatic state transitions:
+
+1. from **unread** to **chatting** when e-mail is written about an item
+2. from **testing** to **resolved** when a new release of the software is made
+
+Beyond these, in accordance with our principle of *generality*,
+we allow access to the hyperdatabase
+API so that scripts can automate transitions themselves or
+be triggered by changes in the database.
+
+
+User Interface
+==============
+
+Roundup provides its services through two main interfaces:
+e-mail and the Web.
+This division is chosen to optimize the most common tasks.
+
+E-mail is best suited for
+the submission of new items since most people are most comfortable
+with composing long messages in their own favourite e-mail client.
+E-mail also permits them to mention URLs or attach files relevant
+to their submission.  Indeed, in many cases people are already
+used to making requests by sending e-mail to a mailing list
+of people; they can do exactly the same thing to use Roundup
+without even thinking about it.
+Similarly, people are already
+familiar with holding discussions in e-mail, and plenty of
+valuable usage conventions and software tools already exist for that medium.
+
+The Web, on the other hand, is best suited for summarizing
+and seeking information, because it can present an interactive
+overview of items.  Since the Web has forms, it's also
+the best place to edit items.
+
+
+Submission and Discussion
+-------------------------
+
+The system needs an address for receiving mail
+and an address that forwards mail to all participants.
+Each item has its own list
+of interested parties, known as its *nosy list*.
+Here's how nosy lists work:
+
+1. New items are always submitted by sending an e-mail message
+   to Roundup.  The "Subject:" field becomes the description
+   of the new item.
+   The message is saved in the mail spool of the new item,
+   and copied to the list of all participants
+   so everyone knows that a new item has been added.
+   The new item's nosy list initially contains the submitter.
+
+2. All e-mail messages sent by Roundup have their "Reply-To:"
+   field set to Roundup's address, and have the item's
+   number in the "Subject:" field.  Thus, any replies to the
+   initial announcement and subsequent threads are all received
+   by Roundup.  Roundup notes the item number in the "Subject:"
+   field of each incoming message and appends the message
+   to the appropriate spool.
+
+3. Any incoming e-mail tagged with an item number is copied
+   to all the people on the item's nosy list,
+   and any users found in the "From:", "To:", or "Cc:" fields
+   are automatically added to the nosy list.  Whenever a user
+   edits an item's properties in the Web interface, they are
+   also added to the nosy list.
+
+The effect is like each item having its own little mailing list,
+except that no one ever has to worry about subscribing to
+anything.  Indicating interest in an issue is sufficient, and if you
+want to bring someone new into the conversation, all you need to do
+is "Cc:" a message to them.  It turns out that no one ever has to worry
+about unsubscribing, either: the nosy lists are so specific in scope
+that the conversation tends to die down by itself when the issue is
+resolved or people no longer find it sufficiently important.
+
+Each nosy list is like an asynchronous chat room,
+lasting only a short time (typically five or ten messages)
+and involving a small group of people.  However, that
+group is the *right* group of people:
+only those who express interest in an item in some way
+ever end up on the list, so no one gets spammed with mail they
+don't care about, and no one who *wants*
+to see mail about a particular item needs to be left
+out, for they can easily join in, and just as easily
+look at the mail spool on an item to catch up on any
+messages they might have missed.
+
+We can take this a step further and
+permit users to monitor particular topics or classifications of items
+by allowing other kinds of items to also have their own nosy lists.
+For example, a manager could be on the
+nosy list of the priority value item for "critical", or a
+developer could be on the nosy list of the topic value item for "security".
+The recipients are then determined by the union of the nosy lists on the
+item and all the items it links to.
+
+Using many small, specific mailing lists results
+in much more effective communication than one big list.
+Taking away the effort of subscribing and unsubscribing
+gives these lists the "feel" of being cheap and
+disposable.
+
+The transparent capture of the mail spool attached to each
+issue also yields a nice knowledge repository over time.
+
+
+Editing
+-------
+
+Since Roundup is intended to support arbitrary user-defined
+schema for item properties, the editing interface must be
+automatically generated from the schema.  The configuration for
+Roundup will include a template describing how to lay out the
+properties to present a UI for inspecting and editing items.
+For example::
+
+ <tr>
+  <th class="required">Priority</th>
+  <td tal:content="structure context/priority/menu">priority</td>
+  <th>Status</th>
+  <td tal:content="structure context/status/menu">status</td>
+ </tr>
+
+To display the editing form for an item, Roundup inserts
+an HTML form widget where it encounters an expression like
+``tal:content="structure context/priority/menu"``.
+Each type has its own appropriate editing widget:
+
+- *string* and *number* properties appear as text fields
+- *boolean* properties appear as a yes/no selection
+- *date* and *interval* properties appear as text fields
+- *link* properties appear as selection lists
+- *multilink* properties appear as multiple-selection lists
+    or text fields with pop-up widgets for larger selections.
+
+We foresee the use of custom date fields for things like deadlines,
+so input fields for *date* properties support a
+simple way of specifying relative dates (such as "3w" for
+"three weeks from now").
+
+The **superseder** property is a special case:
+although it is more efficient to store a **superseder**
+property in the superseded item, it makes more sense to provide
+a "supersedes" edit field on the superseding item.  We use
+a special widget on items for this purpose (a text field containing
+a comma-separated list of items).  Links in the **superseder** property
+appear on both the superseding and superseded items to
+facilitate navigating an item's pedigree.
+
+After the editing widgets, the item inspection page shows
+a "note" text box and then a display of the messages in the
+discussion spool.  This field
+lets you enter a note explaining your change when you edit the
+item, and the note is included in the notification message that
+goes out to tell the interested parties on the nosy list of
+your edits.
+
+Browsing and Searching
+----------------------
+
+The ideal we would like to achieve is to make searching as
+much like browsing as possible: the user simply clicks about
+on things that seem interesting, and the information narrows
+down comfortably until the goal is in sight.  This is preferable
+to trying to digest a screen filled with widgets and buttons
+or entering a search expression in some arcane algebraic syntax.
+
+While a one-shot search may be appropriate when you're
+looking for a single item and you know exactly what you want, it's
+not very helpful when you want an overview of
+things ("Gee, there are a lot more high-priority items than
+there were last week!") or trying to do comparisons ("I have
+some time today, so who is busiest and could most use some help?")
+
+The browsing interface presents filtering
+functionality for each of the properties in the schema.  As with
+editing, the interface is generated from a template
+describing how to lay out the properties.
+Each type of property has its own appropriate filtering widget:
+
+- *string* properties appear as text fields supporting
+  case-insensitive substring match
+- *date* properties appear as a text field which accepts a date
+  range with start, end or both
+- *link* properties appear as a group of selectable options
+  (the filter selects the *union* of the sets of items
+  associated with the active options)
+- *multilink* properties appear as a group of selectable options
+  (the filter selects the *intersection* of the sets of items
+  associated with the active options)
+
+For a *multilink* property like **topic**,
+one possibility is to show, as hyperlinks, the keywords whose
+sets have non-empty intersections with the currently displayed set of
+items.  Sorting the keywords by popularity seems
+reasonable.  Clicking on a keyword then narrows both the list of items
+and the list of keywords.  This gives some of the feel of walking
+around a directory tree -- but without the restriction of having
+to select keywords in a particular hierarchical order, and without
+the need to travel all the way to the leaves of the tree before
+any items are visible.
+
+Below the filtering form is a listing of items, with their
+properties displayed in a table.  Rows in the table are 
+generated from a template, as with the editing interface.
+This listing is the central overview of the system, and it
+should aim to maximize the density of
+useful information in accordance with our guiding principle of
+*efficiency*.  Colour may be used to indicate
+the status of each item to help the eye sift through the index quickly.
+
+Roundup sorts items
+in groups by priority, and then within groups by the date
+of last activity.  This reveals at a glance where discussion is
+most active, and provides an easy way for anyone to move an issue
+up in the list.
+
+The page produced by a given set of browsing options constitutes
+an *index*.  The options should all be part of the query
+parameters in the URL so that views may be bookmarked.  An index
+specifies:
+
+- search strings for string properties
+- date ranges for date properties
+- acceptable values for choice properties
+- required values for reference properties
+- a sorting key
+- a grouping key
+- a list of properties for which to display filtering widgets
+
+Our default index is:
+
+- all **status** values except "resolved"
+- show **priority** and **fixer**
+- grouping by **priority** in sections
+- sorting by decreasing **activity** date
+
+The starting URL for Roundup immediately presents the listing of
+items generated by this default index, with no preceding query screen.
+

diff --git a/roundup/__init__.py b/roundup/__init__.py
index 27dbc317836c85fad7a3af18edd4addeddebad38..8382cf88b51e27369b2fe6fd05fcf4d95338055e 100644 (file)
--- a/roundup/__init__.py
+++ b/roundup/__init__.py
@@ -15,7 +15,7 @@
 # BASIS, AND THERE IS NO OBLIGATION WHATSOEVER TO PROVIDE MAINTENANCE,
 # SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
 # 
-# $Id: __init__.py,v 1.22 2003-05-09 05:04:34 richard Exp $
+# $Id: __init__.py,v 1.23 2003-06-09 23:17:22 richard Exp $
 
 ''' Roundup - issue tracking for knowledge workers.
 
@@ -67,6 +67,6 @@ written by Ka-Ping Yee in the "doc" directory. If nothing else, it has a
 much prettier cake :)
 '''
 
-__version__ = '0.6.0b1'
+__version__ = '0.6.0b3'
 
 # vim: set filetype=python ts=4 sw=4 et si

diff --git a/roundup/cgi/client.py b/roundup/cgi/client.py
index 7fae91782d33946443d918e70c6ad5e2bbce37f2..c08ec82994ddc1e94deffa60802ce4da9f0897cf 100644 (file)
--- a/roundup/cgi/client.py
+++ b/roundup/cgi/client.py
@@ -1,4 +1,4 @@
-# $Id: client.py,v 1.117 2003-05-09 04:04:27 richard Exp $
+# $Id: client.py,v 1.118 2003-06-09 23:17:23 richard Exp $
 
 __doc__ = """
 WWW request handler (also used in the stand-alone server).
@@ -1423,49 +1423,146 @@ You should then receive another email with the new password.
         raise Redirect, url
 
     def parsePropsFromForm(self, num_re=re.compile('^\d+$')):
-        ''' Pull properties out of the form.
+        ''' Item properties and their values are edited with html FORM
+            variables and their values. You can:
 
-            In the following, <bracketed> values are variable, ":" may be
-            one of ":" or "@", and other text "required" is fixed.
+            - Change the value of some property of the current item.
+            - Create a new item of any class, and edit the new item's
+              properties,
+            - Attach newly created items to a multilink property of the
+              current item.
+            - Remove items from a multilink property of the current item.
+            - Specify that some properties are required for the edit
+              operation to be successful.
 
-            Properties are specified as form variables:
+            In the following, <bracketed> values are variable, "@" may be
+            either ":" or "@", and other text "required" is fixed.
+
+            Most properties are specified as form variables:
 
              <propname>
               - property on the current context item
 
-             <designator>:<propname>
+             <designator>"@"<propname>
               - property on the indicated item (for editing related
                 information)
 
-             <classname>-<N>:<propname>
-              - property on the Nth new item of classname (generally for
-                creating new items to attach to the current item)
+            Designators name a specific item of a class.
+
+            <classname><N>
+
+                Name an existing item of class <classname>.
+
+            <classname>"-"<N>
+
+                Name the <N>th new item of class <classname>. If the form
+                submission is successful, a new item of <classname> is
+                created. Within the submitted form, a particular
+                designator of this form always refers to the same new
+                item.
+
+            Once we have determined the "propname", we look at it to see
+            if it's special:
+
+            @required
+                The associated form value is a comma-separated list of
+                property names that must be specified when the form is
+                submitted for the edit operation to succeed.  
+
+                When the <designator> is missing, the properties are
+                for the current context item.  When <designator> is
+                present, they are for the item specified by
+                <designator>.
+
+                The "@required" specifier must come before any of the
+                properties it refers to are assigned in the form.
+
+            @remove@<propname>=id(s) or @add@<propname>=id(s)
+                The "@add@" and "@remove@" edit actions apply only to
+                Multilink properties.  The form value must be a
+                comma-separate list of keys for the class specified by
+                the simple form variable.  The listed items are added
+                to (respectively, removed from) the specified
+                property.
+
+            @link@<propname>=<designator>
+                If the edit action is "@link@", the simple form
+                variable must specify a Link or Multilink property.
+                The form value is a comma-separated list of
+                designators.  The item corresponding to each
+                designator is linked to the property given by simple
+                form variable.
+
+XXX              Used to add a link to new items created during edit.
+XXX              These are collected up and returned in all_links. This will
+XXX              result in an additional linking operation (either Link set or
+XXX              Multilink append) after the edit/create is done using
+XXX              all_props in _editnodes. The <propname> on the current item
+XXX              will be set/appended the id of the newly created item of
+XXX              class <designator> (where <designator> must be
+XXX              <classname>-<N>).
+
+            None of the above (ie. just a simple form value)
+                The value of the form variable is converted
+                appropriately, depending on the type of the property.
+
+                For a Link('klass') property, the form value is a
+                single key for 'klass', where the key field is
+                specified in dbinit.py.  
+
+                For a Multilink('klass') property, the form value is a
+                comma-separated list of keys for 'klass', where the
+                key field is specified in dbinit.py.  
+
+                Note that for simple-form-variables specifiying Link
+                and Multilink properties, the linked-to class must
+                have a key field.
+
+                For a String() property specifying a filename, the
+                file named by the form value is uploaded. This means we
+                try to set additional properties "filename" and "type" (if
+                they are valid for the class).  Otherwise, the property
+                is set to the form value.
+
+                For Date(), Interval(), Boolean(), and Number()
+                properties, the form value is converted to the
+                appropriate
 
-            Once we have determined the "propname", we check to see if it
-            is one of the special form values:
+            Any of the form variables may be prefixed with a classname or
+            designator.
 
-             :required
-              The named property values must be supplied or a ValueError
-              will be raised.
+            Two special form values are supported for backwards
+            compatibility:
 
-             :remove:<propname>=id(s)
-              The ids will be removed from the multilink property.
+            @note
+                This is equivalent to::
 
-             :add:<propname>=id(s)
-              The ids will be added to the multilink property.
+                    @link@messages=msg-1
+                    @msg-1@content=value
 
-             :link:<propname>=<designator>
-              Used to add a link to new items created during edit.
-              These are collected up and returned in all_links. This will
-              result in an additional linking operation (either Link set or
-              Multilink append) after the edit/create is done using
-              all_props in _editnodes. The <propname> on the current item
-              will be set/appended the id of the newly created item of
-              class <designator> (where <designator> must be
-              <classname>-<N>).
+                except that in addition, the "author" and "date"
+                properties of "msg-1" are set to the userid of the
+                submitter, and the current time, respectively.
 
-            Any of the form variables may be prefixed with a classname or
-            designator.
+            @file
+                This is equivalent to::
+
+                    @link@files=file-1
+                    @file-1@content=value
+
+                The String content value is handled as described above for
+                file uploads.
+
+            If both the "@note" and "@file" form variables are
+            specified, the action::
+
+                    @link@msg-1@files=file-1
+
+            is also performed.
+
+            We also check that FileClass items have a "content" property with
+            actual content, otherwise we remove them from all_props before
+            returning.
 
             The return from this method is a dict of 
                 (classname, id): properties
@@ -1474,22 +1571,6 @@ You should then receive another email with the new password.
             doesn't result in any changes would return {('issue','123'): {}})
             The id may be None, which indicates that an item should be
             created.
-
-            If a String property's form value is a file upload, then we
-            try to set additional properties "filename" and "type" (if
-            they are valid for the class).
-
-            Two special form values are supported for backwards
-            compatibility:
-             :note - create a message (with content, author and date), link
-                     to the context item. This is ALWAYS desginated "msg-1".
-             :file - create a file, attach to the current item and any
-                     message created by :note. This is ALWAYS designated
-                     "file-1".
-
-            We also check that FileClass items have a "content" property with
-            actual content, otherwise we remove them from all_props before
-            returning.
         '''
         # some very useful variables
         db = self.db

diff --git a/setup.py b/setup.py
index fc98a4e4377ada38343ab82defdceb44186c30c8..367293d2b3a992ada67299ae14bc2090cad61105 100644 (file)
--- a/setup.py
+++ b/setup.py
@@ -16,7 +16,7 @@
 # BASIS, AND THERE IS NO OBLIGATION WHATSOEVER TO PROVIDE MAINTENANCE,
 # SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
 # 
-# $Id: setup.py,v 1.52 2003-05-09 05:28:42 richard Exp $
+# $Id: setup.py,v 1.53 2003-06-09 23:17:20 richard Exp $
 
 from distutils.core import setup, Extension
 from distutils.util import get_platform
@@ -185,8 +185,10 @@ def main():
 command-line, web and e-mail interfaces. It is based on the winning design
 from Ka-Ping Yee in the Software Carpentry "Track" design competition.
 
-This release has all the bugfixes from the latest 0.5 maintnenance release
-plus lots of new goodies including:
+This release has a couple of bufixes mostly important to Windows users,
+making it possible for them to install new trackers!
+
+The 0.6 release has lots of new goodies including:
 
 - new instant-gratification Demo Mode ("python demo.py" :)
 - added mysql backend (see doc/mysql.txt for details)
@@ -215,7 +217,7 @@ plus lots of new goodies including:
 ''',
         author = "Richard Jones",
         author_email = "richard@users.sourceforge.net",
-        url = 'http://sourceforge.net/projects/roundup/',
+        url = 'http://roundup.sourceforge.net/',
         download_url = 'http://sourceforge.net/project/showfiles.php?group_id=31577',
         packages = packagelist,
         classifiers = [