/arc/handbook/opinion @(#) 1.10 03/02/06
This file is an ASCII template for writing an architecture
opinion.
Read the comments, and look for the lines bracketed by <...> that
tell where your insertions go. Don't forget to remove the
comments and run spell on the opinion before sending it out for
review. Also remove this line and everything above it.
_________________________________________________________________
sun microsystems Systems Architecture Committee
_________________________________________________________________
Subject: ${NAME}
Put the name of the project being reviewed here in title
form, with major words capitalized and omitting the case
number. E.g.:
Solaris on Fusion
Submitted by: ${SUBMITTER}
Name of main submitter. If more than one, note "et al"
File: ${ARC}/${CASE}/opinion.ascii
The name of the file holding this text. The standard location is:
"case number" "/" and "opinion.ascii"; no alteration is necessary
unless you're using a different filename.
Date:
Put the date we reached the decision being documented here.
If it's being revised, include the original date and the last
revision date as in: `February 30th, 1991, Revised March 32nd, 1991'.
As a style matter, the "st", "nd", "rd", "th" suffixes to the date
should be added as appropriate. No period follows the date.
Committee: ${COMMITTEE}
names of committee members who participated in the decision
List the majority first, in alphabetical order. Except, place the name
of the person writing the majority opinion first. List the minority
second, after a "." and the word "Minority:". Again, place the name
of the author of the minority opinion first, but then alphabetically.
E.g.: Joe Blow, Allan Able, Charlie Carlson. Minority: George Wrong,
Devils Advocate. List abstentions last.
Interns should not be included in the committee list unless an intern
wrote the opinion. In that situation, list the intern in parentheses
after the case owner. E.g.:
August Case-Owner (opinion written by Aspiring Intern)
Note that /committee contains a list of committee
members in a form suitable for inclusion here. The review minutes
are another source for this information.
Product Approval Committee: ${PACname} (${PACabbr})
${PACemail}
E-mail alias of PAC(s) that should care about this case
(Probably a list of community discussion forums that want to
be affiliated with this case)
1. Summary
<In this section, put a few sentence synopsis of the proposal>.
Make the description ample enough for a wide audience, as this
will be used in other places as a quick summary of this project.
2. Decision & Precedence Information
In this section, state the following in this order. One sentence
paragraphs are best.
* Whether or not the proposal is accepted. [If there are mandatory
modifications that the acceptance is conditional upon, state that
they are specified in Appendix A. If the proposal is accepted
unconditionally, simply state that it's accepted.]
E.g.:
<The project is approved as specified in reference [1], but as modified by
the required technical changes listed in Appendix A below.>
* The classification of the deliverable as a major [incompatible],
minor [compatible enhancement], or micro [a "replicant" like a
port or driver; or a bug fix] and for what consolidation
[OpenSolaris-ON, a specific unbundled consolidation, ...].
E.g.:
<The project may be delivered in a minor release of the OpenSolaris
ON Consolidation.>
* The list of projects that must be delivered no later than this project.
(If none, omit this paragraph.) List this in the format shown, with
project IDs or case numbers to the left and the text of the description
(usually the case's title) to the right.
E.g.,
<The project depends on the following other project and
may not be delivered before it.
PSARC/1994/038 Making FNS XFN Compliant
>
3. Interfaces
The project exports the following interfaces.
This section should identify the project's interfaces and their
classifications in the interface taxonomy. A tabular format is
most appropriate for this information, listing imported interfaces
in a separate table from interfaces being exported.
Two skeleton tables appear below. Use either format. (One is
better looking, but the other is easier to produce and edit.)
Fill them in with export and import information.
Try to make comments succinct. If you need so much room that the
table won't fit on a standard 80-character line, let the cell span
multiple lines. If you need more space still (try not to), don't
embed the comment proper in the table, but instead number it to
match a numbered paragraph (in `.IP 1.' format) appearing
immediately below the table.
Useful information to include in the Comments field includes:
- What kind of interface it is (function, library, file, ...)
- A cross reference to a reference material entry describing it
___________________________________________________________________________
| Interfaces Exported |
___________________________________________________________________________
| Interface Name | Classification | Comment |
___________________________________________________________________________
| /etc/foobar | Stable | Defined by foobar(4) manpage |
| /etc/barfo | Project Private | Defined by foobar(4) manpage |
___________________________________________________________________________
___________________________________________________________________________
Interfaces Imported
_________________________________________________________________________
| Interface Name | Classification | Comment |
| my_get_foobar() | Consolidation Private | Part of module foo |
_________________________________________________________________________
4. Opinion
<Place the text of any opinion here.>
Place the text of any opinion here. Note that if the decision is
to reject then opinion text is mandatory. The decision should,
where possible and especially for a rejection, express the principles
that underly the decision. If the application of the principle is
limited or "special" for this case, be sure to identify that.
This section should also capture the content and resolution of the major
issues uncovered during the committee's deliberations. Unless there
are only one or two issues, use a subsection for each, by adding
headers for each issue or related group of issues; e.g.:
4.1 Issue Title
<Text about that issue here.>
5. Minority Opinion(s)
<If there is a dissent, the text for the dissent goes here.>
If none, so state.
6. Advisory Information
<Any editorial or advisory information goes here.>
If there is editorial, or advisory information the committee wishes
to express, place that here. This is information that may be used
by the project or management as they see fit. It could include
observations about costs, techniques, suggestions for different
design decisions, and the like. This section is where advice to
product approval committees about the project's ramifications should go.
7. Appendices
7.1. Appendix A: Technical Changes Required
<If there are mandatory technical changes, enumerate them here.>
<If there are none, so state.>
The formatting that works best is:
1. Indented paragraph that is ever so long, so when it gets to the
end of the line, it continues nicely indented below.
2. fmt(1) can format such a paragraph with it's "crown mode" -c
option.
7.2. Appendix B: Technical Changes Advised
<As in Appendix A, list specific changes that the committee advises.>
If there are none, so state.
7.3. Appendix C: Reference Material
List reference material. Start by saying that, unless stated
otherwise, path names are relative to the case directory and give
the path name of that directory. Then list each reference using
the enumeration formatting described for Appendix A.
Unless otherwise noted, materials are relative to the case directory.
(The logistics of which are still being worked out on the OpenSolaris
site...)
<List reference material. This usually will include the submission material.>
1. Functional Spec, 20 Questions ...
2. Team's discussion of name space issues. File: materials/naming.
3. Proposals for naming options. File: materials/naming_options.
4. mail log - ./mail
The references must include the project's specification and should
include the case's mail file, and other submission material as
appropriate. It is often useful to include references to related
cases, as well. This section should help guide the reader through
the material, so include a short explanation with each reference.
