# HG changeset patch # User Jeff Hammel # Date 1364039026 25200 # Node ID 0c411c083fab7334af9ca80170c38742d187afd5 # Parent c008855cf3a9e0131e723d359a94b814ff189ebb update doc diff -r c008855cf3a9 -r 0c411c083fab README.txt --- a/README.txt Fri Nov 25 19:49:31 2011 -0800 +++ b/README.txt Sat Mar 23 04:43:46 2013 -0700 @@ -1,7 +1,7 @@ buttercup: a flower for k0s.org =============================== -buttercup is a `flower `_ that is used to bloom a website like +buttercup is a ``flower`` that is used to bloom a website like `k0s.org `_. There are several `python `_ components to a buttercup website: @@ -13,16 +13,161 @@ * software demos: - anagram - wordstream + * and so forth + why is buttercup so messy? -------------------------- Easy. Its the backport of a highly specific website to a flower. The buttercup flower is in fact a study in botany, useful in the study of -species, but probably less interesting as a practical deployment. +species, but probably less interesting as a practical deployment for +widescale use. does buttercup work yet? ------------------------ -No. It is still a work in progress. +Depends on what you want to do. Right now, what `buttercup` does is +mostly best gleaned from the source code. I hope to change this with time. + + +what is a flower? +----------------- + +Every website has, in essence, an intent, a purpose the website serves +and tools and method with which to enact such purpose. While the +intent itself belongs to the domain of natural language, the tools +(read: web applications) and how they are deployed (including +e.g. request dispatching) should be catalogued in a manner actionable +to machine. + +A flower is a deployment pattern of a website. + +The deployment pattern contains information about what tools (usually, +python packages) are required, how they are set up for an instance of +the pattern, and how they interact with each other; but it does not +contain content (including site-static content) save in abstract. + +For example, imagine you are making a very simple website where you +want static files and directories served from the path info segment +``/``, a blog served at ``/blog``, and the ability to upload files to +whatever directory ``/`` corresponds to on the web server's +filesystem. (Let's also make it real simple and completely ignore auth +which you should definitely *NOT* do if you were to deploy this flower.) +If you were me, you'd probably use +`decoupage `_ + for the file server, +`bitsyblog `_ +for the blog software, +and `uploader `_ +for the file upload widget. +This would be a *flower*. It has a clear intent -- a blog and file +server -- and a set of tools that manifests that intent. +You could have variations on this, such as mounting the blog at ``/`` +and files at ``/files``, but since the deployment intentions are the +same (the tools interact with each other the same way, from a machine +point of view). It would be of merit to write this example flower, +but such shall be reserved for an exercise to the reader (which may +very well be me). + + +I'm a programmer. Can you give me a briefer explanation? +--------------------------------------------------------- + +Assuming you know object-oriented programming, a flower would be the +*class* of the website, and the website would be the instance. + + +what should a flower look like? +------------------------------- + +As said, buttercup is currently messy. It was written as a marriage +between a very minimalistic need of saving some time on very specific +problems and the abstract idea of flowers which I didn't have time to +delve in. Voila! Software is born. In addition, even had I the best +intentions and time available to them, technologies such as more +recent pip changes were not available at the time of crafting. + +Also, I'm lazy and/or don't have time to work on it. + +In essence, ``buttercup`` has (or should have): + +- a list of software requirements (that should be installed in +``--develop`` mode in a ``virtualenv``) +- a method of "fitting the pipes" with + `wsgintegrate `_ +- (and there's also something about ensuring system packages are + installed and what not; see e.g + http://k0s.org/hg/buttercup/file/c008855cf3a9/buttercup/PACKAGES.txt + though I believe it is yet unused) + +If I were to incorporate these as concepts into ``buttercup``, I would +make the flower have: + +- a ``pip`` + `requirements file `_ + +- a skeleton of a ``wsgintegrate`` ``.ini`` file and methods to + interpolate this skeleton to the instance + +- *and*, very importantly but very forgettably, tools to port + production changes to the ``wsgintegrate`` configuration back to + the flower. + +- (in addition formalize the system packages (obviously per platform) + needed and how to check for them install them etc. Not sure if + there is stuff out there for this; outside of the fact that several + platforms have to be supported, its a pain. Vagrant and puppet seem + close...ish. Silverlining?) + +Obviously, this sort of make-up works for ``buttercup``. It would not +work so well if, say, you were using apache + mod_wsgi vs +e.g. wsgintegrate and a standalone WSGI server. While the latter (and +other) software stacks can certainly be part of flowers, I care less +about them for my personal development needs/wants. You could imagine +a buttercup variant, built roughly the same but with e.g. apache. +While the intents are close, that is a different flower ... at least +until an abstraction layer is written to obviate that difference (the +clause itself being very illustrative as to what a flower *is*). + + +why is this all coded into buttercup? why not have one or more base packages? +------------------------------------------------------------------------------ + +So far all I've needed to care about was k0s.org for purposes of +flowers. Being not one to repeat code and being very much one to put +things in the right place, if there is an event to abstract the logic, +abstract I will. + + +so what's the advantage of flowers, anyway? is this just for deployment? +------------------------------------------------------------------------- + +While I've presented flowers as a deployment pattern for a website, +that is mostly for expedience and because such language is easily +understood. While of course this is directly usable for deployment, I +am more interested in classification. Its kinda like design patterns +or whatever other sorts of patterns: having a copy of the catalog +does not guarantee an understanding of taxonomy. + +There are technical advantages at looking at websites and their +deployments as evolving pattern. There is the generic: the flower; +and there is the newly deployed site. But both change and evolve. +You can make a new flower from the old. You can use a flower as part +of a flower. They become building blocks. + +I want to make something crazy called *flowerbed* which combines some +generic flower software (to be written) with wsgintegrate and a web +interface to manipulating directed graphs (also to be written). With +this and a little elbow grease and unicorn dust, you could write a +tool to allow you to make a flower (and also the website, if desired) +just by drawing a graph with a preselected set of tools and pipes. +But, as usual, postponed until needed. + + +it seems like it'd be cool if ``buttercup`` +and other flowers were insantiable TTW. +------------------------------------------- + +It does, doesn't it? You should write that! Or maybe I will someday.