feedback on the 2.0 specs

hey all. i finally had a chance to sit down with the 2.0 specs and write up 
some thoughts. i posted them on the discussion pages on the wiki, and i'll 
include them here too. thanks for writing them up, will and blake!

http://pyblosxom.sourceforge.net/wiki/index.php/Category:2.0_Planning

general:

The [[Filestat and sorting specification]] is god. We should take a closer 
look at support for programmatically creating entry lists and shepherding them 
through the serving pipeline. The spec is the right start, but support for 
other features, like flavour templates, is incomplete. Right now, plugins that 
create entries programmatically often have to reach into PyBlosxom's internals 
to get feature parity.

The "end of the year" goal is aggressive, especially since the req'ts are 
incomplete. We should try to put together a more concrete list of use cases 
and features that aren't supported now, but will be supported by 2.0. Each of 
the individual specs does this pretty well, but it'd be nice to have a (very) 
brief list of *concrete* use cases in the top-level 2.0 planning page.

We should also consider pushing out the date, especially since we all have 
pretty demanding full time jobs. :P


archives:

I understand the motivation for this, but I'm not convinced by the proposal. 
My main concern is that it's unnecessarily surprising. Site admins understand 
that adding or removing a directory can make a request for that directory 
serve a result or a 404, respectively. However, it'd probably be surprising to 
see a specific feature, like archives, trigger only when a directory doesn't 
exist.

PyBlosxom and its plugins have used parts of the path to trigger behavior like 
this for a while. There were probably never clear rules or guidelines, so this 
path usage grew organically, and different plugins used different parts of 
path. This is strange and inconsistent for new developers, site admins, *and* 
end users.

We should try to standardize this. To start, we should discuss whether parts 
of the path should *ever* be used as triggers. I think there's a strong 
argument to be made for only using path to traverse the filesystem, and using 
query parameters for triggers and everything else.

That would break backward compatibility with lots of plugins, though. One 
alternative would be a set of guidelines on which parts of paths a plugin can 
use to trigger dynamic behavior, and which parts are used as filesystem paths.

Most importantly, filesystem paths can be arbitrarily deep, so I'd propose 
that "trigger" parts of the path should always come before filesystem parts. 
We could consider only allowing the beginning part of the path, e.g.
/archive/, to be a trigger. We could consider alowing a small number of parts, 
starting from the beginning. I'm reluctant to let plugins use an arbitrary 
amount of the beginning of the path, though, since I think that starts to get 
surprising.


blog.ini:

I'm not familiar with Paste. Having said that, I think the proposal is great. 
It's simple and mirrors the Python syntax.

My one question is is how syntax errors will be handled. Will unquoted values 
be interpreted as strings? How about unquoted values in lists? I think either 
failing fast or coercing them to strings would be fine.


cache:

+1. I'm all for this. I agree with the spec, and it doesn't hurt that it's 
really well written. :P)

Incidentally, when we have a lull - after 2.0! - we could consider writing a 
memcached cache driver.


filestat:

+1. Solidifying these as callbacks will rock. It's overdue.

The callbacks should probably have different names, filelist because entries 
don't have to be files, and sortlist because it does more than sort (and 
doesn't have to sort). Maybe entry_list and top_entries or entries_to_display?

Also, I think mtime vs. ctime is one of the most confusing parts of PyBlosxom 
for new users. While we're bumping the major version, we should consider a sea 
change and add a config setting that lets users choose between ctime and 
mtime. We could even default to ctime in 2.0, but that's obviously a bigger 
decision.

We'd also want to encourage plugins that implement these callbacks to support 
both ctime and mtime.


entryparser:

Have we heard from many people who want to keep their entries in databases, or 
wherever, as opposed to on filesystems?

Just to clarify, right now, all metadata lines are required to be at the top, 
right below the title? You can't have metadata scattered through an entry, 
right? (If so, that's good. I wonder if we should even support it above the 
title, but that's mostly subjective.)

What's up with the *#markup rst* metadata line? It seems to imply that entries 
can "override" their extension and thus choose their entryparser and 
pre/postformatters. Is that right? Is that supported now? Are you considering 
it for 2.0?

Do you know if we have any users with very large entries? If so, I wonder if 
streaming support would be interesting. If an entry didn't need pre/post 
formatting, and we changed the entry parser calback signature, we could 
support streaming entryparsers so that entries don't have to be loaded into 
memory. Clients would also start seeing the page sooner.

...on second thought, I doubt that's worth doing. It's an interesting idea, 
but not really important for PyBlosxom.


templates:

Hmm. This is a good doc, but I'm unclear on what's new. The only feature that 
was new to me was scoping and function calls in variables. Is that a new 
proposal, or is it supported right now?


plugins:

We should clarify that we'll include a few mature plugins *of our choice* with 
PyBlosxom, as opposed to all mature plugins. Also, we'll only do it with the 
plugin developer's permission, since we'd have to either take over 
maintennance or add them as a committer on SourceForge. :P

BTW, I'd never really paid attention to conditionalhttp before. Does it only 
have a single, site-wide setting for Last-Modified, ETag, etc.? Does it set 
them per page? I wonder how it supports plugins like comments that can result 
in new content outside of entries.

Finally, I agree with moving the plugin registry to the wiki. Of those four 
options, it's easily the biggest bang for the buck.


-Ryan

--
http://snarfed.org/

-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2005.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/