Question sets are now collected in a Work called a Survey. Reviews now
form collections of specific Answers to the Questions in a specific Survey,
which acts as a Review "template".
git-svn-id: http://soc.googlecode.com/svn/wiki@264 5fae56a1-394a-0410-ba46-5107137fd53f
diff --git a/ReviewModel.wiki b/ReviewModel.wiki
index 5fbb8cd..7888e58 100644
--- a/ReviewModel.wiki
+++ b/ReviewModel.wiki
@@ -7,81 +7,67 @@
class Review(db.Model):
"""Model of a review of a Proposal or a Task.
- A Review is a Work made up of one or more Questions and their associated
- Answers. Reviews will even be used to implement comments and scoring
- annotations to Proposals and Tasks. For example, a commment attached to
- a Proposal is a Review with a single "question" (with the answer being
- the comment itself). An evaluation might be made up of two "questions",
- one containg the comment as the answer and the other containing the score.
+ A Review entity is a specific instance of a completed Survey, collecting
+ the Answers to the Questions that are found in that Survey.
+
+ Reviews are also used to implement comments and scoring annotations to
+ Proposals and Tasks. For example, a commment attached to a Proposal is
+ a Review with the Answer to a single "question" (with that answer being
+ the comment itself). A scoring evaluation might be made up of
+ Answers to two "questions", one containg the comment the other
+ containing the score.
A Review entity participates in a number of relationships:
- work) a required 1:1 relationship with a Work entity that contains the
- general "work" properties of the Review. The back-reference in the Work
- model is a Query named 'review'.
+ survey) a required many:1 relationship with a Survey which acts as a
+ "template" for the Review, containing the Questions that are anwered
+ by the Answers associated with the Review. The back-reference in
+ the Survey model is a Query named 'reviews' which represents all of
+ the Reviews that contains Answers to the Questions in that particular
+ Survey.
- work.authors: the Authors of the Work referred to by this relation
- are the Review "template" of questions and possible answers, not the
- answers themselves, which is, instead, the reviewer.
+ answers) a 1:many relationship (but not required, since initially none
+ of the Questions to be answered by a Review will have Answers) that
+ relates the specific answers to the Survey questions for a specfic
+ Review instance. This relation is implemented as a back-reference
+ Query of the Answer model 'review' reference.
- work.title: the title of the Review "template", not the specific
- instance of the Review containing selected answers.
+ Some (zero or more) of the Questions answered by a Review may define an
+ 'approval_style' string and one or more 'approval_answers'. See
+ the Question and Answer models for details. All Questions answered
+ in the Review that provide non-empty 'approval_style' and
+ 'approval_answers' must meet the described approval conditions for
+ the Review to represent "approval" (or a "positive outcome" or
+ a "passing grade", so to speak). Most Reviews answer Questions in
+ a Survey that contains only a single "approval" question (if they
+ contain one at all).
- work.abstract: db.TextProperty displayed before the first Question,
- usually explanatory text.
+ reviewed) a required many:1 relationship with a Work, where the
+ Review answers are attached to the Work as a comment, evaluation,
+ review, report, acceptance, etc. Reviews are the mechanism by
+ which non-authors of the Work make annotations to it. The
+ back-reference in the Work model is a Query named 'reviews'
+ which represents all of the annotations attached to that particular
+ work.
reviewer) a required many:1 relationship with a Reviewer entity indicating
the "author" of the actual answers for a specific Review instance. The
back-reference in the Reviewer model is a Query named 'reviews' which
represents all of the Reviews by that particular Reviewer.
- proposal) an optional many:1 relationship with a Proposal entity attaching
- the Review to that Proposal. The back-reference in the Proposal model
- is a Query named 'reviews'. This relationship is mutually exclusive
- with the 'task' relationship.
-
- task) an optional many:1 relationship with a Task entity attaching
- the Review to that Task. The back-reference in the Task model is a
- Query named 'reviews'. This relationship is mutually exclusive
- with the 'proposal' relationship.
-
- questions) a required many:many relationship with Question entities, where
- a given Question can appear in more than one Review, and a Review is made
- up of one or more questions. See the ReviewsQuestions model for details.
- Under this model, a given Question can only be asked once in a given
- Review (or Review "template"). Asking the same exact question twice does
- not seem like a common use case.
-
- Some (zero or more) of the Questions asked by a Review may define an
- 'approval_style' string and one or more 'approval_answers'. See
- the Question and Answer models for details. All Questions asked in the
- Review that provide non-empty 'approval_style' and 'approval_answers'
- must meet the described approval conditions for the Review to represent
- "approval" (or a "passing grade", so to speak). Most Reviews contain
- only a single "approval" question (if they contain one at all).
-
- answers) a 1:many relationship (but not required, since initially none
- of the Questions asked by a Review will have Answers) that relates the
- specific answers to the Review questions for a specfic Review instance.
- This relation is implemented as a back-reference Query of the Answer
- model 'review' reference.
-
start: db.DateTimeProperty that indicates the beginning of the time period
in which this Review can be "answered" (e.g. survey start date)
end: db.DateTimeProperty that indicates the end of the time period
in which this Review can be "answered" (e.g. survey end date)
"""
- work = db.ReferenceProperty(reference_class=Work, required=True,
- collection_name="review")
+ survey = db.ReferenceProperty(reference_class=Survey, required=True,
+ collection_name="reviews")
- reviewer = db.ReferenceProperty(reference_class=Reviewer, required=True,
+ reviewed = db.ReferenceProperty(reference_class=Work, required=True,
collection_name="reviews")
- task = db.ReferenceProperty(reference_class=Task,
- collection_name="reviews")
-
- proposal = db.ReferenceProperty(reference_class=Proposal,
+ reviewer = db.ReferenceProperty(reference_class=Reviewer, required=True,
collection_name="reviews")
start = db.DateTimeProperty()
