OpenSolaris

	/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.