tiddlyweb going 1.0
Chris Dent
Note: This message applies to the Python package called "tiddlyweb" which provides the core HTTP engine and storage system for the larger system known as "TiddlyWeb". It does not (yet) apply to the Python package called "tiddlywebwiki" which provides the TiddlyWiki server-side functionality.
Knowing full well that I've made the following assertion before I'll go ahead and make it again:
By January 15th I would like to declare the tiddlyweb Python package to be a) stable and b) version 1.0.
This means stabilizing the API and flushing out any remaining obvious bugs.
The tiddlyweb api consists of several parts:
* The HTTP API (the urls and methods supported, such as PUT /bags/foo/tiddlers/bar).
* The API for adding twanager commands.
* The API for the various subsystems in TidldlyWeb:
** stores
** challengers
** extractors
** serializers
** filters
** renderers
** policy handling
* Modes or idioms for adding:
** plugins
** handlers
** routes
Each of these areas have been extensively used by _me_ and to some large extent by FND and some others, but not huge amounts by the world at large. That means there are likely creepy crawlies lurking in the corners, either as bugs or mis-apprehensions about how each feature is to be used. While it would be best to get all those bugs squished before a 1.0 release, I think we've been at this long enough and it is time to freeze features, and only worry about bugs for a while.
To that end I will be following an accelerated release schedule over the next 4 weeks. If you are aware of a critical bug or mis-feature that you think should be fixed before 1.0, now is the time to speak.
Once tiddlyweb is 1.0 at least two things will happen:
* tiddlyweb will follow a linux kernel like development path: a 1.0.x branch will carry bug fixes, 1.1.x will proceed on trunk/origin/master (whatever you want to call it) with feature development. It's hoped that 1.1.x development will not happen soon.
* Energies will be focussed on the tiddlywebwiki Python package to bring it around to 1.0 status as well. This will involve a lot of work at greasing the install process and making the initial user experience as straightforward and complete as possible.
If you have questions or comments, please post, your input is not just desired, it's needed.
FND
> should be fixed before 1.0, now is the time to speak.
Something that's stung me multiple times over the last few weeks are
policy constraints.
I always have to look them up*, as their meaning is different depending
on the context (bags vs. recipes).
Initially, I was planning to resolve this problem simply by providing a
proper UI within TiddlyRecon, explaining what each item meant in the
respective context.
However, as Shatner says, it hasn't happened yet.
So, just to incite some controversy, is it really a good idea to use the
same Policy attributes on bags and recipes?
-- F.
* the docs on this are currently suboptimal - it's possible that improving
those will also lead to a simpler, more memorable mental model
chris...@gmail.com
On Thu, 17 Dec 2009, FND wrote:
> So, just to incite some controversy, is it really a good idea to use the
> same Policy attributes on bags and recipes?
Bags and Recipes don't have policy attributes, they have policies.
Policies have attributes.
I realize that's an incredibly pedantic statement, but it is an
important part of understanding how policies fit in.
One could choose to use policies on other entities too.
And as such they are generic things designed to allow the application of
generic constraints to stuff. They started out life as just for bags but
were applied to recipes when it became clear that some enterprisey
people needed to be sure none their names of stuff were being exposed.
FND
> Policies have attributes.
My apologies for being a little careless in my wording.
I of course meant to question the application of the Policy class, with
its standard set of attributes, to both bags and recipes.
Griffelspitzer.
> And as such they are generic things designed to allow the application of
> generic constraints to stuff. They started out life as just for bags [...]
This doesn't answer my question though.
I'm wondering whether it's worth compromising the semantics of recipe
constraints for the sake of using a generic concept.
I understand that this has certain benefits in terms of code complexity,
as the permissions handling doesn't need to differentiate between bags'
and recipes' constraints - but perhaps that mapping could happen
internally rather than being exposed to users?
-- F.
chris...@gmail.com
> > And as such they are generic things designed to allow the application of
> > generic constraints to stuff. They started out life as just for bags [...]
>
> This doesn't answer my question though.
Yes. I don't have one.
> I'm wondering whether it's worth compromising the semantics of recipe
> constraints for the sake of using a generic concept.
>
> I understand that this has certain benefits in terms of code complexity,
> as the permissions handling doesn't need to differentiate between bags'
> and recipes' constraints - but perhaps that mapping could happen
> internally rather than being exposed to users?
"Users" should never have to see policies. They should be able to choose
behaviors in a friendly UI which underneath that UI are then mapped to
policies[1]. In other words effort is better spent in two ways:
* Making the UI useful, friendly, effective, efficient.
* Making the core simple, patterned, idiomatic, extensible, etc.
The part you're talking about, the part in the middle where you are trying to
create code that bridges between the two is the hardest part of the job and
the one requiring the most flexibility, knowledge and learning.
This is, of course, just my opinion.
[1] The fact that this is not yet true is no reason to change the core
architecture. It is a reason to build better tools that take advantage of the
flexible architecture. This is a general rule of thumb throughout the
TiddlyWeb universe. We don't need to come up with a bunch of new stuff, we
just need to use the stuff we've got effectively.
FND
> behaviors in a friendly UI
Depends on your definition of "user". I wasn't talking about end-users
in the sense of people using the TiddlyWebWiki UI, but rather people
using twanager or accessing the HTTP API.
> The part you're talking about, the part in the middle where you are trying to
> create code that bridges between the two is the hardest part of the job and
> the one requiring the most flexibility, knowledge and learning.
True - pushing complexities towards the edges is generally preferable.
(Though in this case, I'm not convinced that the mapping is the hardest
part.)
> The fact that [there is no such UI yet] is no reason to change the core
> architecture. It is a reason to build better tools that take advantage of the
> flexible architecture.
I agree.
-- F.
chris...@gmail.com
> True - pushing complexities towards the edges is generally preferable.
> (Though in this case, I'm not convinced that the mapping is the hardest
> part.)
In any case, I've had a think about it and I think the problem is just that
the policy stuff is not been well described, or the model is weird.
We kind of think of the Policy as the thing controlling access either to the
thing or the tiddlers within it, which is a bit poly, and also not quite
right.
The Policy controls access to the things which the policy is attached to
contains. For a bag that means:
read: read the tiddlers within
write: write the tiddlers within
delete: delete the tiddlers within
create: create a tiddler within
accept: accept a tiddler without validation into
manage: manage the bag (delete it, see its definition, update its definition)
For a recipe that means:
read: read the list of bags and filters that make up the recipe
write: NOT USED: we do not write bags _into_ a recipe, they are independent
delete: NOT USED: we do not delete the bags in a recipe
create: NOT USED: we do not create bags _into_ a recipe
accept: NOT USED: we do not write anything into a recipe that is to
be validated[1]
manage: manage the recipe (delete it, change its definition)
So the difference is there, but it is based on how containing is done.
Tiddlers are in Bags. Bags are _not_ in Recipes.
[1] there is recipe validation/sanitization but it is not controlled by
policies
Tobias Beer
basics you mentioned in your first post + the detailed, yet
fundamental basics about policies are VERY helpful to understanding
how things tick... tiddlyweb-wise.
Tobias.