gdl
    title     = AMQ RFC001
    subtitle  = The OpenAMQ RFC system
    product   = OpenAMQ
    author    = iMatix Corporation <amq@imatix.com>
    date      = 2004/10/01
    copyright = Copyright (c) 2004 JPMorgan
    version   = 0.1
end gdl

Cover
*****

State of this Document
======================

This document is a request for comments.  Distribution of this document is
currently limited to iMatix and JPMorgan internal use.

This document describes a work in progress.
This document is a formal standard.
This document is ready for review.

Copyright Notice
================

This document is copyright (c) 2004 JPMorgan Inc.

Authors
=======

This document was written by Pieter Hintjens <ph@imatix.com>.

Abstract
========

The OpenAMQ RFC system is modelled on existing RFC systems.  Our goal is
to create a light-weight but useful basis for capturing the discussions,
proposals, and implementations behind key aspects of the OpenAMQ product.
This document defines the OpenAMQ RFC system itself.

Introduction
************

Problem Statement
=================

We face a challenging process of designing and implementing OpenAMQ, a
product that is ambitious and complex.  Our design process is heavily
based on dialogue, prototyping, and rapid refinement of solutions.  We
do not have the luxury of spending a significant effort in a formal
design phase that would document every aspect of the product before
development started on it.

Our current tools are written documentation (e.g. the AMQ Draft Design),
email lists, irc, and face to face discussion.

We need a more formal way of capturing specific aspects of the design
discussion, so that these aspects can be refined and documented in a
single well-defined place.

Argumentation
=============

We could use many tools for capturing technical discussions: wiki, email,
word-processors, memos.  All of these have advantages and disadvantages.
Email is trivial but has a low signal ratio.  Wiki is centralised but
does not work off-line, nor does it have any change management support
(i.e. one cannot easily retrieve the history of changes).  Word processors
are good for final text but are poor for collaborative work.

We come thus to the Internet standard: simple text documents that can be
edited with any text editor and which are held in a revision-control
system (such as CVS).

A simple text file has the disadvantage of being poor input for final
document production.  I.e. such files must be manually reformatted if
one is to use them in a word-processed document.

The solution to this is to use a tool that recognises the text format and
automatically prepares it in different forms.  iMatix has such a tool,
gurudoc, part of our OSS Base toolkit.  The current memo is written in
gurudoc format.

Basic Proposal
==============

Our proposal is to use a simple text format based on the iMatix gurudoc
standard.  This is aimed at making text documents that are readable in
their original form, but which can be automatically processed into
high-quality HTML, OpenOffice, or PDF formats.

Additionally, we propose a standard naming and storage scheme that ensures
that the documents we make are accessible, safe, and can be easily revised
by multiple people without risk of conflict or damage.

Finally we propose a simple procedure to ensure that the "ownership" of
a document is well-defined, and that the transition of a document from
speculative proposal to formal documentation is clear and documented.

Design Proposal
***************

Definitions and References
==========================

The use and syntax of gurudoc documents is described in the documentation
for iMatix Base.

Objectives
==========

These are the objectives of the OpenAMQ RFC system:

1. To define a standard process for documenting the design process behind
   the OpenAMQ product.
2. To create a library of reference material that describes the actual
   implementations, along with alternative and speculative proposals.
3. To allow the automatic production of technical documentation on the
   product.

Architecture
============

The architecture is based on these elements:

 - A standard syntax, structure, and style guide for documents called
   "AMQ RFCs".
 - A standard archival system.
 - A standard toolset, being the iMatix gurudoc tool.
 - A standard process for writing, reviewing, and publishing AMQ RFCs.

Proof and Demonstration
=======================

We will consider the current proposal to be proven when we have a
collection of AMQ RFCs that describes a significant part of the OpenAMQ
product, and which has been reviewed and accepted by the OpenAMQ
development team including iMatix and JPMorgan engineers.

Detailed Proposal
=================

Document Syntax, Structure, and Style
-------------------------------------

1. Write the AMQ RFCs in English, using a maximum line length of 75
   characters.
2. The AMQ RFCs will be written in US-ASCII-7 and without tabs or other
   special characters
3. Structure the AMQ RFC using the template provided in RFC000.  Add more
   detailed headings if necessary, and remove headings that are not needed.
4. When referring to an AMQ RFC in a document, use the form "AMQ_RFCnnn".

Document Archival
-----------------

1. The AMQ RFCs are numbered sequentially from AMQ_RFC001 (this document).
2. The AMQ RFCs are named amq_rfcnnn.txt where "nnn" is the AMQ RFC number.
3. The AMQ RFCs are stored along with the project source files in the
   directory amq/openamq/rfc/, using whatever revision control system is
   used for the project sources.

Document Toolset
----------------

1. The AMQ RFCs are written using the iMatix gurudoc format, allowing
   automatic conversion to HTML, OpenOffice, etc.
2. The AMQ RFCs are catalogued in a Boom project definition using the boom
   class "gurudoc text".

Document Process
----------------

1. The AMQ RFC numbers will be assigned informally on a first-come,
   first-served basis.
2. The AMQ RFC archive is owned by a single person, who will be assigned by
   the project manager to ensure that AMQ RFC numbers are
   correctly assigned, that the AMQ RFC project file is correctly updated,
   and that documents conform to the specified standards.
3. The AMQ RFC archive will be regularly published to one or more web sites
   for read-only access by interested parties.  This process will be
   implemented as needed over time.
4. All team members are encouraged to comment the documents.  Comments are
   always placed at the end in the section marked "Comments".  The authors
   of the document may at their discretion remove comments from the
   document, especially if the comments request corrections or changes that
   are then implemented.
5. Extended discussions should be conducted by email and the results of
   these discussions captured in the AMQ RFC.
6. Whenever a new AMQ RFC is created, the author(s) will copy it to the
   current email list used for project discussions.  When an AMQ RFC is
   updated, the authors may simply announce the update, or may copy the
   entire document, depending on the amount of change.
7. The project definition (project.pdl) for the AMQ RFC project will define
   the current set of AMQ RFCs.

Alternatives
============

We do not propose any alternatives at this moment.

Security Considerations
=======================

This proposal does not have any specific security considerations.

Comments on this Document
*************************

Date, name
==========

No comments at present.
