Cleanup the README and TODO files a bit. Time to send flask@ a note a…

…nnouncing the repo.

Signed-off-by: Sean Chittenden <[email protected]>

README

@@ -1,34 +1,65 @@
 	This is a "LAMP" stack done right... but using *NIX (FreeBSD/Mac),
 	nginx, memcache, python and postgresql. :~]
 
-Recently someone asked me what my preferred web framework was these days (it
-feels like I've tried them all and have developed a few opinions along the
-way). It's Flask (as of May 2011), but explaining the bootstrapping process
-required to get a new app up and running is a high enough that you can't
-easily expect a new programmer to figure it out. And this isn't unique to
-Flask, bootstrapping any framework is typically a tremendous pain in the
-ass... and it shouldn't have to be... yet still is. So!, invariably you end
-up wasting your afternoon looking up the required implementation details to
+There are several goals with this Skeleton:
+
+1) To demonstrate Flask in action in a complete context, as opposed to the
+fragmented set of tools that comprise Flask. Flask as a collection of modules
+is great, btw!, but it means you have to bootstrap constantly. Skeleton is
+out to combat that.
+
+2) To demonstrate various best practices and combat the effects of the MySQL
+stupid juice. Use of MySQL has led to some incredibly bad examples for how to
+do things that end up being adopted by organizations and developers as "the
+way" for open source products, but in professional development land, there
+are diverging strategies. Document and exhibit an increasing number of them
+here. Over time, I'd like to incorporate improved practices as they become
+known.
+
+3) Maintain Skeleton once the items in the TODO list are complete and shift
+it in to maintenance mode. Specifically, I don't want to see it advance
+beyond being a good starting point for developers (myself included).
+
+So what started this?
+
+Recently several people asked me for framework recommendations (it feels like
+I've tried them all and have developed a few opinions along the way). As of
+May 2011 it's Flask, but explaining the bootstrapping process required to get
+a decent app up and running is high enough that you can't easily expect a new
+programmer to figure it out before their attention span begins to drift. At
+the same time I was giving out recommendations and fielding questions
+regarding Flask, I also had a flurry of applications that I needed to
+write. Ugh.
+
+Bootstrapping any framework is typically a tremendous pain in the ass (and it
+shouldn't have to be, but still is). So instead of constantly wasting various
+evenings or afternoons looking up the required implementation details to
 stitch components that every application needs (e.g. a database, static
-files, caching). Bleh.
-
-This skeleton app is has been hanging out in my ~/src/template_app directory
-for long enough and needs to see the light of day. It has grown to support
-multiple modules structured in a "ready-to-grow" way that shouldn't take
-hours of research to figure out how it was all put together or where the next
-set of work should go in order to get something running. All of the provided
-"scaffolding" resides somewhere under 'skeleton/' so that your friendly
-`egrep -r` command can find the desired string and cement your understanding
-of the layout. Read through the rest of the README for the relevant steps and
-details.
+files, caching), I started Flask-Skeleton.
+
+I'd been hanging on to a "skeleton" app in my ~/src/template_app directory
+for long enough and that I finally decided to kick something out that was
+usable and documented. See the TODO for details on what has been completed,
+but it was initially released to support structured development with a common
+set of design patterns already implemented (i.e. it shouldn't take hours of
+research to figure out how to do a mechanical task or get some piece of
+infrastructure integrated). All of the provided "scaffolding" resides
+somewhere under 'skeleton/' so that your friendly `egrep -r` command can find
+the desired string and cement your understanding of the layout (i.e. don't do
+the django thing and attempt to be clever by stashing application logic in
+random libraries).
 
 With Flask being the awesomest awesomesauce around (at least as of May 2011),
 hopefully this contribution from your neighborhood ghost in the machine will
-make Flask development a bit easier to get started with. If you find new
-tricks that are sensible, straightforward and will help other developers
-setup their apps in a non-fail way, let me know and I'll incorporate your
-changes (including improved documentation, unit tests and comments).  Cheers
-and good luck.
+make Flask development a bit easier to get started with and will have a
+positive impact on your future application development.
+
+If you find new tricks that are sensible, straightforward and will help other
+developers setup their apps in a non-fail way, let me know[1] and I'll
+incorporate your changes (including improved documentation, unit tests and
+comments).  Cheers and good luck.
 
 To begin making use of this skeleton, step through the instructions in
 INSTALL.
+
+[1] https://github.com/sean-/flask-skeleton

TODO

@@ -1,47 +1,53 @@
-Things still in progress:
+See below for a list of completed items. Things still in progress:
 
 *) Add per-user timezone support
-
 *) Cache a user-object upon login in memcache
-
 *) Beef up the @logged_in decorator so that it:
-
    1) checks memcache for a matching session
    2) Logs a user out if their session has expired (or updates it accordingly)
    3) Populates memcache with a user object upon cache miss
-
 *) Add authorization decorators (maybe)
-
 *) Unit testing framework
-
 *) Migrate to using setup.py instead of providing a fixed requirements.txt
-
 *) Scripting via Flask-Script (both shell setup and cron-like jobs)
-
 *) Localization
-
 *) Services API example (XML, maybe protobuf)
-
+*) Add support for insecure and secure cookies
+*) Logout = kill session in memcache and the database
+*) pgmemcache
 
 
 Things that are demonstrated well enough:
 
-*) ORM Layer and examples
-
-*) Caching of objects, fragments and views via memcache
-
-*) Database schema and permissions
-
-*) Registration and login/logout
-
-*) Session management
-
-*) Use of PostgreSQL functions
-
-*) Modularized development
-
-*) Jinja templates and Jinja2 template filters
-
-*) Debugging toolbar
-
-*) Static assets management
+Database (PostgreSQL):
+	*) ORM Layer and examples
+	*) PostgreSQL schema
+	*) Database ROLEs and permissions
+	*) PostgreSQL pl functions
+
+ORM (SQLAlchemy):
+	*) Use of PostgreSQL functions with SQLAlchemy
+
+AAA (Access, Authentication, Authorization):
+	*) Registration
+	*) Login (via pl functions)
+	*) Logout
+
+Caching (memcached):
+	*) Objects
+	*) memoized functions
+	*) Views
+
+Application:
+	*) Modularized development (filesystem layout)
+	*) Integration with other WSGI Middleware's
+	*) Session management (secure cookie handling)
+	*) Static assets management
+
+Development:
+	*) Debugging toolbar
+	*) Application profiling
+
+Templating (Jinja2):
+	*) Template layout
+	*) Template filters