Mercurial > hg > buttercup

comparison README.txt @ 43:0c411c083fab

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
update doc
author Jeff Hammel <jhammel@mozilla.com>
date Sat, 23 Mar 2013 04:43:46 -0700
parents fe197282c615
children
comparison
equal deleted inserted replaced
42:c008855cf3a9 43:0c411c083fab
1 buttercup: a flower for k0s.org 1 buttercup: a flower for k0s.org
2 =============================== 2 ===============================
3 3
4 buttercup is a `flower <TODO>`_ that is used to bloom a website like 4 buttercup is a ``flower`` that is used to bloom a website like
5 `k0s.org <http://k0s.org>`_. There are several `python <http://python.org>`_ 5 `k0s.org <http://k0s.org>`_. There are several `python <http://python.org>`_
6 components to a buttercup website: 6 components to a buttercup website:
7 7
8 * `decoupage <http://k0s.org/portfolio/software.html#decoupage>`_: for static files and indices 8 * `decoupage <http://k0s.org/portfolio/software.html#decoupage>`_: for static files and indices
9 - `montage <http://k0s.org/portfolio/software.html#montage>`_for image galleries 9 - `montage <http://k0s.org/portfolio/software.html#montage>`_for image galleries
11 * `bitsyblog <http://k0s.org/portfolio/software.html#bitsblog>`_ for blogging 11 * `bitsyblog <http://k0s.org/portfolio/software.html#bitsblog>`_ for blogging
12 * a set of mercurial repositories 12 * a set of mercurial repositories
13 * software demos: 13 * software demos:
14 - anagram 14 - anagram
15 - wordstream 15 - wordstream
16 * and so forth
17
16 18
17 why is buttercup so messy? 19 why is buttercup so messy?
18 -------------------------- 20 --------------------------
19 21
20 Easy. Its the backport of a highly specific website to a flower. The 22 Easy. Its the backport of a highly specific website to a flower. The
21 buttercup flower is in fact a study in botany, useful in the study of 23 buttercup flower is in fact a study in botany, useful in the study of
22 species, but probably less interesting as a practical deployment. 24 species, but probably less interesting as a practical deployment for
25 widescale use.
23 26
24 27
25 does buttercup work yet? 28 does buttercup work yet?
26 ------------------------ 29 ------------------------
27 30
28 No. It is still a work in progress. 31 Depends on what you want to do. Right now, what `buttercup` does is
32 mostly best gleaned from the source code. I hope to change this with time.
33
34
35 what is a flower?
36 -----------------
37
38 Every website has, in essence, an intent, a purpose the website serves
39 and tools and method with which to enact such purpose. While the
40 intent itself belongs to the domain of natural language, the tools
41 (read: web applications) and how they are deployed (including
42 e.g. request dispatching) should be catalogued in a manner actionable
43 to machine.
44
45 A flower is a deployment pattern of a website.
46
47 The deployment pattern contains information about what tools (usually,
48 python packages) are required, how they are set up for an instance of
49 the pattern, and how they interact with each other; but it does not
50 contain content (including site-static content) save in abstract.
51
52 For example, imagine you are making a very simple website where you
53 want static files and directories served from the path info segment
54 ``/``, a blog served at ``/blog``, and the ability to upload files to
55 whatever directory ``/`` corresponds to on the web server's
56 filesystem. (Let's also make it real simple and completely ignore auth
57 which you should definitely *NOT* do if you were to deploy this flower.)
58 If you were me, you'd probably use
59 `decoupage <http://k0s.org/hg/decoupage/>`_
60 for the file server,
61 `bitsyblog <http://k0s.org/hg/bitsyblog/>`_
62 for the blog software,
63 and `uploader <http://k0s.org/hg/uploader/>`_
64 for the file upload widget.
65 This would be a *flower*. It has a clear intent -- a blog and file
66 server -- and a set of tools that manifests that intent.
67 You could have variations on this, such as mounting the blog at ``/``
68 and files at ``/files``, but since the deployment intentions are the
69 same (the tools interact with each other the same way, from a machine
70 point of view). It would be of merit to write this example flower,
71 but such shall be reserved for an exercise to the reader (which may
72 very well be me).
73
74
75 I'm a programmer. Can you give me a briefer explanation?
76 ---------------------------------------------------------
77
78 Assuming you know object-oriented programming, a flower would be the
79 *class* of the website, and the website would be the instance.
80
81
82 what should a flower look like?
83 -------------------------------
84
85 As said, buttercup is currently messy. It was written as a marriage
86 between a very minimalistic need of saving some time on very specific
87 problems and the abstract idea of flowers which I didn't have time to
88 delve in. Voila! Software is born. In addition, even had I the best
89 intentions and time available to them, technologies such as more
90 recent pip changes were not available at the time of crafting.
91
92 Also, I'm lazy and/or don't have time to work on it.
93
94 In essence, ``buttercup`` has (or should have):
95
96 - a list of software requirements (that should be installed in
97 ``--develop`` mode in a ``virtualenv``)
98 - a method of "fitting the pipes" with
99 `wsgintegrate <http://k0s.org/hg/wsgintegrate/>`_
100 - (and there's also something about ensuring system packages are
101 installed and what not; see e.g
102 http://k0s.org/hg/buttercup/file/c008855cf3a9/buttercup/PACKAGES.txt
103 though I believe it is yet unused)
104
105 If I were to incorporate these as concepts into ``buttercup``, I would
106 make the flower have:
107
108 - a ``pip``
109 `requirements file <http://www.pip-installer.org/en/latest/requirements.html>`_
110
111 - a skeleton of a ``wsgintegrate`` ``.ini`` file and methods to
112 interpolate this skeleton to the instance
113
114 - *and*, very importantly but very forgettably, tools to port
115 production changes to the ``wsgintegrate`` configuration back to
116 the flower.
117
118 - (in addition formalize the system packages (obviously per platform)
119 needed and how to check for them install them etc. Not sure if
120 there is stuff out there for this; outside of the fact that several
121 platforms have to be supported, its a pain. Vagrant and puppet seem
122 close...ish. Silverlining?)
123
124 Obviously, this sort of make-up works for ``buttercup``. It would not
125 work so well if, say, you were using apache + mod_wsgi vs
126 e.g. wsgintegrate and a standalone WSGI server. While the latter (and
127 other) software stacks can certainly be part of flowers, I care less
128 about them for my personal development needs/wants. You could imagine
129 a buttercup variant, built roughly the same but with e.g. apache.
130 While the intents are close, that is a different flower ... at least
131 until an abstraction layer is written to obviate that difference (the
132 clause itself being very illustrative as to what a flower *is*).
133
134
135 why is this all coded into buttercup? why not have one or more base packages?
136 ------------------------------------------------------------------------------
137
138 So far all I've needed to care about was k0s.org for purposes of
139 flowers. Being not one to repeat code and being very much one to put
140 things in the right place, if there is an event to abstract the logic,
141 abstract I will.
142
143
144 so what's the advantage of flowers, anyway? is this just for deployment?
145 -------------------------------------------------------------------------
146
147 While I've presented flowers as a deployment pattern for a website,
148 that is mostly for expedience and because such language is easily
149 understood. While of course this is directly usable for deployment, I
150 am more interested in classification. Its kinda like design patterns
151 or whatever other sorts of patterns: having a copy of the catalog
152 does not guarantee an understanding of taxonomy.
153
154 There are technical advantages at looking at websites and their
155 deployments as evolving pattern. There is the generic: the flower;
156 and there is the newly deployed site. But both change and evolve.
157 You can make a new flower from the old. You can use a flower as part
158 of a flower. They become building blocks.
159
160 I want to make something crazy called *flowerbed* which combines some
161 generic flower software (to be written) with wsgintegrate and a web
162 interface to manipulating directed graphs (also to be written). With
163 this and a little elbow grease and unicorn dust, you could write a
164 tool to allow you to make a flower (and also the website, if desired)
165 just by drawing a graph with a preselected set of tools and pipes.
166 But, as usual, postponed until needed.
167
168
169 it seems like it'd be cool if ``buttercup``
170 and other flowers were insantiable TTW.
171 -------------------------------------------
172
173 It does, doesn't it? You should write that! Or maybe I will someday.