Add note about git with shared checkouts
[wiki.git] / projects / clockworks.mdwn
index 61632494d1c148efab41f023441b459f3ba9b1ad..4ce15fbbdf86b0dbcdbcc5d0018d2dfa73239fb8 100644 (file)
@@ -1,6 +1,7 @@
 [[!meta title="Clockworks"]]
 
-Hey guys, I heard there was this app called [Doodle](http://www.doodle.com/main.html). It's closed source. Let's make an open-source Doodle killer and call it Clockworks!
+## Summary
+So originally we were thinking, "Hey guys, I heard there was this app called [Doodle](http://www.doodle.com/main.html). It's closed source. Let's make an open-source Doodle killer and call it Clockworks!" More recently, we've been considering what we can do to help schedule things around MIT.
 
 We have a mailing list - if you're interested in helping design the
 app, just [let one of the developers know](mailto:clockworks@mit.edu)
@@ -8,25 +9,30 @@ and we'll add you to our mailing list, **clockworks**. Or if you just
 want to hear more about what we're up to, blanche yourself to the
 public list **clockworks-announce**.
 
-## Getting started
+## State & History
+Clockworks is in alpha phase; the most basic functions of the system are operational. A user can:
 
-Clockworks is in pre-pre-alpha phase; most of the functionality hasn't been done yet.
+* Make an account via the online registration system
+* Login to the web interface to enable poll modifications
+* Create a every simple poll
+* View poll
+* Vote in a poll
 
-The best way to get started with Clockworks is to get yourself added to the project, grab a copy of the code, get it running on your laptop, and then poke around the source code.  We also have a Hiveminder project with bite-sized tasks that you can work on (ping a project maintainer to get invited.)
+The current implementation is in Django. There was an older Clockworks pre-pre-alpha implementation in TurboGears. 
 
-First, make sure you have Git installed on your system. You can grab it [here](http://git-scm.com/download). Verify that it installed by popping open a terminal and running **git --version**
+## Getting started
 
-Next, grab the source code.  If you have Debathena installed on your machine, you can clone the source using **git clone /mit/clockworks/clockworks.git**.  If not, you can use a dialup to get to the directory; **git clone ssh://username@linerva.mit.edu/mit/clockworks/clockworks.git** works well. If the clone succeeds, you will now have a folder named "clockworks".  **cd clockworks**
+The best way to get started with Clockworks is to get yourself added to the project, grab a copy of the code, get it running on your laptop, and then poke around the source code.
 
-Now, to install the application.  Assuming that you have a reasonable version of Python on your system, running **./nosudo-virtualenv.sh** should set up the environment.  If it succeeds, you'll see the help output for a command named paster.
+First, make sure you have Git installed on your system. You can grab it [here](http://git-scm.com/download). Verify that it installed by popping open a terminal and running **git --version**
 
-Run the application by changing into your environment with **source tg2env/bin/activate** and then typing **paster serve --reload development.ini**. And voila; a very boilerplate TurboGears install should be facing you at http://localhost:8080
+Next, grab the source code.  If you have Debathena installed on your machine, you can clone the source using **git clone /mit/clockworks/clockworks.git**.  If not, you can use a dialup to get to the directory; **git clone ssh://username@linerva.mit.edu/mit/clockworks/clockworks.git** works well. If the clone succeeds, you will now have a folder named "clockworks".  **cd clockworks**
 
-If these steps fail (which happens on some configurations of OS X and almost invariably on Windows), talk to us and we can get you set up with a copy running on scripts.mit.edu or xvm.mit.edu.
+Now, to install the application according to the instructions in the repository.
 
 Once you're running, here are some paths to take:
 
-1. Take a break and read some TurboGears documentation to get a feel for the framework
+1. Take a break and read some Django documentation to get a feel for the framework
 2. Browse through the todo list, pick a task that seems interesting, and start working on figuring out how to make it work
 3. Browse the source, fiddle with some variables, see what changes
 4. Decide what clockworks should look like, and take off
@@ -36,103 +42,18 @@ Once you're running, here are some paths to take:
 
 Our Git repository is located in AFS in the clockworks locker: /mit/clockworks/clockworks.git
 
-## Phase 1
-
-Doodle clone. 100% duplication of Doodle functionality. Modifications to improve usability as necessary.
-
-### Pitfalls to avoid
-
-What do people not like about Doodle?
-
-* Too much clicking
- * We can deal with this by collapsing the three-page wizard Doodle has into a single page. Be careful not to sacrifice too much simplicity for such a setup.
-* No obvious "I can, but would rather not"
- * Alleviated also by the above; this might want to be the default poll setup.
-* Trac, one of the first Python web applications to hit mainstream, was long bemoaned for being complex to install. Try not to have the same story
-
-### What to do?
-
-* <del>Work through the [TurboGears tutorial](http://docs.turbogears.org/1.0/Wiki20/Page1) (the tutorial seems to focus on SQLObject, which is not necessarily the best thing. Maybe someone can find some better docs?)</del>
-* <del>Setup database configuration and installer (an auxiliary issue is the presence of an installer for people). (**ezyang**)</del>
-* Learn SQLAlchemy (**ezyang**)
-* <del>Make sure the default scaffolding works on Scripts (this includes running TurboGears as CGI). Any work done here should be considered for a TurboGears auto-installer, the equivalent of tgsetup) (**ezyang**)</del>
-* <del>Write a .gitignore file for generated/not versionable items</del>
-* <del>Get friendly URLs working</del>
-* <del>Setup a zephyrbot that watches the repository</del>
-* [Configure](http://turbogears.org/2.0/docs/main/Config.html) the default TurboGears scaffolding
-* Learn [Genshi](http://turbogears.org/2.0/docs/main/Genshi.html), the templating engine
-* Learn [Widgets](http://turbogears.org/2.0/docs/main/ToscaWidgets/forms.html) (we'll be using them for all of the forms in this website)
-* Polish up and get SSL authentication working with TurboGears Identity (the two should be integrated together in a sane manner.)
-* Write model classes for all of our tables
-* Write controllers for each of the pages
-
-### Architecture
-
-* **Language**: Python 2.5+
-* **Framework**: TurboGears 2.0
-* **SCM**: Git
-* **JavaScript**: Mochikit
-* **Database**: SQLite for development, ? for production
-* **ORM**: SQLAlchemy
-* **Templating**: Genshi
-
-Other ideas:
-
-* Use 15 minute timeslices to simplify interface
-
-### Principles
-
-* Simplicity
-* Extendibility
-* Open Source
-
-### Schema
-
-You can view the database schema in *model.py*. Some notable features:
-
-* All `user.user_id` foreign keys are paired with an `anon_name` field. If user_id is null, then the associated entity was posted by an anonymous user, and `anon_name` contains the name they submitted for themselves
-* The current `time_slots` table uses `DateTime` and `Interval` to define events. We should consider whether or not 15 minute timeslices will be the native representation in the database, or simply a simpler model for the interface
-* `length` is likely common through all possible times for an event, so it's stored in both `time_slots` and `event`
-* `events.timezone` represents the timezone that the event is occurring in, so we can give user-friendly times. If this field is null, then the creator's `user.timezone` field is used (if that is also null, we should probably use EST)
-* `key` and `admin_key` in `event` refer to random values that will compose the URLs for events.
-* For full backwards compatibility, `hidden` and `extended` are stored as boolean attributes (the former refers to hiding the responses of users, the latter refers to allowing Yes/No/IfNeedBe responses). We may want to consider an alternate model for these properties
-* The schema is not very generalized. Certain parts should definitely be generalized, but let's try to avoid the architecture astronaut syndrome.
-
-### Page Inventory
-
-List of "screens" in Doodle
-
-* **/**: Home page (including login)
-* **/help**: Help pages (screencasts, interactive JavaScript, etc.)
-* **/new**: Schedule event (should be one-page-able)
-  * General info (title, description, name, email)
-  * Days (calendar, should be AJAX)
-  * Times (timezone (JS fill-in), add more timeslots, copypaste first row)
-  * Options (yes-no-ifneedbe, hidden poll, limit OKs)
-  * Poll created (admin, participant links)
-* **/events/*event-name***: View poll (timezone, name, times, information, functions)
-  * **/events/*event-name*/edit**: Edit entry (completely wiki!)
-  * Delete entry
-  * **/events/*event-name*/comment**: Add a comment
-  * **/events/*event-name*/export**: Calendar export (both ways)
-  * File export (excel, pdf)
-  * **/events/*event-name*/feed**: Subscribe (atom, and then social feed services)
-  * **/events/*event-name*/embed**: Embed poll (iframe)
-* **/events/*event-name*/admin**: Admin poll (participation link)
-  * **/events/*event-name*/admin/edit**: Edit poll (all original options)
-  * **/events/*event-name*/admin/history**: History
-  * **/events/*event-name*/admin/reset**: Delete all participants/comments
-  * **/events/*event-name*/admin/delete**: Delete poll
-* **/signup**: Signup page
-* **/myclockworks**: List of polls created by user, list of polls the user has participated in, links to creating a new event
-  * **/myclockworks/account** provides links to the following four links
-  * **/myclockworks/changeEmail**
-  * **/myclockworks/changePassword**
-  * **/myclockworks/editInformation**
-  * **/myclockworks/delete**
-  * Note: Doodle functions by creating two links per event: one for the public and one for administrator, but anyone can follow either link if they know what it is
-
-## Phase 2
+The repo contains a Django project.
+
+## Some Simpler Future Steps:
+
+* Create a groups mechanic
+* Enable the sending of polls to groups
+* Enable poll configurations other than the current default
+* Enable users to manage their polls centralls
+* Add a user homepage
+* Add a homepage
+
+## Potential Future Dream Goals
 
 Doodle killer. Extra features. Pump it up.
 
@@ -151,6 +72,8 @@ Doodle killer. Extra features. Pump it up.
 
 ## Developers
 
+* Paul W. Quimby
+* Andrew Farrell
 * Geoffrey Thomas
 * Paul Baranay
 * Edward Yang
@@ -159,3 +82,5 @@ Doodle killer. Extra features. Pump it up.
 * Christian Ternus
 * David Benjamin
 * <a href="mailto:clockworks@mit.edu">You?</a>
+
+