Skip to content

TODO.md

Latest commit

 

History

History
209 lines (151 loc) · 8.02 KB

TODO.md

File metadata and controls

209 lines (151 loc) · 8.02 KB

Hacking

Some guidelines:

  • Development on dev branch, notes in doc/dev/.rst.
  • (Semi-)Finished features in ChangeLog, unreleased versions are enclosed in round brackets.
  • Current Tasks and bugs in section below.
  • Dedicated features branches for specific tasks. Maybe dev release branches for parallel dev/maintenance.

Checklist for new features

  • Feature is placed as an addition to one main feature or sub-feature.

    Mentioned in

    First during the development in dev milestone document, and after intial release also in the main feature list and as items of changelog entries.

  • Finished feature is described

Design points:

No distinction between url paths or local file paths. Prefer for local file based defnitions for resources or API.

Initial router API consists of the generate function. Perhaps move to a schema for the attributes. Maybe combine with Sitefile schema.

Possibly for more types of use; standalone. No Sitefile.{json,yaml}?

In particular control the envelope and delivery of content. Manage style, script and maybe (later) links, metadata, and then later profiles, schema..

Ie. locate, dereference, negotiate, resolve content, etc. and serve to a suitable client e.g. browser.

Next:

  • Move to a concept of a standard file-type handler registry, posibly some magic. Use Sitefile to index (only) those resources that are linked together, likely introduce domain or site attribute (ie. specify a 'docuverse', or 'linking space' within which the hyperlinks/references can act, and which in other ways determines presentation, as apposed to the content which is in principle a set of plain text human readable and processable files).

  • Better HTTP conformance.

Think about:

  • Want to keep it lean, and simple. Sitefile currently (<0.0.5-dev) is under 350 LoC. But:

  • need to integrate concept of content-type (ie. representation vs. resource) to deal with parametrizing the publisher (routers). Currently the routers are purposely very naively implemented to focus on a generic, flexible Sitefile schema.

  • Setup some transclusion micro-protocol (over HTML+XmlHttpRequest) for dynamic branching, and mix/browser content client-side using hash-navigation, building up a client-side app essentially.

    Again, keep going for dynamic, branching literal content and build on this. Avoid creating rolodexes and card boxes.

Roadmap

Stage is in initial development. Upcoming First versions upcoming:

0.1.0

  • Milestone 1: serve a simple website of (derived) HTML, CSS, JS content
    1. Text markup languages (md, rst)
    2. Server side templates (pug)
    3. Scripts (js, coffee, requirejs)
    4. Stylesheets: SASS/SCSS, Stylus, Less
    5. Diagrams: Graphviz, PlantUML, ditaa
    6. Data: Knex (SQL ORM) and Bookshelf API (with Backbone-style REST i'face)
    7. Resources: http, cdn
    8. Services: pm2
    • Convert and edit metadata: json, yaml
    • Edit other files
    • SCM: git
  • Milestone 2: support variant resources, and data and action URL endpoints
    • Document viewer and editor.
    • Router and resource extensions; local user-defined or packaged suites.

Maybe 2017-ish.

1.0.0

  • Milestone 3: package extension routers and resource bundles
    • Lightweight Sitefile core.
    • Extension packs, suites; maybe some verticals, e.g. a GIT wiki.

Dev

Next release 0.0.5, dec 2016/jan 2017. Current: documentation and updating test setup in preparation to stabalize. Next: Work on 0.1 features.

(0.0.x)

Want most features of 0.1.0 soonish.

  • Documented features, tests and reporting on feature functionality.

(0.0.6)

  • Try to stabalize context schema. Maybe for 0.1? So routers can stabalize too. And also, nodelib, point at some things that it needs for 0.1.

Tasks and Bugs

Routers

  • TODO:route: map extensions. Ie. default spec would be something like makefile: path%.trgt: path%.src
  • TODO: map prefixes.
  • TODO: finalize 0.1.0 specifications and define BWC components/interfaces.
  • FIXME: rst2html router context is broken.
  • FIXME: markdown requires Pug router to be loaded, iow. fails w/o pug routes.
  • TODO: add something like a text: router to force play text display.
  • TODO: look at a more middleware compatible approach http://developeriq.in/articles/2015/feb/09/node-expressjs-and-mongoose-part-ii/
  • TODO: directory index/tree router

Documents

  • TODO: manage view: style and scripts. Automatic reload browser on change. See also 'App platform' task. Solve some other router and configuration issues first.
  • TODO: browser reset styles, some simple local Du/rSt styles in e.g. Stylus
  • http://asciidoctor.org/ AsciiDoc processor in Ruby? Maybe add a section of plain text markup formats.

Python Docutils (reStructuredText)

  • TODO: Compiled CSS for Docutils. SCSS or Stylus.
  • public/media/style/default.css:/* TODO: want something like LESS or SASS to build from a common src/css base... can do? */
  • ReadMe.rst:document possibilities emerge. :todo:TODO: Sitefile provides for a pre-styled CSS file
  • TODO: export some tokens (terms, titles, topics) for autolinking
  • src/dotmpe/sitefile/routers/du.coffee:XXX: get all dependencies somehow, and route them?
  • Also: export docinfo or other field maps, maybe refs, etc.
  • src/dotmpe/sitefile/routers/du.coffee:XXX: du.mpe compatible with fallback or?
  • ReadMe.rst: TODO: all docutils output formats (pxml, xml, latex, s5, html)

Markdown

  • TODO: add HTML envelope

App platform

  • Fix ext-mapping in routing, and start re-using resources; build one on another, extend.
  • PLAN: Provide for an initial customizable app stack with RequireJS, Coffee-Script, SASS/SCSS. Think about example/demo repo and keeping files low, focus on testing and documentation.
  • TODO: live customization of views.
  • TODO: components, should want to deal with optional deps. iso. req'ments.
  • FIXME: Consolidate reader.rst into package/stack.
  • XXX: maybe implement simple TODO app as a feature branch somday
  • TODO: site builds, packaging

Configuration

  • NOTE: in yaml, _1 or __1 will not work, YAML strips _ so it turns into a std. route. Not sure if this is particular to the library.

Metadata $ref resolving (JSON path refs)

  • src/dotmpe/context.coffee: # XXX this starts top-down, but forgets context. may need to globalize
  • src/dotmpe/context.coffee: if value.$ref # XXX resolve absolute JSON ref

Sitefile schema

  • TODO YAML, JSON validation. jsonary perhaps. $schema
  • src/dotmpe/sitefile/sitefile.coffee: # TODO: validate Sitefile schema
  • ReadMe.rst:TODO: load schema not just to validate Sitefile but to specify/generate/validate

On the fly reload

  • src/dotmpe/sitefile/sitefile.coffee:# XXX only reloads on src file or sitefile change
  • src/dotmpe/sitefile/sitefile.coffee:# XXX does not reload routes, code+config only
  • src/dotmpe/sitefile/sitefile.coffee:# TODO should reload sitefilerc, should reset/apply routes

Sitefile internals

  • src/dotmpe/sitefile/sitefile.coffee: # TODO Also need to refactor, and scan for defaults across dirs rootward

  • ReadMe.rst:XXX: sitefilerc will be described later, if Sitefile schema (documentation) is set up.

  • ReadMe.rst:XXX the sitefile config itself can go, be replaced by external

  • ReadMe.rst: TODO: see also sitefilerc

Client

  • TODO: look at KnockoutJS for databinding in client.

Misc

  • ReadMe.rst:XXX specs contain as little embedded metadata as possible, focus is on
  • ReadMe.rst:- redir\ specify a redirect FIXME glob behaviour?
  • ReadMe.rst:- module.export callback receives sitefile context, XXX should return::

Project tooling

  • PLAN: make some guards to determine version increment, maybe some gherkin specs. TODO: cleanup and standardize to ttxt?

  • TODO: cucumber-js coffee-script setup.

  • https://codeclimate.com/ "Automated code review for Ruby, JS, and PHP."

  • TODO: have a look again at Express middleware

    "connect-flash": "latest", "method-override": "^2.3.2", "node-uuid": "^1.4.3", "notifier": "latest"

Testing

  • Makefile:# FIXME jasmine from grunt?

.. [#] nodejs-socketio-seed <http://github.com/dotmpe/nodejs-express-socketio-seed>_