Subversion Repositories tendra.SVN

Outline Plan for Forthcoming Restructuring
==========================================

For context: I shall be keeping notes and plans in plain-text, while
making architectural or design decisions. I plan to be spending some
time working out things here; I'd rather keep them archived in SVN and
have them archived than lost.

There is currently no documentation of high-level design or other
developer documentation, aside from the grammars and formats of the
various tools in use. I'm planning to restructure the source somewhat,
and would like to make these things clear.

Eventually, this information will make its way to the TenDRA website
in the form of developer documentation, along with block diagrams and
other such things.

I'm separating my voice here: "I" refers to me personally (Katherine),
where I am not speaking on behalf of the entire project; "we" refers
to the project as a whole.

I'd like to build upon the vast amount of work Jeroen has put into the
project, and rather than discard his efforts, to make use of them -
without which, I don't believe this next stage for TenDRA would happen.


Stages
------

An overview of intended stages during restructuring:

 1. Lay out goals for the project.

    I've sketched out a list of these (at higher resolution than the
    three overseeing principles, which I don't want to change), and
    grouped them into sections.

    These are prioritised into chronological stages, and will form a
    guide for a marketing plan - whilst we are non-commercial, we can
    still use ideas from the commercial world for organising
    ourselves.

    This includes laying out phases for deployment, and identifying
    what demographics are attracted to each stage. For example, right
    now, the focus is on development, and so the project needs to be
    made more attractive to developers.

 2. Document existing High-Level design.

    This is documentation of block diagrams, and information flow
    within and between programs, at various levels of detail.

    The purpose of this is to assist in decisions for restructuring
    (which, currently, are estimates only), and to provide a stable
    base of documentation from which the developer resources may grow.

 3. Restructure directories. (More about this below)

    In accordance with the current goal of being made attractive to
    developers, and - perhaps more importantly - understandable by
    developers, I'm going to split the TenDRA code base up into formally
    separated units.

    Currently the code is kept roughly separate, as with any decently
    organised code base. However, I'd like the distinction to be visible
    to the developer in the form of concretely-defined APIs, and
    entirely separate build trees.

    With this split, the source becomes more digestible, but, more
    importantly, it will appeal to a wider audience. For example, a
    person interested in working with TDF may not be interested in the
    rest of the compiler. Previously, I suspect they were scared off
    from using it by the other unrelated things - and this applies to
    people interested in the other things, but not TDF!

    It is important to note that the information flow within each
    program will not change here: this is splitting up and formalising
    the divisions, not refactoring processes within each program.

 4. Bring the source tree to conform to a directory layout style guide.

    This is not a code style guide; it's a higher level up. This means
    that each directory should identify its purpose, and relate itself
    to a high-level design, for a conceptual overview.

    This is partially done (to great effect) with README files: I'd like
    to formalise this, and correlate it with a new overview.

    I suspect we're recreating documentation which did originally
    exist, and has been long-lost. I can only assume that developer
    documentation was not released when TenDRA was open-sourced.

    Meanwhile, after the directory restructuring, we'd need to recreate
    these anyway.

    This will break the build: I'm more concerned about getting things
    in the right place, than keeping it continuously buildable.

 5. Fix up build system.

    A lot of work has been done here, replacing the original build
    system with a newer one. After restructuring the directories, this
    will have broken drastically, and needs re-creating for each
    individual program.

    Here I'd also like to start on making the system continuously
    buildable; from this point, commits should not break the build,
    unless they are multistage architectural changes.

Work past this point is beyond the scope of this document.