Skip to content
This repository
Browse code

added first pass of documentation about proposals

  • Loading branch information...
commit dc11411a4aef4e2507de66efcc1712b56ce69203 1 parent 3659da8
James Tauber authored July 12, 2012
1  docs/index.rst
Source Rendered
@@ -18,6 +18,7 @@ Apps:
18 18
    conference
19 19
    sponsorship
20 20
    speakers
  21
+   proposals
21 22
 
22 23
 
23 24
 Indices and tables
111  docs/proposals.rst
Source Rendered
... ...
@@ -0,0 +1,111 @@
  1
+Proposals App
  2
+=============
  3
+
  4
+
  5
+Models
  6
+------
  7
+
  8
+
  9
+ProposalSection
  10
+~~~~~~~~~~~~~~~
  11
+
  12
+Recall that a symposion instance consists of one or more ``Conference``s each
  13
+made up of one or more ``Section``s.
  14
+
  15
+Different sections can have different open / close dates for proposals.
  16
+This is managed through a ``ProposalSection`` which is a one-to-one with
  17
+``Section`` where you can define a ``start`` date, an ``end`` date and/or
  18
+simply toggle proposals for the section ``closed``.
  19
+
  20
+A section is available for proposals iff:
  21
+ * it is after the ``start`` (if there is one) and
  22
+ * it is before the ``end`` (if there is one) and
  23
+ * ``closed`` is NULL or False
  24
+
  25
+In other words, ``closed`` can be used as an override, regardless of ``start``
  26
+and ``end`` and, if you want, you can just manually use ``closed`` rather than
  27
+setting dates.
  28
+
  29
+This model is currently managed by conference staff via the Django admin
  30
+although given it's part of "conference setup", it may often just be a
  31
+fixture that's loaded.
  32
+
  33
+
  34
+ProposalKind
  35
+~~~~~~~~~~~~
  36
+
  37
+A conference, even within a section, may have different kinds of
  38
+presentations, e.g. talks, panels, tutorials, posters.
  39
+
  40
+If these have different requirements for what fields should be in the
  41
+proposal form, they should be modeled as different ``ProposalKind``s. For
  42
+example, you may want talk proposals to include an intended audience level
  43
+but not require that for poster submissions.
  44
+
  45
+Note that if you have different deadlines, reviews, etc. you'll want to
  46
+distinguish the **section** as well as the kind.
  47
+
  48
+This model is currently managed by conference staff via the Django admin
  49
+although given it's part of "conference setup", it may often just be a
  50
+fixture that's loaded.
  51
+
  52
+
  53
+ProposalBase
  54
+~~~~~~~~~~~~
  55
+
  56
+Each proposal kind should have a subclass of ``ProposalBase`` defining the
  57
+fields for proposals of that kind. We discuss below how that association is
  58
+made.
  59
+
  60
+``ProposalBase`` provides fields for a ``title``, a single-paragraph
  61
+plain-text ``description`` and an ``abstract`` which can contain markup.
  62
+
  63
+There is also an ``additional_notes`` field which can be used for speakers to
  64
+communicate additional information about their proposal to reviewers that is
  65
+not intended to be shared with others.
  66
+
  67
+This base model supports each proposal having multiple speakers (although
  68
+the submitting speaker is always treated differently) and also supports
  69
+the attachments of supporting documents for reviewers that are, like the
  70
+``additional_notes`` not intended to be shared with others.
  71
+
  72
+A ``cancelled`` boolean field is also provided to indicate that a proposal
  73
+has been cancelled or withdrawn.
  74
+
  75
+
  76
+AdditionalSpeaker
  77
+~~~~~~~~~~~~~~~~~
  78
+
  79
+Used for modeling the additional speakers on a proposal in additional to the
  80
+submitting speaker. The status of an additional speaker may be ``Pending``,
  81
+``Accepted`` or ``Declined``.
  82
+
  83
+.. todo:: see note in speakers docs about explaining the flow
  84
+
  85
+
  86
+SupportingDocument
  87
+~~~~~~~~~~~~~~~~~~
  88
+
  89
+Used for modeling the supporting documents that can be attached to a proposal.
  90
+
  91
+
  92
+How to Add Custom Proposal Kinds
  93
+--------------------------------
  94
+
  95
+For each kind:
  96
+
  97
+ * create a ``ProposalKind`` instance
  98
+ * subclass ``ProposalBase`` and add the fields you want
  99
+ * define a Django ``ModelForm`` for proposals of that kind
  100
+ * make sure your settings file has a ``PROPOSAL_FORMS`` dictionary
  101
+   that maps the slug of your ``ProposalKind`` to the fully-qualified
  102
+   name of your ``ModelForm``.
  103
+
  104
+For example::
  105
+    
  106
+    PROPOSAL_FORMS = {
  107
+        "tutorial": "pycon.forms.PyConTutorialProposalForm",
  108
+        "talk": "pycon.forms.PyConTalkProposalForm",
  109
+        "poster": "pycon.forms.PyConPosterProposalForm",
  110
+    }
  111
+
2  symposion/proposals/models.py
@@ -30,7 +30,7 @@ class ProposalSection(models.Model):
30 30
     start = models.DateTimeField(null=True, blank=True)
31 31
     end = models.DateTimeField(null=True, blank=True)
32 32
     closed = models.NullBooleanField()
33  
-    published = models.NullBooleanField()
  33
+    published = models.NullBooleanField()  # @@@ what is this used for?
34 34
     
35 35
     @classmethod
36 36
     def available(cls):

0 notes on commit dc11411

Please sign in to comment.
Something went wrong with that request. Please try again.