Roadmap for Alpha

[ianjosephwilson]

Maybe this should be a discussion but I've been losing track of where things are at during split discussions.

I think we are getting pretty close to things being stable. This self-closing thing seems like a "huge problem" but I think even the code I ported myself would probably not be affected at all because I don't use any svg / mathml.

I think this could be a decent alpha:

• consolidate the documentation (make issue) -- Started on this a few times myself but need to revisit it and maybe start from an issue
• finish up the self-closing situation ( Split out ParseContext concept from #141 #143 ) ( Draft attempt at updating self-closing rules #141 )
• improve the error reporting ( Improve error message for unclosed components whose attribute value might have consumed the slash. #140 ) (TBD) -- I have a lot of stuff in the pipeline for this, I can start linking it into ( Expose *really good* error messages #33 )
• revisit the test suite and make sure things are consistent
  • check that coverage isn't missing anything meaningful
• performance test (something that isn't going to bog us down though, I'd almost consider putting it in another repo, maybe beta)
• finish up a few companion integrations, even if they are proof of concept (this could get pushed to beta)
  • flask
  • starlette / fastapi
  • django
  • pyramid (because I'm using that)

Major upcoming things:

• whitespace handling ( Support pretty-printing and whitespace management #54 )
• refine our tooling approach
• maybe some test refactoring (would be a good thing to do in a lull, between alpha and beta maybe)

[pauleveritt]

I have mostly resurfaced and can do a big push this week, including pushing my branch for the docs thingy.

[davepeck]

@ianjosephwilson Thank you. This is a great list!

For me, the goals of the alpha are, roughly:

• freeze the public API surface (or, mostly)
• offer a stability policy ("here's what's baked and public; here are the corners may still churn, but you probably aren't touching these corners unless your name is Paul")
• massive rev on the docs

Basically: it's usable; we wouldn't discourage adoption; etc.

Aspects of the public surface we'd want to be confident in stability of might include:

• Exactly what our parser tolerates (when is self-closing allowed; how do we handle void; etc) and how it handles edge cases (attr=value/>)
• Namespace handling at processor/render time (we handle SVG; we should handle MathML, too -- as far as I can tell, there are no tag-name case issues there, but maybe an attribute case thing for definitionURL)
• The escaping/security contract (Markup/__html__). Feels pretty baked at this point, but want to make sure we don't churn post-alpha
• Component invocation
• Context, component extension points, etc.
• Types allowed in each interpolation and their precise behavior (documentation, at minimum)
• Our exception hierarchy (Ian, I really like your hierarchy in Custom Error Handling Prototype #145 although I might want one more "root" exception to cover it all). I'm separating this from the work to raise "great" exceptions, since that could land post-alpha without breaking our public surface area.
• Whitespace handling: I wouldn't offer pretty printing in the alpha, but I would make sure we're comfortable with the default rendering behavior that we ship. (currently: just pass it through)
• Oh yeah, ship a py.typed aka be PEP-561 friendly (easy!)

From this perspective, I think a number of the other things mentioned (integrations with frameworks; perf tests; tooling updates) can maybe live in beta even though I'm excited to get there!

[ianjosephwilson]

@ianjosephwilson Thank you. This is a great list!

For me, the goals of the alpha are, roughly:

• freeze the public API surface (or, mostly)

This is a good discussion because I feel like some of the terms are a little vague. I was thinking some sort of rollout like this:

• alpha: we think this is the final api, try it out, probably don't develop against the API yet unless you really need it
• beta: we are sure this is the nearly the right api, try it out, start to develop against it but is not production ready yet
• release candidate: this is what we plan to release, no new features, try it out, should be nearly ready for production, you could try it in production if you really need it
• release: this is ready, we will provide BWC if we have to change the API, ready to go

• offer a stability policy ("here's what's baked and public; here are the corners may still churn, but you probably aren't touching these corners unless your name is Paul")
• massive rev on the docs

Basically: it's usable; we wouldn't discourage adoption; etc.

Aspects of the public surface we'd want to be confident in stability of might include:

• Exactly what our parser tolerates (when is self-closing allowed; how do we handle void; etc) and how it handles edge cases (attr=value/>)
  I think we decided and we just need to document this now.

• Namespace handling at processor/render time (we handle SVG; we should handle MathML, too -- as far as I can tell, there are no tag-name case issues there, but maybe an attribute case thing for definitionURL)

I think we might be able to pull these from the htmlspec file and create a dynamic automated test to make sure its happening for both when needed.

• The escaping/security contract (Markup/__html__). Feels pretty baked at this point, but want to make sure we don't churn post-alpha

Right, we should create a specific security test suite file for this to separate it from regular bugs. There is probably a standard method of doing this we should look into. Ie. After a release if there is a bug in that suite then we have to do a special release and notification or something.

• Component invocation
• Context, component extension points, etc.
• Types allowed in each interpolation and their precise behavior (documentation, at minimum)
• Our exception hierarchy (Ian, I really like your hierarchy in Custom Error Handling Prototype #145 although I might want one more "root" exception to cover it all). I'm separating this from the work to raise "great" exceptions, since that could land post-alpha without breaking our public surface area.
• Whitespace handling: I wouldn't offer pretty printing in the alpha, but I would make sure we're comfortable with the default rendering behavior that we ship. (currently: just pass it through)
• Oh yeah, ship a py.typed aka be PEP-561 friendly (easy!)

From this perspective, I think a number of the other things mentioned (integrations with frameworks; perf tests; tooling updates) can maybe live in beta even though I'm excited to get there!

Perf and tooling for sure but I think having the integration setup might be important so that 1. it get used at all and 2. it works as intended rather than dealing with a bunch of weird issues because the integration is confusing.

[davepeck]

Perf and tooling for sure but I think having the integration setup might be important so that 1. it get used at all and 2. it works as intended rather than dealing with a bunch of weird issues because the integration is confusing.

Yeah, I think that's fair. For me it might be both "there's an integration story with a popular framework" and "there's an integration story with a popular editor". (I'd choose Django due to personal bias, and VS Code using Koudai's t-linter.)

alpha: we think this is the final api, try it out, probably don't develop against the API yet unless you really need it
beta: we are sure this is the nearly the right api, try it out, start to develop against it but is not production ready yet

Curious what will give you confidence that tdom has "nearly the right api"?

For me, I think it's just more building with it, in a larger project context.