LSARC 20q template update [LSARC/2007/577 FastTrack timeout 10/16/2007]
Alan Coopersmith
Alan.Coopersmith at Sun.COM
Wed Oct 3 21:33:24 PDT 2007
[Manually sending to opensolaris-arc at opensolaris.org since we
don't have LSARC-ext yet. This is the 20 questions template
used for LSARC reviews, which include most desktop components,
developer tools, and system management tools, including some
projects that would be targeting OpenSolaris. Simple cases
that can be handled as fasttracks don't fill this out but most
full cases do.
I realize the template still reads as the questions asked by a
Sun ARC ("How does this benefit Sun?" and all the internal URL
references) - I haven't tried to solve that in this iteration,
hopefully the URL's are simply transposable to external references.
If anyone wants to suggest changes to make it more community
oriented, we'll consider them, but I didn't see it as a requirement
for this round, especially since LSARC works with projects from
multiple communities. -alan- ]
Template Version: @(#)sac_nextcase 1.64 07/13/07 SMI
This information is Copyright 2007 Sun Microsystems
1. Introduction
1.1. Project/Component Working Name:
LSARC 20q template update
1.2. Name of Document Author/Supplier:
Author: Alan Coopersmith
1.3 Date of This Document:
03 October, 2007
4. Technical Description
I've noticed in various reviews lately things in the 20 questions template
that have gotten out of date, and a discussion today with a project team
who contacted LSARC-chair about why the 20q's Windows sections didn't mention
Vista, even though they still ask about Windows 3.1 prompted me to sit down
and take a pass through the document cleaning up the obvious things.
I'd like to ask others take a look to see if they disagree with my changes
or see others to suggest. I've filed this as a fasttrack with a 2 week
timeout instead of the multi-month sessions I know have gone into previous
20q revisions since I just want to fix the most obvious things to make this
easier on the project teams and us.
Specifically in scope:
- Updating to the new interface taxonomy (Committed/Uncommited/Volatile)
- Recognizing that much of what we do is both open source and community
participation - not all closed/proprietary.
- Keeping up with obvious changes in the technology - x64, Niagara,
Linux, virtualization, etc.
- Dropping ancient technologies that are no longer relevant (C interfaces
no longer need to be compilable with original-K&R/pre-ANSI-C89
compilers, Windows 3.1 is long past dead, etc.)
- Making resources more easily accessible to our working-from-everywhere
workforce - http URL's over NFS mounts whereever possible
Specifically out of scope:
- Replacing all references with external URL's
- Trying to coalesce into one unified 20q for all ARC's
- Replacing SVR4 packaging references with IPS or any other future
Solaris packaging system
The case materials directory will include the current draft document and
diffs from the present version as updates are made.
--- /shared/sac/LSARC/20questions 2005-10-03 08:20:54.000000000 -0700
+++ 20q 2007-10-03 19:31:44.139383000 -0700
@@ -1,1406 +1,1395 @@
-@(#) LSARC Questions Version 2.0t @(#)LSARC 1.29 05/10/02
-__________________________________________________________________
-
-ARC Templates are Sun Proprietary: Internal Use Only
+@(#) LSARC Questions Version 2.0u %W% %E%
__________________________________________________________________
#ifdef REMOVE
#ifdef ADVICE
There are logically 3 documents here:
- 1. Background info (mostly in the intro and some of inline, #ifdef ADVICE).
- 2. The questionnaire itself. Consider it "Things to Specify if Applicable."
+ 1. Background info (mostly in the intro and some of inline,
+ #ifdef ADVICE).
+ 2. The questionnaire itself. Consider it "Things to Specify
+ if Applicable."
3. Other Considerations (mostly at the end, #ifdef ADVICE).
The last of these might be a separate document, but is here to
ease editing and review. Our advice is only that; if you have
reasons to deviate from our advice, discuss that with the ARC
in your materials and during your review.
#endif
INTRODUCTION: Here is a comprehensive list of questions that
LSARC asks of project presenters. Ideally, all this
information would already be in the specifications that tell
engineers what to implement, testers what to test, and
management what the project entails, so they can schedule
- resources. The http://sac.eng/HTML/FuncSpec.html template may
+ resources. The http://sac.eng.sun.com/HTML/FuncSpec.html template may
therefore substitute for this questionnaire, if it sufficiently
addresses every applicable aspect. Even a functional spec
follwing the PLC template may substitute, though due to the
hardware orientation of that template it's less likely
that all the issues the ARC cares about will be addressed.
Before submitting a PLC-template function spec, please
read through these questions and ensure all applicable
ones are addressed in the spec.
PLEASE PROVIDE POINTERS: On this questionnaire, tell which
sections of of the specifications provide which answers. There
is no need to duplicate text, but don't forget to submit the
specifications on-line for archive and review purposes. Any
answers not explicit in the project specifications may be
provided here.
MECHANICS: Please add any answers and return this questionnaire
in ASCII to ease searching, reading remotely, and quoting in
E-mail. Start each answer flush left, and keep lines < 80
columns. (The tables may be in separate files, and should be,
if they have to be wider. Diagrams may be separate files, but
in any case must be printable on Solaris; see Q20.2.)
SHRINK-TO-FIT: Not every question will pertain to every
project, nor will be a significant consideration for that
project. Tell us which questions you deem inapplicable, so we
can tell they weren't merely neglected. If an entire set of
questions is inapplicable to this project, note "N/A" for the
main question and delete subordinate questions.
#ifdef WINDOWS
The full Questionnaire also includes questions for projects
with Microsoft Windows components (#ifdef WINDOWS), based on
1.2PC 7/12/95. Some section numbers append W for Windows or S
- for Solaris, to differentiate if both are answered. If your
- project does not include Windows components, you may use
+ for Solaris, Linux, and other Unixes, to differentiate if both
+ are answered. If your project does not include Windows components,
+ you may use
/usr/ccs/bin/unifdef -t -UWINDOWS
as a filter to remove the Microsoft Windows questions.
#endif
An ARC member will be named "owner" of the case at the
end of the project's pre-inception discussion, if not sooner. You
may ask that member (or the Chair) for help interpreting these
questions or their relevance to your project.
Sections 9 through 17 address the details of a project's
environment, interfaces, and so forth; it is understood that
many of these issues will be unresolved at the time of an
inception review. They must, however, be answerable at
commitment review, and should be addressed to the extent
possible at inception review. You may present this information
in any order or form that seems appropriate.
An introduction to the ARC review process is in
- /shared/sac/doc/Client.Handbook/
- The distinction between Inception and Commitment reviews is on
- pages 7 and 8. /shared/sac should work in the Engineering
- domain. In other domains, substitute /net/sac.eng/export/sac
- or use SunWeb's
- http://sac.eng/sac
+ http://sac.eng.sun.com/arc/
- Projects that are modifying existing, ARC-approved, projects
+ Projects that are modifying existing, ARC-approved projects
should review the former ARC opinion and materials, and not
restate what is identical about the projects; limit discussion
to what is new -- being dropped, replaced, changed, or extended
-- and describe the outcome of advice on the previous projects'
opinions.
If a previous release exists, but was unapproved, the committee
needs proposed stability classification and specifications of
*all* the product or project's interfaces. Also describe the
differences proposed, and the migration plan (e.g.,
backwards-compatibility features, translating former
configuration files).
Use an Inception Review to validate your approach, identify
likely issues, and determine what information will be needed to
achieve Commitment. Answer "UNKNOWN" (not N/A) if the
information might be known (and applicable) later.
Answer Question #9 thoroughly before Commitment Review.
Projects cannot be approved until this information is
complete. If the project has too much to describe all at once,
it is probably too much to review all at once; discuss with
your case owner subdividing the review into multiple meetings,
and perhaps even separate projects of a common "program".
If this project has had a Review and is returning for another
review, clearly mark any new or changed material with a date,
change bars, or whatever.
#endif /* REMOVE the above; '/usr/ccs/bin/unifdef -t -UREMOVE' can do it. */
__________________________________________________________________
-All ARC Project Materials are Sun Proprietary: Need-to-Know
-__________________________________________________________________
-
0. Remind us:
0.1 The case number for this project?
??ARC 200x/xxx
0.2 This questionnaire is for an
[ ] Inception Review
or
[ ] Commitment Review
0.3 Name(s) of person(s) answering the questions?
+ 0.4 Are these case materials considered public or confidential?
+
1. What specifically is the proposal that we are reviewing?
1.1 The case owner will need to put a 1 to 4 paragraph description at the
top of the Opinion document. Suggest text for it. Please be
specific about deliverable components and their interfaces.
#ifdef ADVICE
- An example Summary may be found in the
- /shared/sac/PSARC/1995/224/opinion.*
+ An example Summary may be found in the opinion.* files in
+ http://sac.eng.sun.com/PSARC/1995/224/
#endif
1.2 Is this a new product, or a change to a pre-existing one? If it is a
change, would you consider it a "major", "minor", or "micro" change
- and why? (See the document in /shared/sac/doc/release.taxonomy.)
+ and why? (See the release type definitions in
+ http://sac.eng.sun.com/BestPractices/release_taxonomy.html )
2. What is the motivation for it? What are the expected benefits
for Sun? By what criteria will you judge its success?
3. The plan:
3.1 Who (what groups in what business units) are working on it?
3.2 What is the current status?
3.3 Has a design review been done?
#ifdef ADVICE
(Note that LSARC is not a design review service, but an
architecture/interface review board; ARC members may be
invited to design reviews, however.)
#endif
- 3.4 What Product Approval Committee (PAC) do you expect to approve this project?
+ 3.4 What Product Approval Committee (PAC) do you expect to approve this
+ project?
#ifdef ADVICE
PACs are registered with the Sun PLCPtool
http://sunplcptool.central.sun.com/
#endif
4. Related Projects:
4.1 What not-yet-delivered Sun projects (libraries, hardware, etc.) does
this project depend upon (i.e., need to be successful)?
4.2 What non-Sun projects does this project depend upon?
4.3 What other projects depend on this one?
4.4 What other active projects at Sun are related to your project, and
how are they related?
4.5 What future projects should be started or avoided to help your project
succeed, and why?
+ 4.6 What open source communities does this project interact with?
+
5. What technical approach has been selected by the project?
#ifdef ADVICE
This is an open-ended question seeking an implementation overview.
Answers might cover:
* a "make versus buy" decision;
* a client/server or multi-level model, and the determination
of the boundaries between the components;
* CASE tools, if the choice restricts capabilities;
* implementing some project-specific service rather than using or
extending a generic system service;
* other approaches that are more common or arguably superior.
Case materials must distinguish this project (which is subject for
approval now) from wishes, hopes or plans, though it's fine to
outline possibilities for future evolution.
#endif
6. How is the project delivered into the system?
Is it bundled or unbundled?
What are your delivery vehicles (WOS, CTEAM...)
Identify package abbreviations, directory names,
library names, databases, etc.
#ifdef WINDOWS
For Microsoft Windows components, name the DLLs, VxDs, etc.
In this list, highlight any components (executables, libraries, etc.)
which require special consideration at installation time. For example,
if the project installs a third-party library, what provisions are made
for handling version mismatches with any previously-installed copies
merging of new database entries?
#endif
7. Hardware Platform Dependencies:
7.1 What are the project's hardware platform dependencies, including Sun
or third-party add-on hardware that is explicitly supported.
- 7.2 Are Solaris components expected to work on SPARC and Intel?
+ 7.2 Are Solaris components expected to work on SPARC and x86?
If not, why? What will be affected in porting? Any problems if
porting to another architecture were desirable?
7.3 Are there issues with "binary" interfaces, which would be incompatible
on various instruction set architectures?
#ifdef WINDOWS
7.4W For Microsoft Windows components, what is the minimal hardware
- configuration supported (e.g., Intel 386 with 8mb of memory)?
+ configuration supported (e.g., Pentium with 128mb of memory)?
#endif
8. Compatibility and Interoperability
(Consider a compatibility matrix, if the information is nontrivial.)
8.1 OS compatibility:
8.1.1 For Solaris components, what Solaris release(s) does it run on
or work with?
- 8.1.2 Does it run on Linux? What distribution(s)n and version(s)?
+ 8.1.2 Does it run on Linux? What distribution(s) and version(s)?
8.1.3 Might the project need any extra adaptation to work successfully
with future (i.e., later) releases? patches?
#ifdef WINDOWS
- 8.1.3 For Microsoft Windows components, does it run on Windows 3.x?
- Windows 95/98/ME? NT/W2K/XP?
+ 8.1.3 For Microsoft Windows components, what Windows releases does it work on?
+ Client-oriented releases (98/ME/XP/Vista)? Server releases (2000/2003)?
8.2W Does it depend on features and software that exist only in certain
versions of Windows, such as networking features not in XP Home?
#else
- 8.2S Do Solaris components depend on kernel features not in the default
- kernel (e.g. Berkeley compatibility package, /usr/ccs, /usr/ucblib,
- optional loadable kernel modules)? What packages or clusters must be
installed
- first (if the "core" set of packages is insufficient)? Do the
+ 8.2S Do Solaris components depend on OS features not in the core OS
+ (e.g. Berkeley compatibility package, /usr/ccs, /usr/ucblib,
+ optional loadable kernel modules)? What packages or clusters must be
+ installed first (if the "core" set of packages is insufficient)? Do the
packages express those dependencies explicitly?
- 8.3 Do Solaris components use any system interfaces, commands, or features
- not in X/Open CAE SUSv2 and XNS5?
+ 8.3 Do Solaris components use any system interfaces, commands, or features
+ not in POSIX or the Single Unix Specification? What is the minimum
+ version of those standards required? (POSIX.1-1990, UNIX98, UNIX2003?)
#ifdef ADVICE
Read "man standards" for what those abbreviations mean.
Projects using system (or other project) interfaces that are
- neither Standard nor Stable (formerly Public) should explain
+ neither Standard nor Committed (formerly Public/Stable) should explain
to the ARC why the risk of being broken by an incompatible change
- are sufficiently low, and how the risk will be managed. Before
- release, but typically long after ARC Commitment,
- the project team should submit to the ARC for review the
- "ABI application certification" results for all executables
- and libraries that run on Solaris. See
- http://www.sun.com/developers/tools/appcer/t .
+ are sufficiently low, and how the risk will be managed. One way to
+ verify interface usage is to review "ABI application certification"
+ results for all executables and libraries that run on Solaris. See
+ http://www.sun.com/developers/tools/appcert .
#endif
8.4 Do Linux components use any interfaces, commands, or features not in
- the Linux System Base 1.3?
+ the Linux System Base? What is the minimum LSB version required?
#ifdef ADVICE
http://www.linuxbase.org/
#endif
#endif /* WINDOWS */
8.4 With what releases of what other projects or products does this
project interoperate? Using what interfaces? (Provide reference
to ARC case approving these interfaces or a specification and
proposed stability classification for the interfaces.)
8.5 What internationalization (I18n) issues are involved? What languages
*can* be supported by localization without modifying the base product,
whether or not a localization is currently planned? What I18N interfaces
will the project adhere to? If strings are used, how are they accessed
- -- Solaris-mostly gettext(), X/Open catgets(), GNU gettext? What items and
- interfaces are (or are not) being internationalized?
+ -- Solaris-mostly gettext(), X/Open catgets(), GNU gettext? What items
+ and interfaces are (or are not) being internationalized?
#ifdef ADVICE
See the Internationalization Best Practice document.
- http://sac.eng/cgi-bin/bp.cgi?NAME=I18N.bp
+ http://sac.eng.sun.com/cgi-bin/bp.cgi?NAME=I18N.bp
#endif
8.6 Are there any existing or proposed standards it conforms to or
- deviates from? Examples: SPARC/Intel ABI, OMG/CORBA, POSIX, SVID,
- XPG (X/Open Portability Guide), RFCs, national or international
- standards. Include version numbers.
+ deviates from? Examples: SPARC/x86 ABI, POSIX, Open Group standards,
+ IETF RFCs, national or international standards. Include version numbers.
8.7 Can this version co-exist or interoperate with earlier and later
versions? with alternative implementations (perhaps by other vendors)?
Is switching between installed versions or implementations possible?
What is involved?
8.8 Does the project move, disable, delete, circumvent or change any files,
components, or services outside the project?
8.9 Does it use any interfaces (for example, a driver using kernel
structures) that are private to another consolidation? read or write
/dev/kmem? trap directly into the kernel, instead of via libc functions?
#ifdef ADVICE
These are all serious architectural issues, and will need
justification and discussion.
#endif
8.10 What components (e.g., libraries or packages) are shared with other
projects or products?
8.11 Can customization (e.g., OEM relabeling) be accomplished via resource
files that are separable from the source code?
8.12 Device Drivers:
8.12.1 Does this project deliver any device drivers?
8.12.2 Does it conform to the Solaris DDI/DKI (manual sections 9e, 9f, & 9s)?
8.12.3 Does it pass "DDICT" DDI compliance tool (available on Solaris DDK)?
9. Technical Content
9.1 Architecture Diagram: Include in case materials an Architecture
Diagram, showing the major components, major interfaces, and all
customer-visible interfaces and inter-project interfaces. Give each
a number or brief name for use in the Interface Table below.
#ifdef ADVICE
The ARC definition of "interface" is broad -- any syntax or
semantics that anything outside your project could depend on.
It is not limited to APIs nor even project boundaries that are
customer-visible. (See the sections that follow.)
A good example Architecture Diagram is in
- /shared/sac/LSARC/1995/132/commit.materials/interface.ps
+ http://sac.eng.sun.com/LSARC/1995/132/commit.materials/interface.ps
Get help from your case owner in completing the Architecture
Diagram.
#endif
9.2 Interface Table: Include Imported and Exported Interface Tables
showing all customer-visible interfaces and inter-project interfaces and
significant internal interfaces (inter-subsystem and inter-invocation).
- Interfaces are not just function calls. Include user interfaces (graphical,
- browser based, character based), configuration files, XML schemas,
- network protocols, port numbers, etc.
+ Interfaces are not just function calls. Include user interfaces
+ (graphical, browser based, character based), configuration files,
+ XML DTD's, database schemas, network protocols, port numbers, etc.
#ifdef ADVICE
- Interfaces are not just function calls. Include user interfaces (graphical,
- browser based, character based), configuration files, XML schemas,
- network protocols, port numbers, etc.
-
The following sections ask for more detail and help "brainstorm"
additional interfaces.
Divide your table into sections that will be helpful to the reviewers
(e.g., client-side versus server-side). Subdivide your table or use
another method to distinguish Imported and Exported interfaces and
"what kind" of component or interface. For example: Protocols,
Libraries, Daemons, Command Line Utilities (applications,
configuration or administration tools), Graphical User Interfaces,
Character User Interfaces, Command Line Interpreters, Input/Output
File Formats, Configuration Files, Databases, Log files. If it is
too much to describe all at once, it is probably too much to review
all at once; discuss with your case owner subdividing the review,
perhaps into separate projects of a common "program".
Propose for *each* interface a stability/commitment classification
- -- "Standard", "Stable" (formerly Public), "Evolving", "Unstable"
- (intentionally Uncommitted), Contract Private, etc. -- per the SAC
+ -- "Standard", "Committed" (formerly Public/Stable), "Uncommitted"
+ (formerly Unstable), Contract Private, etc. -- per the SAC
Interface Taxonomy document in
- http://sac.eng/cgi-bin/bp.cgi?NAME=interface_taxonomy.bp
+ http://sac.eng.sun.com/cgi-bin/bp.cgi?NAME=interface_taxonomy.bp
A "Contract Private" interface (between projects) requires a
contract (see the template in /shared/sac/arc/ARC-Templates/contract)
be submitted and reviewed.
#endif
EXPORTED INTERFACES:
Proposed Specified Former Stability
Interface Stability in what Classification
Name Classification document? or Other Comments
------------------ ------------- -------------- --------------------
Your project will not be easily reviewed without information here
------------------ ------------- -------------- --------------------
IMPORTED INTERFACES:
Proposed Specified in Former Stability,
Interface New Stability what case no. Contract Number,
Name Classification &/or document? or Other Comments
------------------ -------------- -------------- --------------------
Your project will not be easily reviewed without information here
------------------ ------------- -------------- --------------------
#ifdef ADVICE
A good example Interface Table is in
- /shared/sac/arc/LSARC/1995/132/commit.materials/interface.ps
+ http://sac.eng.sun.com/LSARC/1995/132/commit.materials/interface.ps
It uses letters to tie the table to the Architecture Diagram.
A project can't be approved until the interfaces are enumerated
and assigned stability classifications and -- where appropriate -- a
specification of the syntax and semantics is submitted and reviewed.
Get help from your case owner in completing the interface table.
For a Standard interface, a pointer to the specification (with
version number or date) is usually sufficient. Some standards lack
bindings to a specific programming language; if you've chosen syntax,
arguments, names, or numbers, they're not Standard (but are probably
Public or Evolving). Also document any differences between the
specification and the implementation -- implementation-specific
details, unimplemented features, extensions, requirements,
assumptions.
- For a Stable interface, a reasonably-brief specification must be
+ For a "Committed" interface, a reasonably-brief specification must be
submitted with the case materials, and reviewed by the committee.
Customer documentation is also required.
- "Evolving", "Unstable", and "External" interfaces also require a
+ "Uncomitted" and "Volatile" interfaces also require a
specification be submitted and reviewed. Customer documentation is
also expected. It should for all stability classifications, but
- must for Evolving or Unstable interfaces, describe the risk that in
+ must for Uncommitted or Volatile interfaces, describe the risk that in
a future release the interface may be changed or dropped; this is
best done by using the terms defined in the Solaris attributes(5)
man page.
For a "Committed Private" interface, the ARC will at least assure
that the interface can satisfy its purpose and support evolution so
that "normal use" will be sufficiently seamless between invocations,
between hosts, and across releases.
For a "Contracted" interface, the specification already agreed
between the parties should be reviewed by the ARC. The ARC will at
least assure that the interface can satisfy its purpose and support
evolution in the way described in the contract.
For an "Imported" interface, the goal is to specify what aspects
of the interface must not change, in order to avoid breaking your
implementation.
#endif
9.3 Identify names and contents of packages, directories, libraries,
databases, etc. Identify package abbreviations (SUNWxxx) and
contents figuratively ("configuration command line utilities").
#ifdef ADVICE
The table may be integrated with the Interface Table or separate,
but must be complete. If the project is to deliver any contents
that have not been presented to the committee before approval,
they must be added, perhaps as a fast track; talk to the case
owner.
SAC advice about packaging is in
- /shared/sac/doc/packaging.rules
- and /shared/sac/PSARC/1993/271/materials
+ http://sac.eng.sun.com/cgi-bin/bp.cgi?NAME=packaging-1.bp
+ and http://sac.eng.sun.com/PSARC/1993/271/materials
- SAC's filesystem layout guidelines (such as they are) are in
- /shared/sac/doc/directory.layout/dirlayout.txt
+ SAC's filesystem layout guidelines for Solaris are in
+ http://sac.eng.sun.com/cgi-bin/bp.cgi?NAME=install_locations.bp
Here's a quick reference for installation locations:
Type of File If Bundled If Unbundled
============================= =============== ============
user-invoked executables /usr/bin/ /opt/SUNWxxx/bin/
system administration utilities /usr/sbin/ /opt/SUNWxxx/sbin/
daemons, libraries /usr/lib/ /opt/SUNWxxx/lib/
configuration files /etc/ /etc/opt/SUNWxxx/
changing files (logs, databases) /var/ /var/opt/SUNWxxx/
SUNWxxx is normally the package abbreviation, but is sometimes an
"umbrella" package name, so related packages are grouped. When this
is done, version-number-specific subdirectories are advised, so that
multiple versions can simultaneously find their compatible files.
Any program invoked automatically when appropriate is effectively a
daemon, and should live in /usr/lib. Also, no code names must appear
in the final product. Subdirectories of these installation locations
may be used when several files are being added.
+
+ Installation location and packaging guidelines for Linux are in:
+ http://sac.eng.sun.com/WSARC/2004/304/inception.materials/current
+ http://sac.eng.sun.com/WSARC/2004/009/materials/current
#endif
9.4 Package manifest:
#ifdef ADVICE
This may be provided in a separate file and referenced here.
A package manifest should list the name and file type of every file
in every package that is part of the project. Give each package
abbreviation (SUNWxxx) and whether it is required, recommended, or
optional. Identify dependencies between packages stated by the
packages.
At Commitment Review, a draft should be available. Before release,
but typically long after ARC Commitment, the project
team should submit to the ARC the final package manifest, generally
from the pkgmap(4) files.
An exceptionally nice Packaging list is in:
- /shared/sac/LSARC/1995/132/commit.materials/package.ps
+ http://sac.eng.sun.com/LSARC/1995/132/commit.materials/package.ps
#endif
10. The operational environment:
#ifdef ADVICE
(Each of the following questions should be answered for every component
of the project to which it applies. For example, a project with
multiple Solaris applications would specify the exit status of them
all. Manpages commonly present some of this information, but be sure
the remaining questions are answered for those components.)
#endif
10.1 Command line or calling syntax: What options/operands are supported?
#ifndef WINDOWS
- 10.1S Do they conform to PSARC/1999/645 command syntax guidelines, an
extension of
- the Single Unix Specifications rules? Are any of the "CLIP" extensions
- to the SUS guidelines used?
+ 10.1S Do they conform to PSARC/1999/645 command syntax guidelines, an
+ extension of the Single Unix Specifications rules? Are any of the
+ "CLIP" extensions to the SUS guidelines used?
#ifdef ADVICE
In particular, note the length limit: from 2 to 9 characters.
Guideline 14 suggests a command that takes subcommands (a la sccs)
for grouping similar operations and avoiding long command names.
#endif
#endif
- 10.1.1 Is there support for standard forms, e.g. X11(7) manpage's
+ 10.1.1 Is there support for standard forms, e.g. X11(5) manpage's
"-display", etc.? If not, why not?
10.1.2 Are these options propagated to sub-environments?
10.2 Can it be included in a shell pipeline? How does it use standard
input, output and error?
10.3 Environment Variables:
10.3.1 What environment variables are used? Describe values and semantics.
10.3.2 What is the default behavior if the environment variable is not set?
#ifdef ADVICE
In general, environment variables aren't good interfaces: they're
- inconvenient, not very dynamic, not entirely MT-safe, one big namespace. If
- necessary at all, make them optional (unneeded for the typical user).
+ inconvenient, not very dynamic, not entirely MT-safe, one big
+ namespace. If necessary at all, make them optional (unneeded for
+ the typical user).
#endif
10.3.3 What environment variables are set?
- 10.4 For Solaris programs, what are their exit status values? What nonzero
- status values have what meanings?
+ 10.4 For Solaris, Linux, or other Unix programs, what are their exit
+ status values? What nonzero status values have what meanings?
#ifdef WINDOWS
10.5W What inter-component Windows messages are sent or intercepted?
#else
- 10.5S Signals issued? Signals caught? (See "man(5) signal".) What are
+ 10.5S Signals issued? Signals caught? (See "man signal".) What are
their semantics?
#ifdef ADVICE
For example, daemons normally reread their configuration files when
they catch SIGHUP. Do your daemons do that? Why not? Programs
normally clean up and exit when they receive SIGINT (typically from
typing a Ctrl-C), but debuggers do not.
#endif
#endif
10.6 Device drivers directly used (e.g. /dev/audio)?
#ifdef WINDOWS
10.7W SYSTEM.INI, WIN.INI or other resource/configuration files or databases?
Describe any files used between invocations.
#else
10.7S .rc/defaults files, Java properties, GNOME GConf keys
or other resource/configuration files or databases?
Describe any files used between invocations.
#endif
10.8 Does it use any "hidden" files (filename begins with "."), system
files, or temporary files?
10.9 Does it use any locking files? Does it use Solaris locking
facilities?
#ifdef ADVICE
fcntl(2) has long been the POSIX compliant interface for locking;
XPG4.2 adds lockf(3C) which is less complicated. If the project
uses locking, also answer #17.4.
#endif
10.10 Can it execute remotely? In a distributed fashion? Is the user
aware that the tool is executing remotely?
#ifdef WINDOWS
10.11W For each Windows component (EXE, DLL or VxD) identify the name
of the component and module identifier (EXE/DLL) or VxD ID (VxD)?
If a module provides a plug-compatible replacement for a standard
system component, identify the component and its version. Indicate
whether VxD IDs are officially registered.
#else
- 10.11S Solaris Libraries
+ 10.11S Solaris/Linux/Unix Libraries
If you have code, include output from both "dump -Lv" and "ldd";
but note that the ARC wants to know what the project will deliver,
regardless of what developers currently have.
10.11.1 What dynamic (aka "shared") libraries does it use directly or
indirectly, including via dlopen/dlsym(3x)?
10.11.2 With what -R options will executables be built?
10.11.3 Does it use any static libraries?
10.11.4 What libraries does your project export?
#ifdef ADVICE
- If your project exports Solaris libraries:
+ If your project exports Solaris libraries:
+ (most, but not all, of these apply to Linux & other Unixes as well)
A. SAC prefers dynamic (aka "shared") libraries only, to reduce disk
and memory footprint and to insulate applications from future
implementation changes in the library (picked up automatically).
B. The library must include a version number, so that any necessary
future incompatible change can be recognized as such.
C. Review the Solaris Linker and Libraries Guide and follow
the Library and Shared Object Requirements Best Practice
- http://sac.eng/cgi-bin/bp.cgi?NAME=Libraries.bp
+ http://sac.eng.sun.com/cgi-bin/bp.cgi?NAME=Libraries.bp
D. Use the -R flag when linking to unbundled
libraries, rather than depending on users to set LD_LIBRARY_PATH.
The $ORIGIN construct can allow a product's binaries to find
its libraries even if the install root directory is changed.
- F. C header files should work with all cc's -X modes and with C++.
+ F. C header files should work with both Sun cc and gcc in both
+ C89 & C99 modes and with C++.
PSARC/1991/041/final.guidelines lists requirements on header files.
For details and other advice not yet binding on non-ON projects, see
- http://jurassic.eng/shared/ON/general_docs/cstyle.ms.ps
- G. Unless you're shipping the .o files, use "strip -x" to remove
- symbol table info that is useless without the .o files.
+ http://jurassic.eng.sun.com/shared/ON/general_docs/cstyle.ms.ps
+ G. Libraries containing public interfaces should be provided for all
+ supported ABI's on the platform unless there is a compelling reason
+ not to. For Solaris, this includes 32-bit SPARC, 64-bit SPARC,
+ 32-bit x86, and 64-bit x64.
H. Consider using "mcs -c" to merge identification comments.
I. C++ implementation and interfaces are more problematic; see
LSARC/1993/571 and PSARC/2002/348
J. If your library can't run in all locales, discuss that with the ARC.
K. We advise all libraries shipped as part of Solaris to be made "large
file aware" (meaning, able to use files > 2GB, per PSARC/1995/289).
L. In library routines, pipes (and pretty much everything else)
should generally be opened with the close-on-exec flag.
#endif
#endif /* WINDOWS */
10.12 Does your project use or ship database or persistent storage software?
If not, skip the rest of this section.
10.12.1 What software does it use?
10.12.2 Does it meet the SAC Policy on using standard databases?
- (see the Database Policy at
http://sac.eng/cgi-bin/bp.cgi?NAME=dbpolicy.bp )
+ (see the Database Policy at
+ http://sac.eng.sun.com/cgi-bin/bp.cgi?NAME=dbpolicy.bp )
If NO, please provide the reason:
[ ] does not meet technical requirements (please specify)
[ ] product already shipping with non-compliant technology
[ ] customer requires we use a specific database
[ ] other (please describe)
10.12.3 Is the database technology available for customer use?
10.12.4 Does the customer have to explicitly manage/administer the technology?
11. System Administration Interfaces:
#ifdef ADVICE
NOTE: For an explanation of Sun's packaging technology and
- standard package construction approaches see the Solaris 2.6
+ standard package construction approaches see the Solaris 10
Application Packaging Developers Guide at:
- http://docs.sun.com:80/ab2/coll.45.4/PACKINSTALL/@Ab2TocView?
+ http://docs.sun.com/app/docs/doc/817-0406
For the package partition rules see:
- /net/benet.Eng/benet/Packaging/SW_Pkg_Rqrmts,v4.0.ps
+ http://solaris.eng.sun.com/benet/Packaging/SW_Pkg_Rqrmts,v4_0.pdf
#endif
11.1 How will the project's deliverables be installed?
11.2 How will the project's deliverables be uninstalled?
#ifdef ADVICE
Solaris products normally install via pkgadd (either directly or
- using swmtool) and uninstall with pkgrm. Install scripts are not
- interactive.
+ under the control of an installer UI) and uninstall with pkgrm.
+ Install scripts are not interactive and must not assume they are
+ running in the target environment due to features such as Jumpstart
+ and Live Upgrade.
#endif
11.3 How will the project's deliverables be configured and reconfigured?
11.4 Does it need installation within any global system tables?
Does your package edit existing files in a common directory
(/etc/vfstab for example)? If so, how do you remove your edits
when your package is removed? If your package is reinstalled
over itself, does it recognize that the edits are already there
or does it make all new entries?
#ifdef WINDOWS
What Microsoft Windows registry entries are created or modified?
#endif
#ifdef ADVICE
If an entry needs to be added to /etc/system in support of the
new solid state fanbelt, it's important that the line not be
- added over and over with every execution. The awk class action
- script that would demonstrate this idempotency would look like
- this:
-
- # /etc/system
- !install
- BEGIN { Line = "forceload: drv/fanbelt"; Inserted="false" }
-
- /^forceload: drv\/fanbelt/ { Inserted="true" } { print; }
-
- END { if (Inserted=="false") { print "forceload: drv/fanbelt" } }
- !remove
- /^forceload: drv\/fanbelt/ { next; } { print; }
-
- If the awk class were not being used, the conventional class
- action script to do the job would look like this:
-
- # i.forceld
- # Ignore stdin since there's only one file in this class anyway and
- # we know what it is.
- nawk '
- BEGIN { Line = "forceload: drv/fanbelt"; Inserted="false" }
-
- /^forceload: drv\/fanbelt/ { Inserted="true" } { print; }
-
- END { if (Inserted=="false") { print "forceload: drv/fanbelt" }
- }
- ' < ${PKG_INSTALL_ROOT}/etc/system >
-${PKG_INSTALL_ROOT}/etc/system.new
-
- mv ${PKG_INSTALL_ROOT}/etc/system.new ${PKG_INSTALL_ROOT}/etc/system
-
- And the removal script would look like this.
-
- #r.forceld
- # Ignore stdin since there's only one file in this class anyway and
- # we know what it is.
- awk '
- /^forceload: drv\/fanbelt/ { next; } { print; }
- ' < ${PKG_INSTALL_ROOT}/etc/system > ${PKG_INSTALL_ROOT}/etc/system.new
-
- mv ${PKG_INSTALL_ROOT}/etc/system.new ${PKG_INSTALL_ROOT}/etc/system
-
- Note that these scripts always check to see if the job has
- already been done. If it has, they make no modifications.
+ added over and over with every execution. Solaris package class
+ action scripts must be carefully constructed to work with
+ systems using zones, Live Upgrade, Jumpstart, diskless clients,
+ and a variety of other install/upgrade schemes.
#endif
11.5 Does your package use components of other unbundled packages?
If so, how do you find those packages?
#ifdef ADVICE
More and more of our unbundled packages are relocatable so that
admins can use their filesystem space more efficiently. If the
package you need has been relocated, you need to use the pkg*
interfaces to find it. This usually happens at install time
but may also be used periodically in case a package you need
gets moved.
For instance:
$ pkginfo -x SUNWjdk.* | nawk ' /SUNW/{printf(" %s", $1) } '
returns all instances of SUNWjdk on the current host. Pkgparam
can then be used to find the VERSION and BASEDIR for each
instance.
#endif
11.6 Can your product be installed to an alternate filesystem (using
"pkgadd -R") for use with diskless/auto clients or live upgrade?
#ifdef ADVICE
Don't think that just because you are shipping a server product
that it will never be installed with pkgadd's "-R" option.
That's how jumpstart installs software to the server and how
live upgrade does low-downtime system upgrades!
If there are various package scripts (preinstall, postremove, etc)
that presume "/" to be the root of the target filesystem, your
package cannot be installed to a client nor is it jumpstart
compatible. The root of the target filesystem is guaranteed
to be ${PKG_INSTALL_ROOT:-/} in package scripts, not "/".
#endif
11.7 Can your product be installed anywhere on the target system and
still function (is it relocatable)? (BASEDIR)
#ifdef ADVICE
The administrator may not have enough room in your default
base directory. If your product must be there and only there
then it is not relocatable and that is a problem.
NOTE: The "-R" option to pkgadd does not relocate, it selects a
client filesystem. Administrators will relocate this package by
editing the "basedir=" entry in an admin file like
/var/sadm/install/admin/default.
#endif
11.7.1 Has your project changed or introduced any package procedural
scripts (postinstall, preremove, etc)?
If YES, are these scripts well-behaved with respect to
alternate roots? That is, when these packages are added
or removed using -R, do they cause any changes to be made to /?
The correct answers are either "No" or "Yes, Yes, and No".
#ifdef ADVICE
This question is necessary to ensure that packages follow the rules
necessary for Live Upgrade and for clients.
#endif
11.8 Even relocatable packages may have one or two elements that
*must* go in a certain place (/etc files for example). Are
these "absolute" elements in the pkgmap or are they being
installed with a postinstall script? If installed with a
postinstall, how does the administrator check their integrity
(how does pkgchk know about them)?
#ifdef ADVICE
If you deliver root and /usr files in the same package, your
package *must* be installed on a host with root and /usr local
(you must document this). On Solaris 2.6, such packages can be
installed to a diskless or autoclient successfully only if the
package is installed to the client from the server using "-R".
If the package is a part of Solaris, Solaris rules apply - root
goes into one package, /usr into another and /opt into another.
See
- /net/benet.Eng/benet/Packaging/SW_Pkg_Rqrmts,v4.0.ps
+ http://solaris.eng.sun.com/benet/Packaging/SW_Pkg_Rqrmts,v4_0.pdf
for details
#endif
11.9 How does a new version of your package upgrade a prior version?
#ifdef ADVICE
When a new version of your package is installed to replace an
old version (an upgrade), the old version *must* be removed
otherwise old patches will be able to clobber your new code.
Some teams make the mistake of writing postremove scripts that
delete required databases making upgrade nearly impossible.
You want to make sure that you can inform the old package that
it is being upgraded so that persistent data can be retained
across the upgrade. For details, see the Application Packaging
- Developers Guide for Solarism Advanced Package Generation
+ Developers Guide for Solaris: Advanced Package Generation
Techniques, Upgrading Packages. This explanation is good except
that a checkinstall script should be used to construct the
upgrade script since the checkinstall is guaranteed to run at
install time.
NOTE: This upgrade will result in a package instance on the
filesystem with a ".2" tagged onto the end. That's OK. The
argument you pass to the packaging commands is a package
instance not a package name.
#endif
11.10 Does your package replace a filesystem object delivered by a
prior package? If so, how do you inform the other package that
it doesn't own this file anymore? How do you return the
original package to its original state if your package is
pkgrm'd?
#ifdef ADVICE
This is very tricky because a future patch to the original
package can replace the original package's file (breaking your
product). This should be avoided like a rabid dog! If you must
do this, you must make a contract with the producers of the
package you are modifying. They will have to provide two sets
of patches, one with a hole where your file would be (patch A)
and one with the old file (patch B). Patch A will obsolete
patch B and your product will need to deliver patch A as a part
of your product.
If you actually replace the old file using patch A, your life
is a little simpler - the old package now owns your new file
and the other team delivers it. If you just use the patch as a
placeholder to prohibit other patch B's, your package will need
to do more work. It will need to store the old file in the
$PKGSAV directory using a preinstall script and use removef to
delete that file from the old package. In a postremove script,
your package will restore the old file to its original location
and use installf to register it with its original package
again.
#endif
11.11 Have you grouped generic functionalities that may be used by
other projects into their own packages (KLG widgets, a
third-party set of device drivers)? If not how do other
projects know this generic functionality is installed? Are you
using existing classes and libraries as far as possible?
- 11.12 How is it started? For a daemon: does it use inetd? If not, why not?
+ 11.12 How is it started?
#ifdef WINDOWS
For Microsoft Windows components which are automatically started, what
mechanism is used to do so? For components which are started
interactively, what program group entry is used? Does the component
include any mechanism for implicit starting, e.g. by association with a
file type?
+#else
+ For a daemon: does it use SMF (if on Solaris) or inetd?
+ If not, why not? If SMF, does it comply with the SMF best
+ practices in http://sac.eng.sun.com/cgi-bin/bp.cgi?NAME=SMF.bp ?
+
+#ifdef ADVICE
+ SMF is required for any service that may be installed on Solaris 10
+ or later, even if an rc script is also delivered for older releases.
+ The committee will want to know your service FMRI, any configurable
+ properties, and the roles which may configure it.
+#endif
#endif
11.13 Does it use a naming service such as NIS, DNS, LDAP? Directly,
or through the name service switch?
11.14 What are its on-going maintenance requirements (e.g. keeping global
tables up to date, trimming files)?
#ifdef ADVICE
The committee advises low-volume logging to use the system logging
daemon; see syslog(3). For high-volume logging, the committee
wants on-going maintenance to be automated; projects might allow
the user to select a maximum size that automatically gets truncated
to the most recent or oldest entries; or the project may provide a
script or procedure for performing the truncation. Consider the
reliability of the truncation, so that entries cannot be lost if
they are produced during the truncation.
#endif
11.15 Can administration be done from a remote machine? How?
#ifdef ADVICE
When setting X's DISPLAY variable for a remote execution of an
administration GUI is recommended, the committee advises that the GUI
display in the window title the hostname (of the system being
administered).
#endif
11.16 Can all GUI administration also be performed without the GUI? How?
#ifdef ADVICE
The committee often advises that administration be performable via
a character-only interface (Command line interpreter, or
command-line utilities), as well, since system administrators
sometimes have only a terminal or laptop computer available.
+ Users who need accessibility helpers to interact with the computer
+ often also benefit from character interfaces, making this in many
+ cases a requirement to meet government regulations such as the
+ U.S. Section 508 and similar rules in Europe.
Curses is another option, but admins can't build shell scripts on
it.
#endif
11.17 What command or scripting language is used?
- 11.18 Does the project include runtime license checking? How is it accomplished?
+ 11.18 Does the project include runtime license checking? Why?
+ How is it accomplished? How does it cope with changes of
+ the underlying system due to hardware replacement or virtualization?
11.19 Are there any restrictions or other architectural effects from
- contractual obligations, copyright restrictions, or technology
- royalty structure?
+ contractual obligations, copyright restrictions, technology
+ royalty structure, or open source license requirements?
12. The Window System/Desktop Operational Environment:
12.0 Does the project include a GUI (Graphical User Interface)?
If not, say "NONE" and remove all this section's subsections.
12.1 If the project includes a GUI (Graphical User Interface), case
materials should summarize the GUI's "User Model" in a few pages; that
is, the objects that the user sees or must know about, their logical
state, and the operations the user may perform on them.
#ifdef ADVICE
User's Guides, which describe a lot of mechanics, are often too
large. If you must point the committee to a large document, tell us
what pages or sections include what information that we need.
#endif
12.2 Do the GUI components share the Look and Feel of their product?
In other words, does each component appear to be part of the same
product family?
12.3 Have the GUI components had Human Computer Interaction (HCI) usability
consultation? What recommendations were and were not heeded?
#ifdef ADVICE
The committee recommends that every GUI seek HCI consultation.
HCI advice should be followed or discussed with the ARC.
For management applications, the interface should be reviewed
by the UIRB.
#endif
#ifndef WINDOWS /* The following is NOT for Windows, but Solaris */
12.4S X resources/defaults: Are they supported? What is the
application's "class" name? What resources does it depend on?
Are the resources propagated to sub-environments?
#ifdef ADVICE
The location of the X resource files and resources documented for
customers should be listed on the manpage. Resources named *only*
in the X resource file are Private.
#endif
12.5S X atoms: What X atoms--properties, selection targets, types--does it
depend on? Which ones does it export, and what are their types?
How does it respond to property change notification and ICCCM client
- messages? (E.g. Do you respond to "save workspace"?)
+ messages? (E.g. Do you respond to "save workspace"?) Do the
+ properties need to be visible across multiple labeled zones in
+ a trusted desktop?
#ifdef ADVICE
- Private X11 atom names should use a prefix registered
- with the X Consortium, such as _SUN_, and a project-specific prefix.
+ Private X11 atom names should use a prefix registered with the
+ X.Org Foundation, such as _SUN_, and a project-specific prefix.
#endif
12.6S What window-system toolkit does your project depend on?
12.7S What specific desktop integration work is planned? (GNOME examples:
Nautilus icons for new data types, .desktop files to make applications
show up in the menus, panel "applets")
12.7S What X extensions does it use (e.g. GLX, SHM, DGA, RENDER,
Multi-Buffering)? (Hint: use "xdpyinfo")
12.8S How many colormap entries does it use? How does it share
them? Does it rely on CDE color allocation? Is your project
tested with both 24 bit TrueColor and 8 bit PseudoColor default visuals?
#ifdef ADVICE
The committee advises projects to minimize the number of
colors consumed, since there are still a lot of 8-bit frame buffers
out there.
#endif
12.9S Describe your project's support for User Interface facilities
including Help, Undo, Cut/Paste, Drag and Drop, Props, Find, Stop?
#ifdef ADVICE
If projects do not support Help and Undo, explain why not.
Cut/Paste: text widgets normally support it for you. If this works,
but you have no non-text support for Cut/Paste, say "text-only".
#endif
12.10S When your windows are stretched ("maximized"), do your widgets
expand to use the extra screen real estate? Is that part of GUI
- testing?
+ testing? What happens when you maximize in Xinerama mode?
#ifdef ADVICE
Programmatic adaptation of window sizing and layout is also helpful
when the GUI is localized.
#endif
- 12.11S Will it work with remote displays, such as SunRays and X terminals?
+ 12.11S Will it work with remote and/or low-bandwidth displays, such as
+ Sun Rays, VNC viewers, and remote X servers?
12.12S Desktop Environments:
12.12.1 Does the GUI run correctly under both the default CDE window
manager (dtwm) and the default GNOME window manager (metacity?)
+ On Linux systems, does it run with the default KDE window manager?
#ifdef ADVICE
Really everything should work with any ICCCM-compliant window manager,
- but these two are the most important to verify. Java applications
+ but these are the most important to verify. Java applications
have often had troubles with different window managers.
#endif
12.12.2 Are the GUIs compliant with the style guides for the look-and-feel
employed?
12.13 Is the application usable with accessibility aids like screen readers
and magnifiers?
#ifdef ADVICE
- If you're not using gtk++ or Java -- for example, using Motif --
- it will be a problem. See http://accessibility.eng/ for more
+ If you're not using gtk+ or Java -- for example, using Motif --
+ it will be a problem. See http://accessibility.eng.sun.com/ for more
advice and contacts.
#endif
#else /* below is for Microsoft WINDOWS */
12.4W Describe your project's support for User Interface facilities
12.5W Are drag 'n' drop and cut 'n' paste supported where meaningful?
12.6W Is each GUI compliant with the Windows Style Guide?
12.7W If your software implements any Windows or other PC API or protocol for
use by Solaris-based components, what subset of that API or protocol is
supported? Do the semantics diverge from those published for that API
or protocol?
12.8W If your software provides access to Solaris resources or services to
Windows-based clients by wrapping those services in a Windows or other
PC API or protocol, what subset of that API or protocol is supported?
- 12.9W Is it compatible with SoftWindows (Apple Macintosh Windows emulation),
- SunPC, and Wine (Linux Windows emulation)? If not, what technical
- aspects preclude compatibility and what would it take to remove the
+ 12.9W Is it compatible with Windows emulation (such as Wine) or virtualized
+ Windows (such as under VMWare)? If not, what technical aspects
+ preclude compatibility and what would it take to remove the
incompatibility?
+ 12.10W Does it run well in remote Windows display environments such as
+ Windows RDP, Sun Secure Global Desktop (SGD, aka Tarantella), or
+ Citrix? If not, what technical aspects cause problems and what
+ would it take to resolve them?
+
#endif /* WINDOWS */
13. Brainstorming Interfaces (exported and imported):
Include in your Interface Table any of the following that apply. You
may comment on them here, if you wish.
13.1 Exported Library APIs and ABIs exposed to customers
13.1.1 The name of the library
13.1.2 The installation location for the library
13.1.3 The prefix(es) reserved for use by the library and its header files.
13.1.4 The syntax and semantics of every symbol exported by the library.
#ifdef ADVICE
Provide a manpage for each function, plus one for the whole library
(which names the file(s) to #include and the linking instructions).
#endif
13.1.5 Compile time symbols (#defines or #ifdefs) defined by the project?
13.1.6 Are there any library or headerfile symbols that don't start with one
of those prefixes?
#ifdef ADVICE
The committee recommends testing for unexpected library symbols.
#endif
13.2 Protocols (public or private, including RPCs)
#ifdef ADVICE
RPC protocols must be registered via E-mail to rpc at sun.
Port numbers and other Internet numbers we register directly with the
Internet Assigned Numbers Authority, http://www.iana.org/ .
#endif
13.3 Drag and Drop: what objects and what are the semantics?
13.4 GNOME ORB (bonobo) remote calls, Web service calls (SOAP, etc.),
ToolTalk messages?
- 13.5 Files used as an interface, e.g. Resources, config files, etc.)
+ 13.5 Files used as an interface, e.g. Resources, config files, etc.
13.6 Significant file formats, names, syntax, and semantics?
Is there an /etc/magic entry for any new file format?
What will file(1) say?
#ifdef ADVICE
Support a comment syntax (preferably # to end-of-line) in each
customer-editable configuration file. Configuration by
a administrative command is preferable to hand-editing files.
#endif
13.7 Interfaces to applications it interoperates or communicates with?
(Perhaps pipes, shared memory.)
13.8 Is there a public namespace? (Can third parties create names
in your namespace?) How is this administered?
13.9 Other External Interfaces?
13.10 Brainstorming Significant Internal Interfaces
#ifdef ADVICE
These interfaces are likely to be Private, but there are various
flavors of Private, some of which need ARC review.
#endif
13.11 Protocols (public or private)
13.12 Private ORB, RPC, SOAP, RMI, etc. transactions
- 13.13 Files
+ 13.13 Files and their Formats
#ifdef ADVICE
Private configuration files that save information behind a program
or GUI, but which are not to be edited by hand, should (if a comment
syntax is supported) have a comment saying not to edit it, which
mentions what program(s) modify it.
#endif
13.14 Do any internal interfaces save state across invocations?
13.15 Other Internal Interfaces?
14. Questions for Every Interface:
These questions should be asked for every one of the project's
interfaces; the answers are therefore often listed in Section 9.2
(Don't repeat.) Only the interesting answers are normally discussed.
14.1 Propose the stability/commitment classification of the interface
- -- "Standard", "Stable" (formerly Public), "Evolving", "Unstable"
- (intentionally Uncommitted), Contract Private, etc. -- per the SAC
- Interface Taxonomy document in /shared/sac/doc/interface.taxonomy
+ -- "Standard", "Committed" (formerly Stable), "Uncommitted"
+ (formerly Unstable), "Volatile", Contract Private, etc. -- per
+ the SAC Interface Taxonomy document at
+ http://sac.sfbay/cgi-bin/bp.cgi?NAME=interface_taxonomy.bp
#ifdef ADVICE
Some interfaces (e.g., RPC, a filename used) have one commitment
level, but the actual messages transmitted (or file contents or
format) may have a different stability classification.
#endif
14.2 Who controls the interface (i.e., could make changes to it)?
Point out any interfaces not solely controlled by Sun.
14.3 Interface Specification:
14.3.1 Where is the interface specified (documented)?
14.3.2 Is the specification complete enough for a re-implementation?
14.3.3 Will the project deliver to customers documentation for the interface?
14.3.4 Are the interfaces documented clearly enough for a non-Sun client
to use them successfully?
14.4 Interface Versioning and Projected Evolution
#ifdef ADVICE
- Standard and Stable interfaces cannot change incompatibly (correctly,
+ Committed interfaces cannot change incompatibly (correctly,
cannot remove support for the previous version, even if a new version
can coexist) until either:
A. A major release of the product (which is not envisioned for
Solaris), or
B. the end-of-life process for features (aka EOF) as described in
http://sac.eng.sun.com/BestPractices/ToDo/Obsolete_EOF/
is followed; this requires demonstrating that the interface is
Obsolete -- i.e., generally unused -- often because a better
alternative exists and has "universal" acceptance.
- "Evolving" interfaces are not normally changed incompatibly. Such a
- change would need thoughtful justification to the committee.
+ "Uncommitted" interfaces are not normally changed incompatibly.
+ Such a change would need thoughtful justification to the committee.
Committed Private and Sun Private interfaces have much the same
restriction, but incompatible change can often be allowed, if it
is sufficiently hidden from the customer, or otherwise "managed"
so that "normal use" is not affected by the interface's evolution.
#endif
14.4.1 Present Change: if any interface is an update to or replacement for a
previous one, what was the stability classification of the previous
version? Is this backwards-compatible? Describe any migration story
to mitigate the conversion.
14.4.2 Future Evolution: Even if an interface is new, it should be prepared
for evolution. How will a transition to a new version to be
accomplished? What are the expected consequences to ISVs and users
and administrators? What provisions are made now to minimize or
manage the pain (to clients) of future evolution?
#ifdef WINDOWS
14.4.3 For Microsoft Windows components that install on top of an existing
product (such as PC-X on top of PC-NFSpro): are there common files
that should only be upgraded if the files being installed have a new
version?
#endif
15. Performance and Scalability:
#ifdef ADVICE
Our goal is to assure the architectural choices will likely lead to
acceptable performance and avoid surprising resource consumption.
#endif
15.1 What are the performance goals of the project? How were they
evaluated (or how will they be)? On what type of test platform?
How will performance regressions be identified?
#ifdef ADVICE
Significantly reduced performance can make an interface no longer
suited to a task for which it was appropriate; that would be an
architectural issue. In any case, the committee recommends that
test plans include verifying that performance regression is
identified, so it can be evaluated. If the performance of the
typical case is improved, but certain usage performs drastically
worse, a careful, educated tradeoff must be made.
#endif
15.2 Are there any limits to scalability, such as a fixed-size array
forcing a maximum number of clients, users, simultaneous
connections, etc.? Are any data structures (e.g., kernel
structures) so huge that large numbers of them are impractical?
15.3 Resource Consumption:
#ifdef ADVICE
Resources and constraints might be how many processors can be used,
kernel memory, file descriptors, virtual memory, filesystem space,
ports consumed.
#endif
15.3.1 Attempt to describe resource consumption scaling, even crudely.
For example, if each client consumes 1MB of memory, you could say:
Memory_required = 1MB * Nclients
15.3.2 Which resources are likely to be bottlenecks?
15.4 Does the application pause for significant amounts of time?
Can the user interact with the application while it is performing
long-duration tasks?
#ifdef ADVICE
If so, consider using threads (or forking a subprocess) to allow
user interaction in the interim.
#endif
15.5 Multi-threading: What is your project's MT model? What must an MT
client do to use your interface(s) safely? How does your project use
threads internally? How does it expect its client to use threads? If
it uses call-backs, can the called entity create a thread and
- recursively call back?
+ recursively call back? Is it prepared for multi-thread & multi-core
+ systems like Niagara and Opteron?
#ifdef ADVICE
Every API potentially will be used by MT clients. Describe what
synchronization (locking) would need to be performed by such a
client. Is this information documented for your customers? Most
ARC opinions should state this information. For more information
about threading terminology, see
http://sac.eng.sun.com/BestPractices/ToDo/MTsafety/
#endif
15.6 What is the impact on system performance (positive or negative)?
15.6.1 What is the average memory usage or working set of this component?
#ifdef WINDOWS
15.6.2W How much of this is locked down?
15.6.3W What system resources are consumed by each component under
- Windows 3.x? Under Windows 95?
+ Windows?
#else
15.6.2S How much of this is shared/sharable by other apps?
#ifdef ADVICE
The "pmap" command and the program performance
- analysis tools in Sun ONE Studio can help you measure
+ analysis tools in Sun Studio can help you measure
and improve memory usage for C/C++ programs.
#endif
#endif /* WINDOWS */
15.7 Does this application "wake up" periodically? How often and
under what conditions? What is the working set associated
with this behavior?
15.8 Will it require large files/databases (for example, new fonts)?
15.9 Do files/databases or heap space tend to grow with time/load?
What mechanisms does the user have to use to control this?
What happens to performance/system load?
15.10 What are the project's effects on boot time requirements?
16. Security:
Include a thorough description of the security assumptions,
capabilities and any potential risks (possible attack points) being
introduced by your project. A separate Security Questionnaire
- http://sac.eng/cgi-bin/bp.cgi?NAME=Security.bp
+ http://sac.eng.sun.com/cgi-bin/bp.cgi?NAME=Security.bp
is provided for more detailed guidance on the necessary information.
Cases are encouraged to fill out and include the Security
questionnaire (leveraging references to existing documentation) in the
case materials.
16.1 What security issues do you address in your project?
16.2 What security concerns might customers or reviewers have?
16.3 Are any components (e.g., encryption) subject to export restrictions?
Why or why not?
16.4 How are particularly security-critical data like passwords
treated?
17. Availability and Serviceability
17.1 How will it respond to failures? (Does it ever require reboot?
-#ifdef WINDOWS
- Can it lock up?)
-#else
Can it lock up? Is there a way for the user to "unstick it"?)
-#endif
17.2 How does your project deal with network failures (including
partition and re-integration)?
- 17.3 Can it save and restore state?
+ 17.3 Can it save and restore state? Is any special action required
+ if the filesystem is rolled-back to previous state (such as via
+ ZFS or other filesystem snapshot technologies)?
17.4 Can it checkpoint and recover? Can its files be corrupted by
failures? Does it clean up any locks/files after crashes?
17.5 Will it participate in the Solaris Fault Management Architecture
- (http://fma.eng/)
+ (http://fma.eng.sun.com/)?
17.6 Can the project's deliverables be patched and upgraded without
requiring a reboot? Without a noticeable service interruption?
17.7 How will patches be installed?
18. Adaptability to a Changing World:
18.1 Any plans for supporting operating systems other than Solaris (Linux,
- perhaps HP/UX, Microsoft Windows, AIX, etc.)?
+ Microsoft Windows, MacOS X, AIX, HP/UX, etc.)?
18.2 How does it deal with issues in the 64-bit world, including 64-bit
address spaces, 64-bit integers, and 64-bit files?
18.3 How will the project provide services to other projects?
18.3.1 Current or planned usage of CORBA IDL, IIOP, and an ORB?
If an ORB, hich one (Bonobo, Java IDL, ...)?
18.3.2 Current or planned Java Beans, especially J2EE?
18.3.3 Current or planned Web Services interfaces (SOAP, etc.?)
18.4 What is its relationship (or difficulties) with . . .
18.4.1 the Internet? Web Services?
18.4.2 Java? J2EE? Application Servers?
- 18.4.3 "Network of Things" (thin clients, portable devices,
+ 18.4.3 "Network of Things" (thin clients, portable devices, cell phones,
wireless networking, kitchen appliances with IP addresses?)
18.4.4 Multimedia?
18.4.5 Networked storage (SANs, NAS)
18.4.5 Infiniband?
18.4.6 Network identity services?
-
+ 18.4.7 Virtualized environments (Xen, Zones, VMWare)?
19. Issues? Please identify the issues for which you would like ARC
guidance. (e.g. Interface classification, deviations from standards,
architectural conflicts, release constraints...)
Any issues outstanding from previous reviews (or the case's mail
archive)?
20. Appendices and References
#ifdef ADVICE
Files must be in one of the acceptable file formats:
ASCII text
PDF
HTML
PostScript
Discuss any other form with your case owner and/or the SAC
coordinator via E-mail to lsarc-materials at sac.
In particular, framemaker, staroffice, powerpoint... formats
are almost never acceptable.
#endif
20.1 Interface Tables, Package Manifests, etc
20.2 References to other documents (one-pager, design papers,
interface contracts, etc.). Copies are to be placed in the case
directory.
20.3 Comments For Us?
20.3.1 How many engineer hours went into preparation of case materials,
including answering this questionnaire (that would not otherwise
have been needed for other purposes)?
20.3.2 Do you think it was time well spent?
20.3.3 How many engineer hours went into answering this questionnaire alone?
20.3.4 Comments on this questionnaire should be mailed to
- lsarc-chair at sac.eng.
+ lsarc-chair at sac.eng.sun.com.
20.3.5 Comments on your case owner, the review process, or the experience
may be placed here if they're not too personal, may be mailed to
the chair or arc-chairs at sac, or may be expressed to John Plocher
- (xXXXXX), Cheryl B. (xXXXXX) or Rob G. (xXXXXX).
+ (xXXXXX), or your divisional CTO.
#ifdef ADVICE
A. Other Considerations for Projects
Please see the following documents which attempt to enumerate additional
items which your project is responsible for understanding and addressing:
SAC Best Practices:
- http://sac.eng/BestPractices
+ http://sac.eng.sun.com/BestPractices
SAC Other Considerations:
- http://sac.eng/arc/ReviewQuestions/OtherConsiderations
+ http://sac.eng.sun.com/arc/ReviewQuestions/OtherConsiderations
#endif
6. Resources and Schedule
6.4. Steering Committee requested information
6.4.1. Consolidation C-team Name:
N/A
6.5. ARC review type: FastTrack
6.6. ARC Exposure: open
More information about the opensolaris-arc
mailing list