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.