From markcarl@sac.sfbay.sun.com Tue Apr 28 09:56:19 2009 Received: from newsunmail1brm.central.sun.com (newsunmail1brm.Central.Sun.COM [129.147.62.245]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n3SGuJX4009048 for ; Tue, 28 Apr 2009 09:56:19 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by newsunmail1brm.central.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n3SGuHPN052557; Tue, 28 Apr 2009 10:56:18 -0600 (MDT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KIT00B0ZLPUUL00@brm-avmta-1.central.sun.com>; Tue, 28 Apr 2009 10:56:18 -0600 (MDT) Received: from dm-sfbay-02.sfbay.sun.com ([129.146.11.31]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KIT00L6QLPTPJE0@brm-avmta-1.central.sun.com>; Tue, 28 Apr 2009 10:56:17 -0600 (MDT) Received: from sac.sfbay.sun.com (sac.SFBay.Sun.COM [129.146.226.132]) by dm-sfbay-02.sfbay.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n3SGuGlT002308; Tue, 28 Apr 2009 09:56:16 -0700 (PDT) Received: from sac.sfbay.sun.com (localhost [127.0.0.1]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n3SGuEd2009043; Tue, 28 Apr 2009 09:56:14 -0700 (PDT) Received: (from markcarl@localhost) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8/Submit) id n3SGuEVj009039; Tue, 28 Apr 2009 09:56:14 -0700 (PDT) Date: Tue, 28 Apr 2009 09:56:14 -0700 (PDT) From: Mark Carlson Subject: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] To: LSARC-ext@sun.com Cc: Vivek.Titarmare@sun.com Message-id: <200904281656.n3SGuEVj009039@sac.sfbay.sun.com> Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 Status: RO Content-Length: 6669 I am sponsoring this familiarity case for Vivek Titarmare. It requests minor binding and times out 05/05/2009. -- mark Template Version: @(#)sac_nextcase 1.68 02/23/09 SMI This information is Copyright 2009 Sun Microsystems 1. Introduction 1.1. Project/Component Working Name: trove-2.0.4 1.2. Name of Document Author/Supplier: Author: Vivek Titarmare 1.3 Date of This Document: 28 April, 2009 2. Project Summary 2.1 Project Description The Trove library provides high speed regular and primitive collections for Java. 4. Technical Description: The Trove library provides high speed regular and primitive collections for Java. The GNU Trove library has two objectives: 1. Provide "free" (as in "free speech" and "free beer"), fast, lightweight implementations of the java.util Collections API. These implementations are designed to be pluggable replacements for their JDK equivalents. 2. Provide primitive collections with similar APIs to the above. This gap in the JDK is often addressed by using the "wrapper" classes (java.lang.Integer, java.lang.Float, etc.) with Object-based collections. For most applications, however, collections which store primitives directly will require less space and yield significant performance gains. 5. Interfaces The jar file "trove.jar" contains following interface. Exported interface Classification Interface type ============================= ============== ============== gnu.trove * TByteByteProcedure Uncommitted Interface * TByteDoubleProcedure Uncommitted Interface * TByteFloatProcedure Uncommitted Interface * TByteFunction Uncommitted Interface * TByteHashingStrategy Uncommitted Interface * TByteIntProcedure Uncommitted Interface * TByteLongProcedure Uncommitted Interface * TByteObjectProcedure Uncommitted Interface * TByteProcedure Uncommitted Interface * TByteShortProcedure Uncommitted Interface * TDoubleByteProcedure Uncommitted Interface * TDoubleDoubleProcedure Uncommitted Interface * TDoubleFloatProcedure Uncommitted Interface * TDoubleFunction Uncommitted Interface * TDoubleHashingStrategy Uncommitted Interface * TDoubleIntProcedure Uncommitted Interface * TDoubleLongProcedure Uncommitted Interface * TDoubleObjectProcedure Uncommitted Interface * TDoubleProcedure Uncommitted Interface * TDoubleShortProcedure Uncommitted Interface * TFloatByteProcedure Uncommitted Interface * TFloatDoubleProcedure Uncommitted Interface * TFloatFloatProcedure Uncommitted Interface * TFloatFunction Uncommitted Interface * TFloatHashingStrategy Uncommitted Interface * TFloatIntProcedure Uncommitted Interface * TFloatLongProcedure Uncommitted Interface * TFloatObjectProcedure Uncommitted Interface * TFloatProcedure Uncommitted Interface * TFloatShortProcedure Uncommitted Interface * TIntByteProcedure Uncommitted Interface * TIntDoubleProcedure Uncommitted Interface * TIntFloatProcedure Uncommitted Interface * TIntFunction Uncommitted Interface * TIntHashingStrategy Uncommitted Interface * TIntIntProcedure Uncommitted Interface * TIntLongProcedure Uncommitted Interface * TIntObjectProcedure Uncommitted Interface * TIntProcedure Uncommitted Interface * TIntShortProcedure Uncommitted Interface * TLinkable Uncommitted Interface * TLongByteProcedure Uncommitted Interface * TLongDoubleProcedure Uncommitted Interface * TLongFloatProcedure Uncommitted Interface * TLongFunction Uncommitted Interface * TLongHashingStrategy Uncommitted Interface * TLongIntProcedure Uncommitted Interface * TLongLongProcedure Uncommitted Interface * TLongObjectProcedure Uncommitted Interface * TLongProcedure Uncommitted Interface * TLongShortProcedure Uncommitted Interface * TObjectByteProcedure Uncommitted Interface * TObjectDoubleProcedure Uncommitted Interface * TObjectFloatProcedure Uncommitted Interface * TObjectFunction Uncommitted Interface * TObjectHashingStrategy Uncommitted Interface * TObjectIntProcedure Uncommitted Interface * TObjectLongProcedure Uncommitted Interface * TObjectObjectProcedure Uncommitted Interface * TObjectProcedure Uncommitted Interface * TObjectShortProcedure Uncommitted Interface * TShortByteProcedure Uncommitted Interface * TShortDoubleProcedure Uncommitted Interface * TShortFloatProcedure Uncommitted Interface * TShortFunction Uncommitted Interface * TShortHashingStrategy Uncommitted Interface * TShortIntProcedure Uncommitted Interface * TShortLongProcedure Uncommitted Interface * TShortObjectProcedure Uncommitted Interface * TShortProcedure Uncommitted Interface * TShortShortProcedure Uncommitted Interface Imported interface Classification Comments ======================= ============== =================================== None The Jar file would go in "usr/share/lib/java/" 6. Resources and Schedule 6.4. Steering Committee requested information 6.4.1. Consolidation C-team Name: SFW 6.5. ARC review type: FastTrack 6.6. ARC Exposure: open From storycrafter@gmail.com Tue Apr 28 11:28:48 2009 Received: from newsunmail1brm.central.sun.com (newsunmail1brm.Central.Sun.COM [129.147.62.245]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n3SISmu8013351 for ; Tue, 28 Apr 2009 11:28:48 -0700 (PDT) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by newsunmail1brm.central.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n3SISWvN049103 for <@sunmail2sca.sfbay.sun.com:LSARC-ext@sun.com>; Tue, 28 Apr 2009 12:28:48 -0600 (MDT) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KIT00D07PZZXV00@nwk-avmta-2.sfbay.sun.com> for LSARC-ext@sun.com (ORCPT LSARC-ext@sun.com); Tue, 28 Apr 2009 11:28:47 -0700 (PDT) Received: from brmea-mail-4.sun.com ([192.18.98.36]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KIT00B5ZPZZKL40@nwk-avmta-2.sfbay.sun.com> for LSARC-ext@sun.com (ORCPT LSARC-ext@sun.com); Tue, 28 Apr 2009 11:28:47 -0700 (PDT) Received: from relay12i.sun.com (ip122.net129179-4.block1.us.syntegra.com [129.179.4.122]) by brmea-mail-4.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n3SIE6BM025795 for ; Tue, 28 Apr 2009 18:28:47 +0000 (GMT) Received: from mmp14es.mmp.us.syntegra.com ([160.41.208.14] [160.41.208.14]) by relay12i.sun.com with ESMTP id BT-MMP-299920 for LSARC-ext@sun.com; Tue, 28 Apr 2009 18:28:46 +0000 (Z) Received: from relay14i.sun.com (relay14i.sun.com [129.179.4.124]) by mmp14es.mmp.us.syntegra.com with ESMTP id BT-MMP-355035 for LSARC-ext@sun.com; Tue, 28 Apr 2009 18:28:46 +0000 (Z) Received: from yx-out-1718.google.com ([74.125.44.155] [74.125.44.155]) by relay1i.sun.com with ESMTP id BT-MMP-31942189 for LSARC-ext@sun.com; Tue, 28 Apr 2009 18:27:54 +0000 (Z) Received: by yx-out-1718.google.com with SMTP id 6so464632yxn.68 for ; Tue, 28 Apr 2009 11:27:51 -0700 (PDT) Received: by 10.100.121.12 with SMTP id t12mr6138637anc.58.1240943271395; Tue, 28 Apr 2009 11:27:51 -0700 (PDT) Received: from ?172.16.202.89? (68-252-106-20.ded.ameritech.net [68.252.106.20]) by mx.google.com with ESMTPS id c9sm242985ana.39.2009.04.28.11.27.50 (version=TLSv1/SSLv3 cipher=RC4-MD5) ; Tue, 28 Apr 2009 11:27:50 -0700 (PDT) Date: Tue, 28 Apr 2009 13:27:50 -0500 From: Mark Martin Subject: Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] In-reply-to: <200904281656.n3SGuEVj009039@sac.sfbay.sun.com> To: Mark Carlson Cc: LSARC-ext@sun.com Message-id: <49F74AA6.4080107@gmail.com> MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1; format=flowed Content-transfer-encoding: 7BIT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=domainkey-signature:received:received:message-id:date:from :user-agent:mime-version:to:cc:subject:references:in-reply-to :content-type:content-transfer-encoding; bh=60KkXnNU04S6cBVZUajSrczwVXaAfIhmQf0XtZpgr0k=; b=JknzWfXnYzld/wgN5JsxYqZQE9owy5Ov0ClIIKlaJt8cicQ+PBouE6gsTBRcTWiOhh JZ7WaXPEUVgYt289DdLRMffqu2zPTxYQxW9w960DR+K0qvN9978iAqgRDT4Msfc2exx7 UnBZQspFdHoFh/zYiNhw+bJEZuVGON0EZFB/U= DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=message-id:date:from:user-agent:mime-version:to:cc:subject :references:in-reply-to:content-type:content-transfer-encoding; b=GSFnKm3F/fKqOJTwjOAmRNkTsyX68pne7hBsvhgdrWRTAoQjSFQLEjJVpbR1djwaf0 AujgL/ZN2r7iISTI4Y1UVY9C5syEmrau5m/m7Ivy5HF4Z7yDpSwnqK/EseFWOmz7wdzN sv0PYjIzKMZWnfw5rriRX+YT2AnOCtu9LS90Y= X-PMX-Version: 5.4.1.325704 X-Brightmail-Tracker: AAAAAA== X-Antispam: No, score=0.0/5.0, scanned in 0.076sec at (localhost [127.0.0.1]) by smf-spamd v1.3.1 - http://smfs.sf.net/ References: <200904281656.n3SGuEVj009039@sac.sfbay.sun.com> User-Agent: Thunderbird 2.0.0.21 (Windows/20090302) Status: RO Content-Length: 5567 Mark Carlson wrote: > 5. Interfaces > > The jar file "trove.jar" contains following interface. > > Exported interface Classification Interface type > ============================= ============== ============== > gnu.trove > * TByteByteProcedure Uncommitted Interface > * TByteDoubleProcedure Uncommitted Interface > * TByteFloatProcedure Uncommitted Interface > * TByteFunction Uncommitted Interface > * TByteHashingStrategy Uncommitted Interface > * TByteIntProcedure Uncommitted Interface > * TByteLongProcedure Uncommitted Interface > * TByteObjectProcedure Uncommitted Interface > * TByteProcedure Uncommitted Interface > * TByteShortProcedure Uncommitted Interface > * TDoubleByteProcedure Uncommitted Interface > * TDoubleDoubleProcedure Uncommitted Interface > * TDoubleFloatProcedure Uncommitted Interface > * TDoubleFunction Uncommitted Interface > * TDoubleHashingStrategy Uncommitted Interface > * TDoubleIntProcedure Uncommitted Interface > * TDoubleLongProcedure Uncommitted Interface > * TDoubleObjectProcedure Uncommitted Interface > * TDoubleProcedure Uncommitted Interface > * TDoubleShortProcedure Uncommitted Interface > * TFloatByteProcedure Uncommitted Interface > * TFloatDoubleProcedure Uncommitted Interface > * TFloatFloatProcedure Uncommitted Interface > * TFloatFunction Uncommitted Interface > * TFloatHashingStrategy Uncommitted Interface > * TFloatIntProcedure Uncommitted Interface > * TFloatLongProcedure Uncommitted Interface > * TFloatObjectProcedure Uncommitted Interface > * TFloatProcedure Uncommitted Interface > * TFloatShortProcedure Uncommitted Interface > * TIntByteProcedure Uncommitted Interface > * TIntDoubleProcedure Uncommitted Interface > * TIntFloatProcedure Uncommitted Interface > * TIntFunction Uncommitted Interface > * TIntHashingStrategy Uncommitted Interface > * TIntIntProcedure Uncommitted Interface > * TIntLongProcedure Uncommitted Interface > * TIntObjectProcedure Uncommitted Interface > * TIntProcedure Uncommitted Interface > * TIntShortProcedure Uncommitted Interface > * TLinkable Uncommitted Interface > * TLongByteProcedure Uncommitted Interface > * TLongDoubleProcedure Uncommitted Interface > * TLongFloatProcedure Uncommitted Interface > * TLongFunction Uncommitted Interface > * TLongHashingStrategy Uncommitted Interface > * TLongIntProcedure Uncommitted Interface > * TLongLongProcedure Uncommitted Interface > * TLongObjectProcedure Uncommitted Interface > * TLongProcedure Uncommitted Interface > * TLongShortProcedure Uncommitted Interface > * TObjectByteProcedure Uncommitted Interface > * TObjectDoubleProcedure Uncommitted Interface > * TObjectFloatProcedure Uncommitted Interface > * TObjectFunction Uncommitted Interface > * TObjectHashingStrategy Uncommitted Interface > * TObjectIntProcedure Uncommitted Interface > * TObjectLongProcedure Uncommitted Interface > * TObjectObjectProcedure Uncommitted Interface > * TObjectProcedure Uncommitted Interface > * TObjectShortProcedure Uncommitted Interface > * TShortByteProcedure Uncommitted Interface > * TShortDoubleProcedure Uncommitted Interface > * TShortFloatProcedure Uncommitted Interface > * TShortFunction Uncommitted Interface > * TShortHashingStrategy Uncommitted Interface > * TShortIntProcedure Uncommitted Interface > * TShortLongProcedure Uncommitted Interface > * TShortObjectProcedure Uncommitted Interface > * TShortProcedure Uncommitted Interface > * TShortShortProcedure Uncommitted Interface > > > Imported interface Classification Comments > ======================= ============== =================================== > None > > The Jar file would go in "usr/share/lib/java/" > Is it important, in general, to note the minimum JDK required? I've noted it's importance to other cases. If none is listed, what is the assumed minimum java installation? From margot.miller@sun.com Thu May 7 14:10:36 2009 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n47LAZnr015947 for ; Thu, 7 May 2009 14:10:35 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail5.uk.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n47LAU31027971; Thu, 7 May 2009 22:10:32 +0100 (BST) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJA00J35LHJWI00@brm-avmta-1.central.sun.com>; Thu, 07 May 2009 15:10:31 -0600 (MDT) Received: from jurassic-x4600.sfbay.sun.com ([129.146.17.63]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJA00CKLLHI3H90@brm-avmta-1.central.sun.com>; Thu, 07 May 2009 15:10:30 -0600 (MDT) Received: from [10.7.250.251] (punchin-client-10-7-250-251.SFBay.Sun.COM [10.7.250.251]) by jurassic-x4600.sfbay.sun.com (8.14.3+Sun/8.14.3) with ESMTP id n47LASZl965114; Thu, 07 May 2009 14:10:28 -0700 (PDT) Date: Thu, 07 May 2009 14:10:27 -0700 From: Margot Miller Subject: Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] In-reply-to: <200904281656.n3SGuEVj009039@sac.sfbay.sun.com> To: Mark Carlson Cc: LSARC-ext@sun.com, Vivek.Titarmare@sun.com Message-id: <4A034E43.7070305@sun.com> MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <200904281656.n3SGuEVj009039@sac.sfbay.sun.com> User-Agent: Thunderbird 2.0b1 (X11/20070115) Status: RO Content-Length: 7117 Please put the JDK in the imported table. Also previous email asked what is the minimum JDK that can be used with this. No need to deliver a man page for a java library. Thanks Margot Mark Carlson wrote: > I am sponsoring this familiarity case for Vivek Titarmare. It requests minor binding and times out 05/05/2009. > > -- mark > > Template Version: @(#)sac_nextcase 1.68 02/23/09 SMI > This information is Copyright 2009 Sun Microsystems > 1. Introduction > 1.1. Project/Component Working Name: > trove-2.0.4 > 1.2. Name of Document Author/Supplier: > Author: Vivek Titarmare > 1.3 Date of This Document: > 28 April, 2009 > > 2. Project Summary > 2.1 Project Description > > The Trove library provides high speed regular and primitive collections for Java. > > 4. Technical Description: > > The Trove library provides high speed regular and primitive collections for Java. > > The GNU Trove library has two objectives: > > 1. Provide "free" (as in "free speech" and "free beer"), fast, lightweight implementations of the java.util Collections API. These implementations are designed to be pluggable replacements for their JDK equivalents. > 2. Provide primitive collections with similar APIs to the above. This gap in the JDK is often addressed by using the "wrapper" classes (java.lang.Integer, java.lang.Float, etc.) with Object-based collections. > For most applications, however, collections which store primitives directly will require less space and yield significant performance gains. > > 5. Interfaces > > The jar file "trove.jar" contains following interface. > > Exported interface Classification Interface type > ============================= ============== ============== > gnu.trove > * TByteByteProcedure Uncommitted Interface > * TByteDoubleProcedure Uncommitted Interface > * TByteFloatProcedure Uncommitted Interface > * TByteFunction Uncommitted Interface > * TByteHashingStrategy Uncommitted Interface > * TByteIntProcedure Uncommitted Interface > * TByteLongProcedure Uncommitted Interface > * TByteObjectProcedure Uncommitted Interface > * TByteProcedure Uncommitted Interface > * TByteShortProcedure Uncommitted Interface > * TDoubleByteProcedure Uncommitted Interface > * TDoubleDoubleProcedure Uncommitted Interface > * TDoubleFloatProcedure Uncommitted Interface > * TDoubleFunction Uncommitted Interface > * TDoubleHashingStrategy Uncommitted Interface > * TDoubleIntProcedure Uncommitted Interface > * TDoubleLongProcedure Uncommitted Interface > * TDoubleObjectProcedure Uncommitted Interface > * TDoubleProcedure Uncommitted Interface > * TDoubleShortProcedure Uncommitted Interface > * TFloatByteProcedure Uncommitted Interface > * TFloatDoubleProcedure Uncommitted Interface > * TFloatFloatProcedure Uncommitted Interface > * TFloatFunction Uncommitted Interface > * TFloatHashingStrategy Uncommitted Interface > * TFloatIntProcedure Uncommitted Interface > * TFloatLongProcedure Uncommitted Interface > * TFloatObjectProcedure Uncommitted Interface > * TFloatProcedure Uncommitted Interface > * TFloatShortProcedure Uncommitted Interface > * TIntByteProcedure Uncommitted Interface > * TIntDoubleProcedure Uncommitted Interface > * TIntFloatProcedure Uncommitted Interface > * TIntFunction Uncommitted Interface > * TIntHashingStrategy Uncommitted Interface > * TIntIntProcedure Uncommitted Interface > * TIntLongProcedure Uncommitted Interface > * TIntObjectProcedure Uncommitted Interface > * TIntProcedure Uncommitted Interface > * TIntShortProcedure Uncommitted Interface > * TLinkable Uncommitted Interface > * TLongByteProcedure Uncommitted Interface > * TLongDoubleProcedure Uncommitted Interface > * TLongFloatProcedure Uncommitted Interface > * TLongFunction Uncommitted Interface > * TLongHashingStrategy Uncommitted Interface > * TLongIntProcedure Uncommitted Interface > * TLongLongProcedure Uncommitted Interface > * TLongObjectProcedure Uncommitted Interface > * TLongProcedure Uncommitted Interface > * TLongShortProcedure Uncommitted Interface > * TObjectByteProcedure Uncommitted Interface > * TObjectDoubleProcedure Uncommitted Interface > * TObjectFloatProcedure Uncommitted Interface > * TObjectFunction Uncommitted Interface > * TObjectHashingStrategy Uncommitted Interface > * TObjectIntProcedure Uncommitted Interface > * TObjectLongProcedure Uncommitted Interface > * TObjectObjectProcedure Uncommitted Interface > * TObjectProcedure Uncommitted Interface > * TObjectShortProcedure Uncommitted Interface > * TShortByteProcedure Uncommitted Interface > * TShortDoubleProcedure Uncommitted Interface > * TShortFloatProcedure Uncommitted Interface > * TShortFunction Uncommitted Interface > * TShortHashingStrategy Uncommitted Interface > * TShortIntProcedure Uncommitted Interface > * TShortLongProcedure Uncommitted Interface > * TShortObjectProcedure Uncommitted Interface > * TShortProcedure Uncommitted Interface > * TShortShortProcedure Uncommitted Interface > > > Imported interface Classification Comments > ======================= ============== =================================== > None > > The Jar file would go in "usr/share/lib/java/" > > 6. Resources and Schedule > 6.4. Steering Committee requested information > 6.4.1. Consolidation C-team Name: > SFW > 6.5. ARC review type: FastTrack > 6.6. ARC Exposure: open > > From margot.miller@sun.com Thu May 7 14:12:34 2009 Received: from sunmail3mpk.sfbay.sun.com (sunmail3mpk.SFBay.Sun.COM [129.146.11.52]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n47LCXVN016053 for ; Thu, 7 May 2009 14:12:33 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail3mpk.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n47LCU4E021753; Thu, 7 May 2009 14:12:31 -0700 (PDT) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJA0090RLKV3300@nwk-avmta-1.sfbay.Sun.COM>; Thu, 07 May 2009 14:12:31 -0700 (PDT) Received: from jurassic-x4600.sfbay.sun.com ([129.146.17.59]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJA0057YLKUQG40@nwk-avmta-1.sfbay.Sun.COM>; Thu, 07 May 2009 14:12:30 -0700 (PDT) Received: from [10.7.250.251] (punchin-client-10-7-250-251.SFBay.Sun.COM [10.7.250.251]) by jurassic-x4600.sfbay.sun.com (8.14.3+Sun/8.14.3) with ESMTP id n47LCRJ7965391; Thu, 07 May 2009 14:12:28 -0700 (PDT) Date: Thu, 07 May 2009 14:12:27 -0700 From: Margot Miller Subject: Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] In-reply-to: <4A034E43.7070305@sun.com> To: Mark Carlson Cc: LSARC-ext@sun.com, Vivek.Titarmare@sun.com Message-id: <4A034EBB.2010103@sun.com> MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <200904281656.n3SGuEVj009039@sac.sfbay.sun.com> <4A034E43.7070305@sun.com> User-Agent: Thunderbird 2.0b1 (X11/20070115) Status: RO Content-Length: 7879 Also what is the name of package this is being delivered in? Margot Miller wrote: > Please put the JDK in the imported table. Also previous email > asked what is the minimum JDK that can be used with this. > > No need to deliver a man page for a java library. > > Thanks > Margot > > > Mark Carlson wrote: >> I am sponsoring this familiarity case for Vivek Titarmare. It >> requests minor binding and times out 05/05/2009. >> >> -- mark >> >> Template Version: @(#)sac_nextcase 1.68 02/23/09 SMI >> This information is Copyright 2009 Sun Microsystems >> 1. Introduction >> 1.1. Project/Component Working Name: >> trove-2.0.4 >> 1.2. Name of Document Author/Supplier: >> Author: Vivek Titarmare >> 1.3 Date of This Document: >> 28 April, 2009 >> >> 2. Project Summary >> 2.1 Project Description >> >> The Trove library provides high speed regular and primitive >> collections for Java. >> 4. Technical Description: >> >> The Trove library provides high speed regular and primitive >> collections for Java. >> >> The GNU Trove library has two objectives: >> >> 1. Provide "free" (as in "free speech" and "free beer"), fast, >> lightweight implementations of the java.util Collections API. These >> implementations are designed to be pluggable replacements for their >> JDK equivalents. >> 2. Provide primitive collections with similar APIs to the >> above. This gap in the JDK is often addressed by using the "wrapper" >> classes (java.lang.Integer, java.lang.Float, etc.) with Object-based >> collections. For most applications, however, collections >> which store primitives directly will require less space and yield >> significant performance gains. >> >> 5. Interfaces >> The jar file "trove.jar" contains following interface. >> Exported interface Classification >> Interface type >> ============================= ============== >> ============== >> gnu.trove >> * TByteByteProcedure Uncommitted Interface >> * TByteDoubleProcedure Uncommitted Interface >> * TByteFloatProcedure Uncommitted Interface >> * TByteFunction Uncommitted >> Interface * TByteHashingStrategy >> Uncommitted Interface >> * TByteIntProcedure Uncommitted Interface >> * TByteLongProcedure Uncommitted Interface >> * TByteObjectProcedure Uncommitted Interface >> * TByteProcedure Uncommitted Interface >> * TByteShortProcedure Uncommitted Interface >> * TDoubleByteProcedure Uncommitted Interface >> * TDoubleDoubleProcedure Uncommitted Interface >> * TDoubleFloatProcedure Uncommitted Interface >> * TDoubleFunction Uncommitted Interface >> * TDoubleHashingStrategy Uncommitted Interface >> * TDoubleIntProcedure Uncommitted Interface >> * TDoubleLongProcedure Uncommitted Interface >> * TDoubleObjectProcedure Uncommitted Interface >> * TDoubleProcedure Uncommitted Interface >> * TDoubleShortProcedure Uncommitted Interface >> * TFloatByteProcedure Uncommitted Interface >> * TFloatDoubleProcedure Uncommitted Interface >> * TFloatFloatProcedure Uncommitted Interface >> * TFloatFunction Uncommitted Interface >> * TFloatHashingStrategy Uncommitted Interface >> * TFloatIntProcedure Uncommitted Interface >> * TFloatLongProcedure Uncommitted Interface >> * TFloatObjectProcedure Uncommitted Interface >> * TFloatProcedure Uncommitted Interface >> * TFloatShortProcedure Uncommitted Interface >> * TIntByteProcedure Uncommitted Interface >> * TIntDoubleProcedure Uncommitted Interface >> * TIntFloatProcedure Uncommitted Interface >> * TIntFunction Uncommitted Interface >> * TIntHashingStrategy Uncommitted Interface >> * TIntIntProcedure Uncommitted Interface >> * TIntLongProcedure Uncommitted Interface >> * TIntObjectProcedure Uncommitted Interface >> * TIntProcedure Uncommitted Interface >> * TIntShortProcedure Uncommitted Interface >> * TLinkable Uncommitted Interface >> * TLongByteProcedure Uncommitted Interface >> * TLongDoubleProcedure Uncommitted Interface >> * TLongFloatProcedure Uncommitted Interface >> * TLongFunction Uncommitted Interface >> * TLongHashingStrategy Uncommitted Interface >> * TLongIntProcedure Uncommitted Interface >> * TLongLongProcedure Uncommitted Interface >> * TLongObjectProcedure Uncommitted Interface >> * TLongProcedure Uncommitted Interface >> * TLongShortProcedure Uncommitted Interface >> * TObjectByteProcedure Uncommitted Interface >> * TObjectDoubleProcedure Uncommitted Interface >> * TObjectFloatProcedure Uncommitted Interface >> * TObjectFunction Uncommitted Interface >> * TObjectHashingStrategy Uncommitted Interface >> * TObjectIntProcedure Uncommitted Interface >> * TObjectLongProcedure Uncommitted Interface >> * TObjectObjectProcedure Uncommitted Interface >> * TObjectProcedure Uncommitted Interface >> * TObjectShortProcedure Uncommitted Interface >> * TShortByteProcedure Uncommitted Interface >> * TShortDoubleProcedure Uncommitted Interface >> * TShortFloatProcedure Uncommitted Interface >> * TShortFunction Uncommitted Interface >> * TShortHashingStrategy Uncommitted Interface >> * TShortIntProcedure Uncommitted Interface >> * TShortLongProcedure Uncommitted Interface >> * TShortObjectProcedure Uncommitted Interface >> * TShortProcedure Uncommitted Interface >> * TShortShortProcedure Uncommitted Interface >> >> >> Imported interface Classification Comments >> ======================= ============== >> =================================== None >> >> The Jar file would go in "usr/share/lib/java/" >> >> 6. Resources and Schedule >> 6.4. Steering Committee requested information >> 6.4.1. Consolidation C-team Name: >> SFW >> 6.5. ARC review type: FastTrack >> 6.6. ARC Exposure: open >> >> > From Vivek.Titarmare@Sun.COM Fri May 8 03:25:57 2009 Received: from sunmail2sca.sfbay.sun.com (sunmail2sca.SFBay.Sun.COM [129.145.155.234]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n48APv8u019023 for ; Fri, 8 May 2009 03:25:57 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail2sca.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n48APuMJ010000 for <@sunmail2sca.sfbay.sun.com:LSARC-ext@sun.com>; Fri, 8 May 2009 03:25:56 -0700 (PDT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJB00D10MB72K00@brm-avmta-1.central.sun.com> for LSARC-ext@sun.com (ORCPT LSARC-ext@sun.com); Fri, 08 May 2009 04:25:55 -0600 (MDT) Received: from sineb-mail-1.sun.com ([192.18.19.6]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJB00GAUMB64QA0@brm-avmta-1.central.sun.com> for LSARC-ext@sun.com (ORCPT LSARC-ext@sun.com); Fri, 08 May 2009 04:25:55 -0600 (MDT) Received: from fe-apac-05.sun.com (fe-apac-05.sun.com [192.18.19.176] (may be forged)) by sineb-mail-1.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n48APrEX008610 for ; Fri, 08 May 2009 10:25:53 +0000 (GMT) Received: from conversion-daemon.mail-apac.sun.com by mail-apac.sun.com (Sun Java(tm) System Messaging Server 7.0-5.01 64bit (built Feb 19 2009)) id <0KJB00A00M7K2I00@mail-apac.sun.com> for LSARC-ext@sun.com (ORCPT LSARC-ext@sun.com); Fri, 08 May 2009 18:25:53 +0800 (SGT) Received: from VivekTPC ([unknown] [129.150.146.157]) by mail-apac.sun.com (Sun Java(tm) System Messaging Server 7.0-5.01 64bit (built Feb 19 2009)) with ESMTPSA id <0KJB006FYMAY6F00@mail-apac.sun.com>; Fri, 08 May 2009 18:25:51 +0800 (SGT) Date: Fri, 08 May 2009 15:55:43 +0530 From: Vivek Titarmare Subject: RE: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] In-reply-to: <4A034E43.7070305@sun.com> Sender: Vivek.Titarmare@Sun.COM To: "'Margot Miller'" , "'Mark Carlson'" Cc: LSARC-ext@Sun.COM Message-id: <000501c9cfc7$5a7d4350$0f77c9f0$%Titarmare@Sun.com> MIME-version: 1.0 X-Mailer: Microsoft Office Outlook 12.0 Content-type: multipart/mixed; boundary="Boundary_(ID_ZA2r1gYA7dNCO1l06AabtQ)" Content-language: en-us Thread-index: AcnPWEPmzcwLIMVdR8y6mGEwKbXQsAAbFufw X-PMX-Version: 5.4.1.325704 References: <200904281656.n3SGuEVj009039@sac.sfbay.sun.com> <4A034E43.7070305@sun.com> Status: RO Content-Length: 24851 This is a multi-part message in MIME format. --Boundary_(ID_ZA2r1gYA7dNCO1l06AabtQ) Content-type: text/plain; charset=us-ascii Content-transfer-encoding: 7BIT Hi Margot, I have updated the ARC material. Pl. find attached the same. The minimal JDK is version 1.5. I have added both versions (1.5 & 1.6) in the Imported Interface table. Thanks, ~Vivek R. Titarmare -----Original Message----- From: Margot Miller [mailto:Margot.Miller@Sun.COM] Sent: Friday, May 08, 2009 2:40 AM To: Mark Carlson Cc: LSARC-ext@sun.com; Vivek.Titarmare@Sun.COM Subject: Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] Please put the JDK in the imported table. Also previous email asked what is the minimum JDK that can be used with this. No need to deliver a man page for a java library. Thanks Margot Mark Carlson wrote: > I am sponsoring this familiarity case for Vivek Titarmare. It requests minor binding and times out 05/05/2009. > > -- mark > > Template Version: @(#)sac_nextcase 1.68 02/23/09 SMI > This information is Copyright 2009 Sun Microsystems > 1. Introduction > 1.1. Project/Component Working Name: > trove-2.0.4 > 1.2. Name of Document Author/Supplier: > Author: Vivek Titarmare > 1.3 Date of This Document: > 28 April, 2009 > > 2. Project Summary > 2.1 Project Description > > The Trove library provides high speed regular and primitive collections for Java. > > 4. Technical Description: > > The Trove library provides high speed regular and primitive collections for Java. > > The GNU Trove library has two objectives: > > 1. Provide "free" (as in "free speech" and "free beer"), fast, lightweight implementations of the java.util Collections API. These implementations are designed to be pluggable replacements for their JDK equivalents. > 2. Provide primitive collections with similar APIs to the above. This gap in the JDK is often addressed by using the "wrapper" classes (java.lang.Integer, java.lang.Float, etc.) with Object-based collections. > For most applications, however, collections which store primitives directly will require less space and yield significant performance gains. > > 5. Interfaces > > The jar file "trove.jar" contains following interface. > > Exported interface Classification Interface type > ============================= ============== ============== > gnu.trove > * TByteByteProcedure Uncommitted Interface > * TByteDoubleProcedure Uncommitted Interface > * TByteFloatProcedure Uncommitted Interface > * TByteFunction Uncommitted Interface > * TByteHashingStrategy Uncommitted Interface > * TByteIntProcedure Uncommitted Interface > * TByteLongProcedure Uncommitted Interface > * TByteObjectProcedure Uncommitted Interface > * TByteProcedure Uncommitted Interface > * TByteShortProcedure Uncommitted Interface > * TDoubleByteProcedure Uncommitted Interface > * TDoubleDoubleProcedure Uncommitted Interface > * TDoubleFloatProcedure Uncommitted Interface > * TDoubleFunction Uncommitted Interface > * TDoubleHashingStrategy Uncommitted Interface > * TDoubleIntProcedure Uncommitted Interface > * TDoubleLongProcedure Uncommitted Interface > * TDoubleObjectProcedure Uncommitted Interface > * TDoubleProcedure Uncommitted Interface > * TDoubleShortProcedure Uncommitted Interface > * TFloatByteProcedure Uncommitted Interface > * TFloatDoubleProcedure Uncommitted Interface > * TFloatFloatProcedure Uncommitted Interface > * TFloatFunction Uncommitted Interface > * TFloatHashingStrategy Uncommitted Interface > * TFloatIntProcedure Uncommitted Interface > * TFloatLongProcedure Uncommitted Interface > * TFloatObjectProcedure Uncommitted Interface > * TFloatProcedure Uncommitted Interface > * TFloatShortProcedure Uncommitted Interface > * TIntByteProcedure Uncommitted Interface > * TIntDoubleProcedure Uncommitted Interface > * TIntFloatProcedure Uncommitted Interface > * TIntFunction Uncommitted Interface > * TIntHashingStrategy Uncommitted Interface > * TIntIntProcedure Uncommitted Interface > * TIntLongProcedure Uncommitted Interface > * TIntObjectProcedure Uncommitted Interface > * TIntProcedure Uncommitted Interface > * TIntShortProcedure Uncommitted Interface > * TLinkable Uncommitted Interface > * TLongByteProcedure Uncommitted Interface > * TLongDoubleProcedure Uncommitted Interface > * TLongFloatProcedure Uncommitted Interface > * TLongFunction Uncommitted Interface > * TLongHashingStrategy Uncommitted Interface > * TLongIntProcedure Uncommitted Interface > * TLongLongProcedure Uncommitted Interface > * TLongObjectProcedure Uncommitted Interface > * TLongProcedure Uncommitted Interface > * TLongShortProcedure Uncommitted Interface > * TObjectByteProcedure Uncommitted Interface > * TObjectDoubleProcedure Uncommitted Interface > * TObjectFloatProcedure Uncommitted Interface > * TObjectFunction Uncommitted Interface > * TObjectHashingStrategy Uncommitted Interface > * TObjectIntProcedure Uncommitted Interface > * TObjectLongProcedure Uncommitted Interface > * TObjectObjectProcedure Uncommitted Interface > * TObjectProcedure Uncommitted Interface > * TObjectShortProcedure Uncommitted Interface > * TShortByteProcedure Uncommitted Interface > * TShortDoubleProcedure Uncommitted Interface > * TShortFloatProcedure Uncommitted Interface > * TShortFunction Uncommitted Interface > * TShortHashingStrategy Uncommitted Interface > * TShortIntProcedure Uncommitted Interface > * TShortLongProcedure Uncommitted Interface > * TShortObjectProcedure Uncommitted Interface > * TShortProcedure Uncommitted Interface > * TShortShortProcedure Uncommitted Interface > > > Imported interface Classification Comments > ======================= ============== =================================== > None > > The Jar file would go in "usr/share/lib/java/" > > 6. Resources and Schedule > 6.4. Steering Committee requested information > 6.4.1. Consolidation C-team Name: > SFW > 6.5. ARC review type: FastTrack > 6.6. ARC Exposure: open > > --Boundary_(ID_ZA2r1gYA7dNCO1l06AabtQ) Content-type: text/plain; name=FOSS_trove-2.0.4.txt Content-transfer-encoding: 7BIT Content-disposition: attachment; filename=FOSS_trove-2.0.4.txt FCL--FOSS Check List 1.0 Project Information 1.1 Name of project/component trove-2.0.4 Ver 2.0.4 1.2 Author of document Vivek R. Titarmare 2.0 Project Summary 2.1 Project Description The Trove library provides high speed regular and primitive collections for Java. 2.2 Release binding What is is the release binding? (see http://opensolaris.org/os/community/arc/policies/release-taxonomy/) [ ] Major [X] Minor [ ] Patch or Micro [ ] Unknown -- ARC review required 2.3 Type of project Is this case a Linux Familiarity project? [X] Yes [ ] No 2.4 Originating Community 2.4.1 Community Name Trove (http://trove4j.sourceforge.net) 2.4.2 Community Involvement Indicate Sun's involvement in the community [ ] Maintainer [ ] Contributor [X] Monitoring Will the project team work with the upstream community to resolve architectural issues of interest to Sun? [X] Yes [ ] No - briefly explain Will we or are we forking from the community? [ ] Yes - ARC review required prior to forking [X] No 3.0 Technical Description 3.1 Installation & Sharable 3.1.1S Solaris Installation - section only required for Solaris Software (see http://opensolaris.org/os/community/arc/policies/install-locations/ for details) Does this project follow the Install Locations best practice? [X] Yes [ ] No - ARC review required Does this project install into /usr under [sbin|bin|lib|include|man|share]? [X] Yes [ ] No or N/A Does this project install into /opt? [ ] Yes - explain below [X] No or N/A Does this project install into a different directory structure? [ ] Yes - ARC review required [X] No or N/A Do any of the components of this project conflict with anything under /usr? (see http://opensolaris.org/os/community/arc/caselog/2007/047/ for details) [ ] Yes - explain below [X] No If conflicts exist then will this project install under /usr/gnu? [ ] Yes [ ] No - ARC review required [X] N/A Is this project installing into /usr/sfw? [ ] Yes - ARC review required [X] No 3.1.1W Windows Installation - section only required for Windows Software (see http://sac.sfbay/WSARC/2002/494 for details) Does this project install software into a :\Program Files\Sun\ or :\Sun\ directory? [ ] Yes [ ] No - ARC review required Does the project use the Windows registry? [ ] Yes [ ] No - ARC review required Does the project use HKEY_LOCAL_MACHINE\SOFTWARE\Sun Microsystems\\ for the registry key? [ ] Yes [ ] No - ARC review required Is the project's stored location HKEY_LOCAL_MACHINE\SOFTWARE\Sun Microsystems\\\Path? [ ] Yes [ ] No - ARC review required 3.1.2 Share and Sharable Does the module include any components that are used or shared by other projects? [X] Yes [ ] No If yes are these components packaged to be shared with the other FOSS? [X] Yes [ ] No - ARC review required [ ] N/A Are these components already in the Solaris WOS? [ ] Yes [X] No - continue with next section (section 3.2) If yes are these newer versions being delivered? [ ] Yes [ ] No - ARC review required If yes are the newer versions replacing the existing versions? [ ] Yes [ ] No - ARC review required 3.2 Exported Libraries Are libraries being delivered by this project? [X] Yes [ ] No - continue with next section (section 3.3) Are 64-bit versions of the libraries being delivered? [X] Yes [ ] No - ARC review required Are static versions of the libraries being delivered? [ ] Yes - ARC review required [X] No 3.3 Services and the /etc Directory (see http://opensolaris.org/os/community/arc/policies/SMF-policy/) Does the project integrate anything into /etc/init.d or /etc/rc?.d? [ ] Yes - ARC review required [X] No Does the project integrate any new entries into /etc/inittab or /etc/inetd.conf? [ ] Yes - ARC review required [X] No Does the project integrate any private non-public files into /etc/default or /etc/ configuration files? [ ] Yes - ARC review required [X] No Does the service manifests method context grant rights above that of the noaccess user and basic privilege set? [ ] Yes - ARC review required [X] No 3.4 Security 3.4.1 Secure By Default (see http://opensolaris.org/os/community/arc/policies/secure-by-default/ for details) (see http://www.opensolaris.org/os/community/arc/policies/NITS-policy/ for details) (see parts of http://opensolaris.org/os/community/arc/policies/SMF-policy/ for addtional details) Are there any network services provided by this project? [ ] Yes [X] No - continue with the next section (section 3.4.2) Are network services enabled by default? [ ] Yes - ARC review required [ ] No [X] N/A Are network services automatically enabled by the project during installation? [ ] Yes - ARC review required [ ] No [X] N/A Are inbound network communications denied by default? [ ] Yes [ ] No - ARC review required [X] N/A Is inbound data checked to prevent content-based attacks? [ ] Yes [ ] No - ARC review required [X] N/A Is the outbound receiver authenticated? [ ] Yes [ ] No - ARC review required [X] N/A Is the receiver authenticated prior to receiving any sensitive outbound communication? [ ] Yes [ ] No - ARC review required [X] N/A 3.4.2 Authorization (see http://opensolaris.org/os/community/arc/bestpractices/rbac-intro/ and http://opensolaris.org/os/community/arc/bestpractices/rbac-profiles/ and http://opensolaris.org/os/community/arc/bestpractices/rbac-profiles/ for details) Are there any setuid/setgid privileged binaries in the project? [ ] Yes - ARC review required [X] No - continue with next section (section 3.4.3) If yes then are the setuid/setgid privileges handled by the use of roles? [ ] Yes [ ] No - ARC review required 3.4.3 Auditing (see http://opensolaris.org/os/community/arc/policies/audit-policy/ for details) (see http://opensolaris.org/os/community/arc/caselog/2003/397 for details) Does this component contain administrative or security enforcing software? [ ] Yes - ARC review required [X] No - continue to next section (section 3.4.4) (see http://opensolaris.org/os/community/arc/caselog/2003/397 for details) Do the components create audit logs detailing what took place including what event took place, who was involved, when the event took place? [ ] Yes - ARC contract and Audit project team review required [ ] No - ARC review required 3.4.4 Authentication (see http://opensolaris.org/os/community/arc/policies/PAM/) Do the components contain any authentication code? [ ] Yes [X] No - continue to next section (section 3.4.5) If yes do the components use PAM (plugable authentication modules) for authentication? [ ] Yes [ ] No - ARC review required If yes is a single PAM session maintained during authentication? [ ] Yes [ ] No - ARC review required If yes are the components sufficiently privileged to allow the requested operations (authentication, password change, process credential manipulation, audit state initialization)? [ ] Yes - briefly describe below [ ] No - ARC review required 3.4.5 Passwords (see http://opensolaris.org/os/community/arc/bestpractices/passwords-cli/ and http://opensolaris.org/os/community/arc/bestpractices/passwords-files/ for details) Do any of the components for the project deal with passwords? [ ] Yes [X] No - continue to next section (section 3.4.6) If yes are these passwords entered via the CLI or environment? [ ] Yes - ARC review required [ ] No Are passwords stored within the file system for the component? [ ] Yes [ ] No - continue to next section (section 3.4.6) If yes are the permissions on the file such to protect exposing the password(s)? [ ] Yes [ ] No - ARC review required 3.4.6 General Security Questions (see http://opensolaris.org/os/community/arc/bestpractices/security-questions/ for details) Are there any network protocols used by this project? [ ] Yes [X] No - continue with the next section (section 3.5) Do the components use standard network protocols? [ ] Yes [ ] No - ARC review required Do network services for the project make decisions based upon user, host or service identities? [ ] Yes - explain below [ ] No [ ] N/A Do the components make use of secret information during authentication and/or authorization? [ ] Yes - explain below [ ] No [ ] N/A 3.5 Networking Do the components access the network? [ ] Yes [X] No - continue with the next section (section 3.6) If yes do the components support IPv6? [ ] Yes [ ] No - ARC review required 3.6 Core Solaris Components Do the components of this project compete with or duplicate core Solaris components? [ ] Yes - ARC review required [X] No 4.0 Interfaces (see project proposal) --Boundary_(ID_ZA2r1gYA7dNCO1l06AabtQ) Content-type: text/plain; name=FastTrack_trove-2.0.4.txt Content-transfer-encoding: 7BIT Content-disposition: attachment; filename=FastTrack_trove-2.0.4.txt Template Version: @(#)sac_nextcase %I% %G% SMI This information is Copyright 2009 Sun Microsystems 1. Introduction 1.1. Project/Component Working Name: trove-2.0.4 1.2. Name of Document Author/Supplier: Author: Vivek R. Titarmare 1.3 Date of This Document: 06th April, 2009 2. Project Summary 2.1 Project Description The Trove library provides high speed regular and primitive collections for Java. 4. Technical Description: The Trove library provides high speed regular and primitive collections for Java. The GNU Trove library has two objectives: 1. Provide "free" (as in "free speech" and "free beer"), fast, lightweight implementations of the java.util Collections API. These implementations are designed to be pluggable replacements for their JDK equivalents. 2. Provide primitive collections with similar APIs to the above. This gap in the JDK is often addressed by using the "wrapper" classes (java.lang.Integer, java.lang.Float, etc.) with Object-based collections. For most applications, however, collections which store primitives directly will require less space and yield significant performance gains. 5. Interfaces The jar file "trove.jar" contains following interface. Exported interface Classification Interface type ============================= ============== ============== SUNWtrove Uncommitted Package Name gnu.trove * TByteByteProcedure Uncommitted Interface * TByteDoubleProcedure Uncommitted Interface * TByteFloatProcedure Uncommitted Interface * TByteFunction Uncommitted Interface * TByteHashingStrategy Uncommitted Interface * TByteIntProcedure Uncommitted Interface * TByteLongProcedure Uncommitted Interface * TByteObjectProcedure Uncommitted Interface * TByteProcedure Uncommitted Interface * TByteShortProcedure Uncommitted Interface * TDoubleByteProcedure Uncommitted Interface * TDoubleDoubleProcedure Uncommitted Interface * TDoubleFloatProcedure Uncommitted Interface * TDoubleFunction Uncommitted Interface * TDoubleHashingStrategy Uncommitted Interface * TDoubleIntProcedure Uncommitted Interface * TDoubleLongProcedure Uncommitted Interface * TDoubleObjectProcedure Uncommitted Interface * TDoubleProcedure Uncommitted Interface * TDoubleShortProcedure Uncommitted Interface * TFloatByteProcedure Uncommitted Interface * TFloatDoubleProcedure Uncommitted Interface * TFloatFloatProcedure Uncommitted Interface * TFloatFunction Uncommitted Interface * TFloatHashingStrategy Uncommitted Interface * TFloatIntProcedure Uncommitted Interface * TFloatLongProcedure Uncommitted Interface * TFloatObjectProcedure Uncommitted Interface * TFloatProcedure Uncommitted Interface * TFloatShortProcedure Uncommitted Interface * TIntByteProcedure Uncommitted Interface * TIntDoubleProcedure Uncommitted Interface * TIntFloatProcedure Uncommitted Interface * TIntFunction Uncommitted Interface * TIntHashingStrategy Uncommitted Interface * TIntIntProcedure Uncommitted Interface * TIntLongProcedure Uncommitted Interface * TIntObjectProcedure Uncommitted Interface * TIntProcedure Uncommitted Interface * TIntShortProcedure Uncommitted Interface * TLinkable Uncommitted Interface * TLongByteProcedure Uncommitted Interface * TLongDoubleProcedure Uncommitted Interface * TLongFloatProcedure Uncommitted Interface * TLongFunction Uncommitted Interface * TLongHashingStrategy Uncommitted Interface * TLongIntProcedure Uncommitted Interface * TLongLongProcedure Uncommitted Interface * TLongObjectProcedure Uncommitted Interface * TLongProcedure Uncommitted Interface * TLongShortProcedure Uncommitted Interface * TObjectByteProcedure Uncommitted Interface * TObjectDoubleProcedure Uncommitted Interface * TObjectFloatProcedure Uncommitted Interface * TObjectFunction Uncommitted Interface * TObjectHashingStrategy Uncommitted Interface * TObjectIntProcedure Uncommitted Interface * TObjectLongProcedure Uncommitted Interface * TObjectObjectProcedure Uncommitted Interface * TObjectProcedure Uncommitted Interface * TObjectShortProcedure Uncommitted Interface * TShortByteProcedure Uncommitted Interface * TShortDoubleProcedure Uncommitted Interface * TShortFloatProcedure Uncommitted Interface * TShortFunction Uncommitted Interface * TShortHashingStrategy Uncommitted Interface * TShortIntProcedure Uncommitted Interface * TShortLongProcedure Uncommitted Interface * TShortObjectProcedure Uncommitted Interface * TShortProcedure Uncommitted Interface * TShortShortProcedure Uncommitted Interface Imported interface Classification Comments ======================= ============== =================================== SUNWj5dev Committed Java Development Kit SUNWj5rt Committed Java Runtime library SUNWj6dev Committed Java Development Kit SUNWj6rt Committed Java Runtime library The Jar file would go in "usr/share/lib/java/" 6. Resources and Schedule 6.4. Steering Committee requested information 6.4.1. Consolidation C-team Name: SFW 6.5. ARC review type: FastTrack 6.6. ARC Exposure: open --Boundary_(ID_ZA2r1gYA7dNCO1l06AabtQ)-- From margot.miller@sun.com Tue May 12 14:35:14 2009 Received: from sunmail2sca.sfbay.sun.com (sunmail2sca.SFBay.Sun.COM [129.145.155.234]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4CLZEr8009958 for ; Tue, 12 May 2009 14:35:14 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail2sca.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4CLZC6B006532; Tue, 12 May 2009 14:35:12 -0700 (PDT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJJ00F01VYOGS00@brm-avmta-1.central.sun.com>; Tue, 12 May 2009 15:35:12 -0600 (MDT) Received: from jurassic-x4600.sfbay.sun.com ([129.146.17.63]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJJ00MMDVYM2JC0@brm-avmta-1.central.sun.com>; Tue, 12 May 2009 15:35:10 -0600 (MDT) Received: from [10.7.250.251] (punchin-client-10-7-250-251.SFBay.Sun.COM [10.7.250.251]) by jurassic-x4600.sfbay.sun.com (8.14.3+Sun/8.14.3) with ESMTP id n4CLZ9LN859307; Tue, 12 May 2009 14:35:09 -0700 (PDT) Date: Tue, 12 May 2009 14:35:09 -0700 From: Margot Miller Subject: Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] To: LSARC-ext@sun.com Cc: Vivek Titarmare Message-id: <4A09EB8D.6090800@sun.com> MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 User-Agent: Thunderbird 2.0b1 (X11/20070115) Status: RO Content-Length: 1052 Hey All, I am derailing this case as it misses the non-controversial requirement for a fast track and would like an email vote on this case by Friday May 15th. My impression from today's meeting was that LSARC will have a future case that will address the issue of how to publicize interface classifications for jar files and that it was okay for this project team and other teams to optionally ship a man page for a jar file. This would be setting precedent. Below is the proposed verbiage for the opinion. The project team is delivering a man page for the java jar file. It was noted that this is not standard practice as most Java developers look for java documentation via javadocs, not via man. However, others stated that having a minimal man page for a java jar file would allow the interface classification to be visible to the end user and a few other ARC cases have shipped these man pages. This case proposes letting the project team and others optionally ship a man page for a jar file. I vote against. Thanks, Margot From storycrafter@gmail.com Tue May 12 15:28:46 2009 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4CMSkRE011567 for ; Tue, 12 May 2009 15:28:46 -0700 (PDT) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by sunmail5.uk.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n4CMSgrs023713; Tue, 12 May 2009 23:28:44 +0100 (BST) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJJ0030FYFUWL00@nwk-avmta-2.sfbay.sun.com>; Tue, 12 May 2009 15:28:42 -0700 (PDT) Received: from sca-ea-mail-4.sun.com ([192.18.43.22]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJJ0004EYFU9450@nwk-avmta-2.sfbay.sun.com>; Tue, 12 May 2009 15:28:42 -0700 (PDT) Received: from relay11i.sun.com (ip121.net129179-4.block1.us.syntegra.com [129.179.4.121]) by sca-ea-mail-4.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n4CMFAWs024897; Tue, 12 May 2009 22:28:42 +0000 (GMT) Received: from mmp13es.mmp.us.syntegra.com ([160.41.208.13] [160.41.208.13]) by relay11i.sun.com with ESMTP id BT-MMP-2133897; Tue, 12 May 2009 22:28:41 +0000 (Z) Received: from relay13i.sun.com (relay13i.sun.com [129.179.4.123]) by mmp13es.mmp.us.syntegra.com with ESMTP id BT-MMP-32153111; Tue, 12 May 2009 22:28:41 +0000 (Z) Received: from mail-fx0-f165.google.com ([209.85.220.165] [209.85.220.165]) by relay1i.sun.com with ESMTP id BT-MMP-11436518; Tue, 12 May 2009 22:28:41 +0000 (Z) Received: by mail-fx0-f165.google.com with SMTP id 9so287831fxm.8 for ; Tue, 12 May 2009 15:28:33 -0700 (PDT) Received: by 10.86.3.11 with SMTP id 11mr445006fgc.11.1242167313617; Tue, 12 May 2009 15:28:33 -0700 (PDT) Received: from ?172.16.202.89? (68-252-106-20.ded.ameritech.net [68.252.106.20]) by mx.google.com with ESMTPS id d6sm763642fga.27.2009.05.12.15.28.31 (version=TLSv1/SSLv3 cipher=RC4-MD5) ; Tue, 12 May 2009 15:28:32 -0700 (PDT) Date: Tue, 12 May 2009 17:28:29 -0500 From: Mark Martin Subject: Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] In-reply-to: <4A09EB8D.6090800@sun.com> To: Margot Miller Cc: LSARC-ext@sun.com Message-id: <4A09F80D.6080305@gmail.com> MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1; format=flowed Content-transfer-encoding: 7BIT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=domainkey-signature:received:received:message-id:date:from :user-agent:mime-version:to:cc:subject:references:in-reply-to :content-type:content-transfer-encoding; bh=Q9CYKZnVg7FqFM6aJJR4ylyFc6q3fMaQFOGbFweC1qk=; b=E/wyV+vQs7GNyAqHeGCHVbsAQVXQ2Pz/J3YQFG2qJnHAfP4xGWFjEyXOiI6MuVSSDt QqwC1/AfhTlRBzjnm2AworrpN2XalfoB+nSerQ2whGoCq0yfsGZU3RsikUPzIPy/o/ma jCO0EW5UrqknBY8uy/jQ/wlmo+K+PQGmduYIw= DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=message-id:date:from:user-agent:mime-version:to:cc:subject :references:in-reply-to:content-type:content-transfer-encoding; b=HCXD/FjwWd5pU2806XXR8caIKtmGFGV1yF0ucfK14gyDHCU73Wh68DNot7RHyzFwdr lzGIDP0/VR5xEk+uqRm998SsRcFetp50qeK9FeGdPG2SaQEBn2jU2tbnJw2lBM78r3bD Hm0eKYIBqmyK9Psespn6Lfd4cu706G8ZOwlic= X-PMX-Version: 5.4.1.325704 X-Brightmail-Tracker: AAAAAA== X-Antispam: No, score=-2.6/5.0, scanned in 0.096sec at (localhost [127.0.0.1]) by smf-spamd v1.3.1 - http://smfs.sf.net/ References: <4A09EB8D.6090800@sun.com> User-Agent: Thunderbird 2.0.0.21 (Windows/20090302) Status: RO Content-Length: 3962 Margot Miller wrote: > Hey All, > > I am derailing this case as it misses the non-controversial requirement > for a fast track and would like an email vote on this case by > Friday May 15th. > > My impression from today's meeting was that LSARC will have > a future case that will address the issue of how to publicize interface > classifications for jar files and that it was okay for this project > team and > other teams to optionally ship a man page for a jar file. This would > be setting > precedent. > > Below is the proposed verbiage for the opinion. > > The project team is delivering a man page for the java jar file. It was > noted that this is not standard practice as most Java developers look > for java documentation via javadocs, not via man. However, others > stated that > having a minimal man page for a java jar file would allow the interface > classification to be visible to the end user and a few other ARC cases > have > shipped these man pages. This case proposes letting the project team > and > others optionally ship a man page for a jar file. > > I vote against. I'm presuming you're voting against this case as spec'd, with the offered opinion, correct? The project team hasn't been given a chance to make any advised or required modifications, so it seems a bit imprudent to deny a case in that manner. The intent here is that the man page inclusion precedent will be set here and now, right? If the vote sustains for approval with a man page, then there's no need to bring another case forth, right? Seems like Jim's gap would be addressed in that case. Or should the "optionally" token in the opinion text be taken as a failure to cover the gap? On the topic, though, I think Jim brings a very good point -- how does the project team communicate the expected stability? Lloyd brings an interesting solution with the use of Java Attributes as documentation decoration, although I have a few issues with it on technical grounds. For those not on the call, I see the problem as this: At some point, Sun must have established the precedent and the _expectation_ that stability levels of most types of interfaces were to be expressed to consumers of those interfaces in the man pages. I'm sorry I can't quote chapter and verse. This is, as far as I'm aware, a communication norm that I don't see in other systems, Sun originated or otherwise. Java certainly does not have it as part of any standard, nor does Linux, as we discussed in the bsh vs. beanshell debate in PSARC. As we're ramping up integration of java components, we're creating new gaps from old practice. One of these is the nomenclature surrounding the naming of the jar files themselves (jars as "libraries"), which I won't go into here. The other is the point which Jim raised -- there's currently no expected way to communicate stability level other than man pages. Adding man pages to java jar projects (projects which deliver only .jars) _feels_ wrong, since the consumers of these jars aren't going to expect to find a man page -- they're on a very different usage model than most other consumers of C libraries and command line interfaces. Consumers in this case typically use JavaDocs as their source of API information, and that _feels_ like a better place to put that information. If the man pages are explicitly NOT to be delivered with "jar" projects, then where is the stability level expressed? If in JavaDocs, then what does that look like, assuming we need precision for that nomenclature? Does the very same taxonomy even apply to jars? The current taxonomy is, as a core component of its definition, dependent on release versions of Solaris. Obviously, java jar's are more tightly coupled to Java versions than on OS release versions, no? > > Thanks, > Margot > > > _______________________________________________ > opensolaris-arc mailing list > opensolaris-arc@opensolaris.org From margot.miller@sun.com Tue May 12 15:57:21 2009 Received: from sunmail4.singapore.sun.com (sunmail4.Singapore.Sun.COM [129.158.71.19]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4CMvKBq012521 for ; Tue, 12 May 2009 15:57:20 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail4.singapore.sun.com (8.13.4+Sun/8.13.3/ENSMAIL,v2.2) with ESMTP id n4CMvFcV024444; Wed, 13 May 2009 06:57:17 +0800 (SGT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJJ00109ZRF4D00@brm-avmta-1.central.sun.com>; Tue, 12 May 2009 16:57:15 -0600 (MDT) Received: from jurassic-x4600.sfbay.sun.com ([129.146.17.59]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJJ000JXZRE4600@brm-avmta-1.central.sun.com>; Tue, 12 May 2009 16:57:15 -0600 (MDT) Received: from [10.7.250.251] (punchin-client-10-7-250-251.SFBay.Sun.COM [10.7.250.251]) by jurassic-x4600.sfbay.sun.com (8.14.3+Sun/8.14.3) with ESMTP id n4CMvCsj872661; Tue, 12 May 2009 15:57:13 -0700 (PDT) Date: Tue, 12 May 2009 15:57:12 -0700 From: Margot Miller Subject: Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] In-reply-to: <4A09F80D.6080305@gmail.com> To: Mark Martin Cc: LSARC-ext@sun.com Message-id: <4A09FEC8.5060105@sun.com> MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <4A09EB8D.6090800@sun.com> <4A09F80D.6080305@gmail.com> User-Agent: Thunderbird 2.0b1 (X11/20070115) Status: RO Content-Length: 4157 The case hasn't been denied; it's been derailed so an opinion can be written and it will be clear if precedence has been set or not with this case. From the LSARC meeting today, it seemed like the majority of the committee thought it was fine for the project team and other teams to ship a man page. I don't think that is the right way to go, in that some jar files will have man pages, some won't and Java developers probably won't look for a man page anyway. I think Jim identified correctly a real problem - how do we communicate the interface classification of a jar file to the end user. I think we need a comprehensive and consistent solution. And the javadocs proposal has a lot of merit to it. We are voting on whether the project team should be allowed to ship the man page. (I thought the majority wanted that but need to take an explicit vote) So if after the vote, I am in the minority, than the case is approved and I write a section stating the minority opinion. If after the vote, I am in the majority, then the case is approved, the team doesn't ship a man page, and the minority can write their section of the opinion if they chose. Margot Mark Martin wrote: > > I'm presuming you're voting against this case as spec'd, with the > offered opinion, correct? The project team hasn't been given a chance > to make any advised or required modifications, so it seems a bit > imprudent to deny a case in that manner. > The intent here is that the man page inclusion precedent will be set > here and now, right? If the vote sustains for approval with a man > page, then there's no need to bring another case forth, right? Seems > like Jim's gap would be addressed in that case. Or should the > "optionally" token in the opinion text be taken as a failure to cover > the gap? > > On the topic, though, I think Jim brings a very good point -- how does > the project team communicate the expected stability? Lloyd brings an > interesting solution with the use of Java Attributes as documentation > decoration, although I have a few issues with it on technical > grounds. For those not on the call, I see the problem as this: > > At some point, Sun must have established the precedent and the > _expectation_ that stability levels of most types of interfaces were > to be expressed to consumers of those interfaces in the man pages. > I'm sorry I can't quote chapter and verse. This is, as far as I'm > aware, a communication norm that I don't see in other systems, Sun > originated or otherwise. Java certainly does not have it as part of > any standard, nor does Linux, as we discussed in the bsh vs. beanshell > debate in PSARC. > > As we're ramping up integration of java components, we're creating new > gaps from old practice. One of these is the nomenclature surrounding > the naming of the jar files themselves (jars as "libraries"), which I > won't go into here. The other is the point which Jim raised -- > there's currently no expected way to communicate stability level other > than man pages. Adding man pages to java jar projects (projects which > deliver only .jars) _feels_ wrong, since the consumers of these jars > aren't going to expect to find a man page -- they're on a very > different usage model than most other consumers of C libraries and > command line interfaces. Consumers in this case typically use > JavaDocs as their source of API information, and that _feels_ like a > better place to put that information. > > If the man pages are explicitly NOT to be delivered with "jar" > projects, then where is the stability level expressed? If in > JavaDocs, then what does that look like, assuming we need precision > for that nomenclature? > > Does the very same taxonomy even apply to jars? The current taxonomy > is, as a core component of its definition, dependent on release > versions of Solaris. Obviously, java jar's are more tightly coupled > to Java versions than on OS release versions, no? > >> >> Thanks, >> Margot >> >> >> _______________________________________________ >> opensolaris-arc mailing list >> opensolaris-arc@opensolaris.org > From Lloyd.Chambers@sun.com Tue May 12 16:56:51 2009 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4CNuouP010379 for ; Tue, 12 May 2009 16:56:50 -0700 (PDT) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by sunmail5.uk.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n4CNudJK017620 for <@sunmail2sca.sfbay.sun.com:LSARC-ext@sun.com>; Wed, 13 May 2009 00:56:49 +0100 (BST) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJK009012IMN700@nwk-avmta-2.sfbay.sun.com> for LSARC-ext@sun.com (ORCPT LSARC-ext@sun.com); Tue, 12 May 2009 16:56:46 -0700 (PDT) Received: from sca-es-mail-1.sun.com ([192.18.43.132]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJK000922IM8ZA0@nwk-avmta-2.sfbay.sun.com> for LSARC-ext@sun.com (ORCPT LSARC-ext@sun.com); Tue, 12 May 2009 16:56:46 -0700 (PDT) Received: from fe-sfbay-10.sun.com ([192.18.43.129]) by sca-es-mail-1.sun.com (8.13.7+Sun/8.12.9) with ESMTP id n4CNum7e005234 for ; Tue, 12 May 2009 16:56:48 -0700 (PDT) Received: from conversion-daemon.fe-sfbay-10.sun.com by fe-sfbay-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJK00H002BK7V00@fe-sfbay-10.sun.com> for LSARC-ext@sun.com (ORCPT LSARC-ext@sun.com); Tue, 12 May 2009 16:56:48 -0700 (PDT) Received: from [192.168.1.5] ([unknown] [208.74.178.82]) by fe-sfbay-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJK008N32IL4830@fe-sfbay-10.sun.com>; Tue, 12 May 2009 16:56:47 -0700 (PDT) Date: Tue, 12 May 2009 16:56:44 -0700 From: Lloyd Chambers Subject: Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] In-reply-to: <4A09FEC8.5060105@sun.com> Sender: Lloyd.Chambers@sun.com To: Margot Miller Cc: Mark Martin , LSARC-ext@sun.com Message-id: <5F22BE17-DE67-43F3-91D5-E4B6FCA162E1@sun.com> MIME-version: 1.0 X-Mailer: Apple Mail (2.930.4) Content-type: multipart/alternative; boundary="Boundary_(ID_J92omPhK2iesyik8UXW/lA)" X-PMX-Version: 5.4.1.325704 References: <4A09EB8D.6090800@sun.com> <4A09F80D.6080305@gmail.com> <4A09FEC8.5060105@sun.com> Status: RO Content-Length: 19945 --Boundary_(ID_J92omPhK2iesyik8UXW/lA) Content-type: text/plain; CHARSET=US-ASCII; delsp=yes; format=flowed Content-transfer-encoding: 7BIT In GlassFish V3, here is what I'm doing (one example). I've created the annotation @Taxonomy, which takes a value of type Stability. This is what it looks like in the Javadoc. One can click through the annotation and see the actual definition of the stability level. This is available at the java package level or class level. Overview Package Class Use Tree Deprecated Index Help PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES @Taxonomy(stability=UNCOMMITTED) Package org.glassfish.admin.amx.core Class level: org.glassfish.admin.amx.core Class AMXConstants java.lang.Object org.glassfish.admin.amx.core.AMXConstants @Taxonomy(stability=UNCOMMITTED) public final class AMXConstants extends java.lang.Object Keys for AMX metadata found in the various javax.management.Desriptors found in MBeanInfo and its contents. On May 12, 2009, at 3:57 PM, Margot Miller wrote: > The case hasn't been denied; it's been derailed so an opinion can be > written and it will be clear if precedence has been set or not with > this case. > > From the LSARC meeting today, it seemed like the majority of > the committee thought it was fine for the project team and other > teams to ship a man page. I don't think that is the right way > to go, in that some jar files will have man pages, some won't > and Java developers probably won't look for a man page > anyway. > > I think Jim identified correctly a real problem - how do > we communicate the interface classification of a jar file to the > end user. I think we need a comprehensive and > consistent solution. And the javadocs proposal has a lot of > merit to it. > We are voting on whether the project team should be allowed > to ship the man page. (I thought the majority wanted that > but need to take an explicit vote) > > So if after the vote, I am in the minority, than the case is approved > and I write a section stating the minority opinion. If after the > vote, > I am in the majority, then the case is approved, the team doesn't > ship a man page, and the minority can write their section of > the opinion if they chose. > > Margot > > > Mark Martin wrote: >> >> I'm presuming you're voting against this case as spec'd, with the >> offered opinion, correct? The project team hasn't been given a >> chance to make any advised or required modifications, so it seems a >> bit imprudent to deny a case in that manner. >> The intent here is that the man page inclusion precedent will be >> set here and now, right? If the vote sustains for approval with a >> man page, then there's no need to bring another case forth, right? >> Seems like Jim's gap would be addressed in that case. Or should >> the "optionally" token in the opinion text be taken as a failure to >> cover the gap? >> >> On the topic, though, I think Jim brings a very good point -- how >> does the project team communicate the expected stability? Lloyd >> brings an interesting solution with the use of Java Attributes as >> documentation decoration, although I have a few issues with it on >> technical grounds. For those not on the call, I see the problem as >> this: >> >> At some point, Sun must have established the precedent and the >> _expectation_ that stability levels of most types of interfaces >> were to be expressed to consumers of those interfaces in the man >> pages. I'm sorry I can't quote chapter and verse. This is, as far >> as I'm aware, a communication norm that I don't see in other >> systems, Sun originated or otherwise. Java certainly does not have >> it as part of any standard, nor does Linux, as we discussed in the >> bsh vs. beanshell debate in PSARC. >> >> As we're ramping up integration of java components, we're creating >> new gaps from old practice. One of these is the nomenclature >> surrounding the naming of the jar files themselves (jars as >> "libraries"), which I won't go into here. The other is the point >> which Jim raised -- there's currently no expected way to >> communicate stability level other than man pages. Adding man pages >> to java jar projects (projects which deliver only .jars) _feels_ >> wrong, since the consumers of these jars aren't going to expect to >> find a man page -- they're on a very different usage model than >> most other consumers of C libraries and command line interfaces. >> Consumers in this case typically use JavaDocs as their source of >> API information, and that _feels_ like a better place to put that >> information. >> >> If the man pages are explicitly NOT to be delivered with "jar" >> projects, then where is the stability level expressed? If in >> JavaDocs, then what does that look like, assuming we need precision >> for that nomenclature? >> >> Does the very same taxonomy even apply to jars? The current >> taxonomy is, as a core component of its definition, dependent on >> release versions of Solaris. Obviously, java jar's are more >> tightly coupled to Java versions than on OS release versions, no? >> >>> >>> Thanks, >>> Margot >>> >>> >>> _______________________________________________ >>> opensolaris-arc mailing list >>> opensolaris-arc@opensolaris.org >> > Lloyd Chambers lloyd.chambers@sun.com GlassFish Team --Boundary_(ID_J92omPhK2iesyik8UXW/lA) Content-type: multipart/related; boundary="Boundary_(ID_tDVkQ+LqtvAlC5+7rcHDXA)"; type="text/html" --Boundary_(ID_tDVkQ+LqtvAlC5+7rcHDXA) Content-type: text/html; CHARSET=US-ASCII Content-transfer-encoding: QUOTED-PRINTABLE
In GlassFish V3, here = is what I'm doing (one example).  I've created the annotation @T= axonomy, which takes a value of type Stability.  This is what it= looks like in the Javadoc.  One can click through the annotatio= n and see the actual definition of the stability level.
This is available at the java package level or class leve= l.

Overview <= td bgcolor=3D"#FFFFFF" class=3D"NavBarCell1Rev" style=3D"background-c= olor: rgb(0, 0, 139); color: rgb(255, 255, 255); "> Package =
Class Use Tree Deprecated Index&= nbsp;Help 
&n= bsp;PREV PACKA= GE   NEXT PACKAGEFRAMES    NO FRAMES    
@Taxonomy(stability=3DUNCOMMITTED)

Package org.gla= ssfish.admin.amx.core



Class level:<= /span>
org= .glassfish.admin.amx.core 

Class AMXConstants

java.lang.Object
  3D"extendedorg.glassfish.admin.amx.core.AM=
XConstants

@Taxonomy(stability=3DUNCOMMITTED)
public final class AMXConstants
extends java.lang.Ob=
ject

Keys for AMX metadata found in the variou= s javax.management.Desriptors found in MBeanInfo and its contents.




On May 12, = 2009, at 3:57 PM, Margot Miller wrote:

The case hasn't been de= nied; it's been derailed so an opinion can be
written and it will = be clear if precedence has been set or not with this case.

Fro= m the LSARC meeting today, it seemed like the majority of
the comm= ittee thought it was fine for the project team and other
teams to = ship a man page.  I don't think that is the right way
to go, = in that some jar files will have man pages, some won't
and Java de= velopers probably won't look for a man page
anyway.

I think= Jim identified correctly a real problem - how do
we communicate t= he interface classification of a jar file to the
end user.  I=  think we need a comprehensive and
consistent solution. &nbs= p; And the javadocs proposal has a lot of
merit to it.
We= are voting on whether the project team should be allowed
to ship = the man page.  (I thought the majority wanted that
but need t= o take an explicit vote)

So if after the vote, I am in the min= ority, than the case is approved
and I write a section stating the= minority opinion.  If after the vote,
I am in the majority, = then the case is approved, the team doesn't
ship a man page, and t= he minority can write their section of
the opinion if they chose.<= br>
Margot


Mark Martin wrote:

I'm presuming you're v= oting against this case as spec'd, with the offered opinion, correct?=  The project team hasn't been given a chance to make any advise= d or required modifications, so it seems a bit imprudent to deny a ca= se in that manner.
The inte= nt here is that the man page inclusion precedent will be set here and= now, right?  If the vote sustains for approval with a man page,= then there's no need to bring another case forth, right?  Seems= like Jim's gap would be addressed in that case.  Or should the = "optionally" token in the opinion text be taken as a failure to cover= the gap?

=
On the topic, though, I think Jim brings a = very good point -- how does the project team communicate the expected= stability?  Lloyd brings an interesting solution with the use o= f Java Attributes as documentation decoration, although I have a few = issues with it on technical grounds.  For those not on the call,= I see the problem as this:

At some point, Sun must h= ave established the precedent and the _expectation_ that stability le= vels of most types of interfaces were to be expressed to consumers of= those interfaces in the man pages.  I'm sorry I can't quote cha= pter and verse.  This is, as far as I'm aware, a communication n= orm that I don't see in other systems, Sun originated or otherwise. &= nbsp;Java certainly does not have it as part of any standard, nor doe= s Linux, as we discussed in the bsh vs. beanshell debate in PSARC.

As we're ramping up integration of java components, we'= re creating new gaps from old practice.  One of these is the nom= enclature surrounding the naming of the jar files themselves (jars as= "libraries"), which I won't go into here.  The other is the poi= nt which Jim raised -- there's currently no expected way to communica= te stability level other than man pages.  Adding man pages to ja= va jar projects (projects which deliver only .jars) _feels_ wrong, si= nce the consumers of these jars aren't going to expect to find a man = page -- they're on a very different usage model than most other consu= mers of C libraries and command line interfaces.  Consumers in t= his case typically use JavaDocs as their source of API information, a= nd that _feels_ like a better place to put that information.

If the man pages are explicitly NOT to be delivered with "j= ar" projects, then where is the stability level expressed?  &nbs= p; If in JavaDocs, then what does that look like, assuming we ne= ed precision for that nomenclature?

Does the very sa= me taxonomy even apply to jars?   The current taxonomy is, = as a core component of its definition, dependent on release versions = of Solaris.  Obviously, java jar's are more tightly coupled to J= ava versions than on OS release versions, no?


Thanks,
Margot


_________________________________= ______________
opensolaris-arc mailing list
<= a href=3D"mailto:opensolaris-arc@opensolaris.org">opensolaris-arc@ope= nsolaris.org



Lloyd Chambe= rs
GlassFish Team



--Boundary_(ID_tDVkQ+LqtvAlC5+7rcHDXA) Content-id: Content-type: image/gif; name=inherit.gif; x-unix-mode=0666 Content-transfer-encoding: BASE64 Content-disposition: inline; filename=inherit.gif R0lGODlhDwAOAIAAAP///wAAACwAAAAADwAOAAACGISPCaG9rhhEcppq8dSQO9+A UUCWpoVOBQA7 --Boundary_(ID_tDVkQ+LqtvAlC5+7rcHDXA)-- --Boundary_(ID_J92omPhK2iesyik8UXW/lA)-- From Lloyd.Chambers@sun.com Tue May 12 17:04:25 2009 Received: from sunmail4.singapore.sun.com (sunmail4.Singapore.Sun.COM [129.158.71.19]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4D04Ouc010494 for ; Tue, 12 May 2009 17:04:24 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail4.singapore.sun.com (8.13.4+Sun/8.13.3/ENSMAIL,v2.2) with ESMTP id n4D04EPu028222 for <@sunmail2sca.sfbay.sun.com:LSARC-ext@sun.com>; Wed, 13 May 2009 08:04:23 +0800 (SGT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJK008032V9FI00@brm-avmta-1.central.sun.com> for LSARC-ext@sun.com (ORCPT LSARC-ext@sun.com); Tue, 12 May 2009 18:04:21 -0600 (MDT) Received: from sca-es-mail-2.sun.com ([192.18.43.133]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJK000DP2V84650@brm-avmta-1.central.sun.com> for LSARC-ext@sun.com (ORCPT LSARC-ext@sun.com); Tue, 12 May 2009 18:04:20 -0600 (MDT) Received: from fe-sfbay-10.sun.com ([192.18.43.129]) by sca-es-mail-2.sun.com (8.13.7+Sun/8.12.9) with ESMTP id n4D04KMk023874 for ; Tue, 12 May 2009 17:04:20 -0700 (PDT) Received: from conversion-daemon.fe-sfbay-10.sun.com by fe-sfbay-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJK004002TNO200@fe-sfbay-10.sun.com> for LSARC-ext@sun.com (ORCPT LSARC-ext@sun.com); Tue, 12 May 2009 17:04:20 -0700 (PDT) Received: from [192.168.1.5] ([unknown] [208.74.178.82]) by fe-sfbay-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJK008AW2V74860@fe-sfbay-10.sun.com>; Tue, 12 May 2009 17:04:20 -0700 (PDT) Date: Tue, 12 May 2009 17:04:19 -0700 From: Lloyd Chambers Subject: Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] In-reply-to: <4A09FEC8.5060105@sun.com> Sender: Lloyd.Chambers@sun.com To: Margot Miller Cc: Mark Martin , LSARC-ext@sun.com Message-id: MIME-version: 1.0 X-Mailer: Apple Mail (2.930.4) Content-type: multipart/alternative; boundary="Boundary_(ID_gplwJ7+nfROVELzDlfLGbA)" X-PMX-Version: 5.4.1.325704 References: <4A09EB8D.6090800@sun.com> <4A09F80D.6080305@gmail.com> <4A09FEC8.5060105@sun.com> Status: RO Content-Length: 13018 --Boundary_(ID_gplwJ7+nfROVELzDlfLGbA) Content-type: text/plain; CHARSET=US-ASCII; delsp=yes; format=flowed Content-transfer-encoding: 7BIT "how do we communicate the interface classification of a jar file" This is a multi-level. Plenty of jar files contain classes or classes with methods and other stuff which is not intended for public consumption. Simply because somthing is "public" or "protected" is not a good way to assume it is an API. So classifying a jar file is ultra-coarse, and maybe not a good idea unless qualified with: - all classes and methods unless otherwise annotated (risky) - no classes unless explicitly annotated (better) eg an "opt out" or "opt in" approach. Lloyd On May 12, 2009, at 3:57 PM, Margot Miller wrote: > The case hasn't been denied; it's been derailed so an opinion can be > written and it will be clear if precedence has been set or not with > this case. > > From the LSARC meeting today, it seemed like the majority of > the committee thought it was fine for the project team and other > teams to ship a man page. I don't think that is the right way > to go, in that some jar files will have man pages, some won't > and Java developers probably won't look for a man page > anyway. > > I think Jim identified correctly a real problem - how do > we communicate the interface classification of a jar file to the > end user. I think we need a comprehensive and > consistent solution. And the javadocs proposal has a lot of > merit to it. > We are voting on whether the project team should be allowed > to ship the man page. (I thought the majority wanted that > but need to take an explicit vote) > > So if after the vote, I am in the minority, than the case is approved > and I write a section stating the minority opinion. If after the > vote, > I am in the majority, then the case is approved, the team doesn't > ship a man page, and the minority can write their section of > the opinion if they chose. > > Margot > > > Mark Martin wrote: >> >> I'm presuming you're voting against this case as spec'd, with the >> offered opinion, correct? The project team hasn't been given a >> chance to make any advised or required modifications, so it seems a >> bit imprudent to deny a case in that manner. >> The intent here is that the man page inclusion precedent will be >> set here and now, right? If the vote sustains for approval with a >> man page, then there's no need to bring another case forth, right? >> Seems like Jim's gap would be addressed in that case. Or should >> the "optionally" token in the opinion text be taken as a failure to >> cover the gap? >> >> On the topic, though, I think Jim brings a very good point -- how >> does the project team communicate the expected stability? Lloyd >> brings an interesting solution with the use of Java Attributes as >> documentation decoration, although I have a few issues with it on >> technical grounds. For those not on the call, I see the problem as >> this: >> >> At some point, Sun must have established the precedent and the >> _expectation_ that stability levels of most types of interfaces >> were to be expressed to consumers of those interfaces in the man >> pages. I'm sorry I can't quote chapter and verse. This is, as far >> as I'm aware, a communication norm that I don't see in other >> systems, Sun originated or otherwise. Java certainly does not have >> it as part of any standard, nor does Linux, as we discussed in the >> bsh vs. beanshell debate in PSARC. >> >> As we're ramping up integration of java components, we're creating >> new gaps from old practice. One of these is the nomenclature >> surrounding the naming of the jar files themselves (jars as >> "libraries"), which I won't go into here. The other is the point >> which Jim raised -- there's currently no expected way to >> communicate stability level other than man pages. Adding man pages >> to java jar projects (projects which deliver only .jars) _feels_ >> wrong, since the consumers of these jars aren't going to expect to >> find a man page -- they're on a very different usage model than >> most other consumers of C libraries and command line interfaces. >> Consumers in this case typically use JavaDocs as their source of >> API information, and that _feels_ like a better place to put that >> information. >> >> If the man pages are explicitly NOT to be delivered with "jar" >> projects, then where is the stability level expressed? If in >> JavaDocs, then what does that look like, assuming we need precision >> for that nomenclature? >> >> Does the very same taxonomy even apply to jars? The current >> taxonomy is, as a core component of its definition, dependent on >> release versions of Solaris. Obviously, java jar's are more >> tightly coupled to Java versions than on OS release versions, no? >> >>> >>> Thanks, >>> Margot >>> >>> >>> _______________________________________________ >>> opensolaris-arc mailing list >>> opensolaris-arc@opensolaris.org >> > Lloyd Chambers lloyd.chambers@sun.com GlassFish Team --Boundary_(ID_gplwJ7+nfROVELzDlfLGbA) Content-type: text/html; CHARSET=US-ASCII Content-transfer-encoding: QUOTED-PRINTABLE "how do we communicate= the interface classification of a jar file"

This = is a multi-level.

Plenty of jar files contai= n classes or classes with methods and other stuff which is not intend= ed for public consumption.  Simply because somthing is "public" = or "protected" is not a good way to assume it is an API.
So classifying a jar file is ultra-coarse, and maybe not= a good idea unless qualified with:

- all cl= asses and methods unless otherwise annotated (risky)
- no c= lasses unless explicitly annotated (better)

= eg an "opt out" or "opt in" approach.

Lloyd<= br>


On May 12, 2009, at 3:57 PM, Margot M= iller wrote:

The case hasn't been denied; it's been derailed s= o an opinion can be
written and it will be clear if precedence has= been set or not with this case.

From the LSARC meeting today,= it seemed like the majority of
the committee thought it was fine = for the project team and other
teams to ship a man page.  I d= on't think that is the right way
to go, in that some jar files wil= l have man pages, some won't
and Java developers probably won't lo= ok for a man page
anyway.

I think Jim identified correctly = a real problem - how do
we communicate the interface classificatio= n of a jar file to the
end user.  I  think we need a com= prehensive and
consistent solution.   And the javadocs p= roposal has a lot of
merit to it.
We are voting on whether the= project team should be allowed
to ship the man page.  (I tho= ught the majority wanted that
but need to take an explicit vote)
So if after the vote, I am in the minority, than the case is ap= proved
and I write a section stating the minority opinion.  I= f after the vote,
I am in the majority, then the case is approved,= the team doesn't
ship a man page, and the minority can write thei= r section of
the opinion if they chose.

Margot


M= ark Martin wrote:

I'm presuming you're voting against this case as= spec'd, with the offered opinion, correct?  The project team ha= sn't been given a chance to make any advised or required modification= s, so it seems a bit imprudent to deny a case in that manner.
The intent here is that the man pa= ge inclusion precedent will be set here and now, right?  If the = vote sustains for approval with a man page, then there's no need to b= ring another case forth, right?  Seems like Jim's gap would be a= ddressed in that case.  Or should the "optionally" token in the = opinion text be taken as a failure to cover the gap?
=

= On the topic, though, I think Jim brings a very good point -- how doe= s the project team communicate the expected stability?  Lloyd br= ings an interesting solution with the use of Java Attributes as docum= entation decoration, although I have a few issues with it on technica= l grounds.  For those not on the call, I see the problem as this= :

At some point, Sun must have established the preced= ent and the _expectation_ that stability levels of most types of inte= rfaces were to be expressed to consumers of those interfaces in the m= an pages.  I'm sorry I can't quote chapter and verse.  This= is, as far as I'm aware, a communication norm that I don't see in ot= her systems, Sun originated or otherwise.  Java certainly does n= ot have it as part of any standard, nor does Linux, as we discussed i= n the bsh vs. beanshell debate in PSARC.

As we're ram= ping up integration of java components, we're creating new gaps from = old practice.  One of these is the nomenclature surrounding the = naming of the jar files themselves (jars as "libraries"), which I won= 't go into here.  The other is the point which Jim raised -- the= re's currently no expected way to communicate stability level other t= han man pages.  Adding man pages to java jar projects (projects = which deliver only .jars) _feels_ wrong, since the consumers of these= jars aren't going to expect to find a man page -- they're on a very = different usage model than most other consumers of C libraries and co= mmand line interfaces.  Consumers in this case typically use Jav= aDocs as their source of API information, and that _feels_ like a bet= ter place to put that information.

If the man pages= are explicitly NOT to be delivered with "jar" projects, then where i= s the stability level expressed?    If in JavaDocs, th= en what does that look like, assuming we need precision for that nome= nclature?

=
Does the very same taxonomy even apply to j= ars?   The current taxonomy is, as a core component of its = definition, dependent on release versions of Solaris.  Obviously= , java jar's are more tightly coupled to Java versions than on OS rel= ease versions, no?


Thanks,
<= blockquote type=3D"cite">Margot


_______________________________________________
opensola= ris-arc mailing list
opensolaris-arc@opensolaris.org



Lloyd Chambers
GlassFis= h Team



--Boundary_(ID_gplwJ7+nfROVELzDlfLGbA)-- From Lloyd.Chambers@Sun.COM Tue May 12 17:07:59 2009 Received: from sunmail3mpk.sfbay.sun.com (sunmail3mpk.SFBay.Sun.COM [129.146.11.52]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4D07xOc010517 for ; Tue, 12 May 2009 17:07:59 -0700 (PDT) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by sunmail3mpk.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4D07wXL008752 for <@sunmail2sca.sfbay.sun.com:LSARC-ext@sun.com>; Tue, 12 May 2009 17:07:58 -0700 (PDT) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJK00A01318DC00@nwk-avmta-2.sfbay.sun.com> for LSARC-ext@sun.com (ORCPT LSARC-ext@sun.com); Tue, 12 May 2009 17:07:56 -0700 (PDT) Received: from sca-es-mail-2.sun.com ([192.18.43.133]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJK0002Z3188VC0@nwk-avmta-2.sfbay.sun.com> for LSARC-ext@sun.com (ORCPT LSARC-ext@sun.com); Tue, 12 May 2009 17:07:56 -0700 (PDT) Received: from fe-sfbay-10.sun.com ([192.18.43.129]) by sca-es-mail-2.sun.com (8.13.7+Sun/8.12.9) with ESMTP id n4D07wCs024245 for ; Tue, 12 May 2009 17:07:58 -0700 (PDT) Received: from conversion-daemon.fe-sfbay-10.sun.com by fe-sfbay-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJK004002TNO100@fe-sfbay-10.sun.com> for LSARC-ext@sun.com (ORCPT LSARC-ext@sun.com); Tue, 12 May 2009 17:07:58 -0700 (PDT) Received: from [192.168.1.5] ([unknown] [208.74.178.82]) by fe-sfbay-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJK008O33194870@fe-sfbay-10.sun.com>; Tue, 12 May 2009 17:07:58 -0700 (PDT) Date: Tue, 12 May 2009 17:07:57 -0700 From: Lloyd Chambers Subject: Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] In-reply-to: <4A09F80D.6080305@gmail.com> Sender: Lloyd.Chambers@Sun.COM To: Mark Martin Cc: Margot Miller , LSARC-ext@Sun.COM Message-id: <10008ADD-B6FC-4D0F-85A1-5DD4393E4532@sun.com> MIME-version: 1.0 X-Mailer: Apple Mail (2.930.4) Content-type: multipart/alternative; boundary="Boundary_(ID_DuR14ocstGLrY8mPYLHL8g)" X-PMX-Version: 5.4.1.325704 References: <4A09EB8D.6090800@sun.com> <4A09F80D.6080305@gmail.com> Status: RO Content-Length: 12420 --Boundary_(ID_DuR14ocstGLrY8mPYLHL8g) Content-type: text/plain; CHARSET=US-ASCII; delsp=yes; format=flowed Content-transfer-encoding: 7BIT Worth noting: 'man' pages are wholly inadequate to document some jar files; one would be in the awkward position of enumerating all the classes, and possibly all the methods/constants in those classes. There are jar files that are nothing but interfaces, some that are interfaces and code, some that are mostly code. I don't think a man page will ever be in a position to do anything but a very coarse (and therefore risk) job at documenting what's the stability. Lloyd On May 12, 2009, at 3:28 PM, Mark Martin wrote: > Margot Miller wrote: >> Hey All, >> >> I am derailing this case as it misses the non-controversial >> requirement >> for a fast track and would like an email vote on this case by >> Friday May 15th. >> >> My impression from today's meeting was that LSARC will have >> a future case that will address the issue of how to publicize >> interface >> classifications for jar files and that it was okay for this project >> team and >> other teams to optionally ship a man page for a jar file. This >> would be setting >> precedent. >> >> Below is the proposed verbiage for the opinion. >> >> The project team is delivering a man page for the java jar file. >> It was >> noted that this is not standard practice as most Java developers look >> for java documentation via javadocs, not via man. However, others >> stated that >> having a minimal man page for a java jar file would allow the >> interface >> classification to be visible to the end user and a few other ARC >> cases have >> shipped these man pages. This case proposes letting the project >> team and >> others optionally ship a man page for a jar file. >> >> I vote against. > > I'm presuming you're voting against this case as spec'd, with the > offered opinion, correct? The project team hasn't been given a > chance to make any advised or required modifications, so it seems a > bit imprudent to deny a case in that manner. > The intent here is that the man page inclusion precedent will be set > here and now, right? If the vote sustains for approval with a man > page, then there's no need to bring another case forth, right? > Seems like Jim's gap would be addressed in that case. Or should the > "optionally" token in the opinion text be taken as a failure to > cover the gap? > > On the topic, though, I think Jim brings a very good point -- how > does the project team communicate the expected stability? Lloyd > brings an interesting solution with the use of Java Attributes as > documentation decoration, although I have a few issues with it on > technical grounds. For those not on the call, I see the problem as > this: > > At some point, Sun must have established the precedent and the > _expectation_ that stability levels of most types of interfaces were > to be expressed to consumers of those interfaces in the man pages. > I'm sorry I can't quote chapter and verse. This is, as far as I'm > aware, a communication norm that I don't see in other systems, Sun > originated or otherwise. Java certainly does not have it as part of > any standard, nor does Linux, as we discussed in the bsh vs. > beanshell debate in PSARC. > > As we're ramping up integration of java components, we're creating > new gaps from old practice. One of these is the nomenclature > surrounding the naming of the jar files themselves (jars as > "libraries"), which I won't go into here. The other is the point > which Jim raised -- there's currently no expected way to communicate > stability level other than man pages. Adding man pages to java jar > projects (projects which deliver only .jars) _feels_ wrong, since > the consumers of these jars aren't going to expect to find a man > page -- they're on a very different usage model than most other > consumers of C libraries and command line interfaces. Consumers in > this case typically use JavaDocs as their source of API information, > and that _feels_ like a better place to put that information. > > If the man pages are explicitly NOT to be delivered with "jar" > projects, then where is the stability level expressed? If in > JavaDocs, then what does that look like, assuming we need precision > for that nomenclature? > > Does the very same taxonomy even apply to jars? The current > taxonomy is, as a core component of its definition, dependent on > release versions of Solaris. Obviously, java jar's are more tightly > coupled to Java versions than on OS release versions, no? > >> >> Thanks, >> Margot >> >> >> _______________________________________________ >> opensolaris-arc mailing list >> opensolaris-arc@opensolaris.org > Lloyd Chambers lloyd.chambers@sun.com GlassFish Team --Boundary_(ID_DuR14ocstGLrY8mPYLHL8g) Content-type: text/html; CHARSET=US-ASCII Content-transfer-encoding: QUOTED-PRINTABLE Worth noting:

'man' pages are wholly inadequate to document some jar files; o= ne would be in the awkward position of enumerating all the classes, a= nd possibly all the methods/constants in those classes.
There are jar files that are nothing but interfaces, some= that are interfaces and code, some that are mostly code.  I don= 't think a man page will ever be in a position to do anything but a v= ery coarse (and therefore risk) job at documenting what's the stabili= ty.

Lloyd

On Ma= y 12, 2009, at 3:28 PM, Mark Martin wrote:

Margot Miller wrote= :
Hey All,

I am derailin= g this case as it misses the non-controversial requirement
for a fast track and would like an em= ail vote on this case by
Fr= iday May 15th.

My impression from today's meeting was= that LSARC will have
a fut= ure case that will address the issue of how to publicize interface
classifications for jar files= and that it was okay for this project team and
other teams to optionally ship a man page for a = jar file.  This would be setting
precedent.

<= /blockquote>
Below is the proposed verbiage = for the opinion.

The project team is delivering a man= page for the java jar file.  It was
noted that this is not standard practice as most Java = developers look
for java do= cumentation via javadocs, not via man.  However, others stated t= hat
having a minimal man pa= ge for a java jar file would allow the interface
classification to be visible to the end user an= d a few other ARC cases have
shipped these man pages.   This case proposes letting the= project team and
others op= tionally ship a man page for a jar file.

I vote again= st.

I'm presuming you're voting against this case= as spec'd, with the offered opinion, correct?  The project team= hasn't been given a chance to make any advised or required modificat= ions, so it seems a bit imprudent to deny a case in that manner.
= The intent here is that the man page inclusion precedent will be set = here and now, right?  If the vote sustains for approval with a m= an page, then there's no need to bring another case forth, right? &nb= sp;Seems like Jim's gap would be addressed in that case.  Or sho= uld the "optionally" token in the opinion text be taken as a failure = to cover the gap?

On the topic, though, I think Jim brings a v= ery good point -- how does the project team communicate the expected = stability?  Lloyd brings an interesting solution with the use of= Java Attributes as documentation decoration, although I have a few i= ssues with it on technical grounds.  For those not on the call, = I see the problem as this:

At some point, Sun must have establ= ished the precedent and the _expectation_ that stability levels of mo= st types of interfaces were to be expressed to consumers of those int= erfaces in the man pages.  I'm sorry I can't quote chapter and v= erse.  This is, as far as I'm aware, a communication norm that I= don't see in other systems, Sun originated or otherwise.  Java = certainly does not have it as part of any standard, nor does Linux, a= s we discussed in the bsh vs. beanshell debate in PSARC.

As we= 're ramping up integration of java components, we're creating new gap= s from old practice.  One of these is the nomenclature surroundi= ng the naming of the jar files themselves (jars as "libraries"), whic= h I won't go into here.  The other is the point which Jim raised= -- there's currently no expected way to communicate stability level = other than man pages.  Adding man pages to java jar projects (pr= ojects which deliver only .jars) _feels_ wrong, since the consumers o= f these jars aren't going to expect to find a man page -- they're on = a very different usage model than most other consumers of C libraries= and command line interfaces.  Consumers in this case typically = use JavaDocs as their source of API information, and that _feels_ lik= e a better place to put that information.

If the man pages are= explicitly NOT to be delivered with "jar" projects, then where is th= e stability level expressed?    If in JavaDocs, then w= hat does that look like, assuming we need precision for that nomencla= ture?

Does the very same taxonomy even apply to jars?  &n= bsp;The current taxonomy is, as a core component of its definition, d= ependent on release versions of Solaris.  Obviously, java jar's = are more tightly coupled to Java versions than on OS release versions= , no?


Thanks,
Margot=


_________= ______________________________________
opensolaris-arc mailing list
open= solaris-arc@opensolaris.org


Lloyd Chambers
GlassFish Team



--Boundary_(ID_DuR14ocstGLrY8mPYLHL8g)-- From Michael.Kearney@sun.com Wed May 13 06:59:56 2009 Received: from sunmail2sca.sfbay.sun.com (sunmail2sca.SFBay.Sun.COM [129.145.155.234]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4DDxuTI014858 for ; Wed, 13 May 2009 06:59:56 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail2sca.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4DDxtrv017533 for <@sunmail2sca.sfbay.sun.com:LSARC-ext@sun.com>; Wed, 13 May 2009 06:59:56 -0700 (PDT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJL0030F5JWOV00@brm-avmta-1.central.sun.com> for LSARC-ext@sun.com (ORCPT LSARC-ext@Sun.COM); Wed, 13 May 2009 07:59:56 -0600 (MDT) Received: from brmea-mail-2.sun.com ([192.18.98.43]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJL00JWA5JVJY70@brm-avmta-1.central.sun.com> for LSARC-ext@sun.com (ORCPT LSARC-ext@Sun.COM); Wed, 13 May 2009 07:59:55 -0600 (MDT) Received: from fe-amer-10.sun.com ([192.18.109.80]) by brmea-mail-2.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n4DDxthW023939 for ; Wed, 13 May 2009 13:59:55 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJL00B004Y3VZ00@mail-amer.sun.com> for LSARC-ext@Sun.COM (ORCPT LSARC-ext@Sun.COM); Wed, 13 May 2009 07:59:55 -0600 (MDT) Received: from [129.147.49.125] ([unknown] [129.147.49.125]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJL000DE5JV0520@mail-amer.sun.com> for LSARC-ext@Sun.COM (ORCPT LSARC-ext@Sun.COM); Wed, 13 May 2009 07:59:55 -0600 (MDT) Date: Wed, 13 May 2009 07:59:54 -0600 From: Michael Kearney Subject: Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] In-reply-to: <10008ADD-B6FC-4D0F-85A1-5DD4393E4532@sun.com> Sender: Michael.Kearney@sun.com Cc: LSARC-ext@sun.com Message-id: <4A0AD25A.7070508@Sun.com> MIME-version: 1.0 Content-type: multipart/mixed; boundary="Boundary_(ID_opC+soFuJN6HVfsVPmOFQA)" X-PMX-Version: 5.4.1.325704 References: <4A09EB8D.6090800@sun.com> <4A09F80D.6080305@gmail.com> <10008ADD-B6FC-4D0F-85A1-5DD4393E4532@sun.com> User-Agent: Thunderbird 2.0.0.17 (Windows/20080914) Status: RO Content-Length: 9734 This is a multi-part message in MIME format. --Boundary_(ID_opC+soFuJN6HVfsVPmOFQA) Content-type: text/html; CHARSET=US-ASCII Content-transfer-encoding: 7BIT 1. Lloyd, I like the idea of your annotation but have a couple of concerns. 
    - Would teams be expected to update third party, open source jar files with the annotation?
    - Would the ARC provide the common @Taxonomy annotation Java code?

2. What if the man page simple documented the stability at the granularity of the jar file and
nothing else.  Perhaps the man page could generically reference the Javadoc?

    -Michael

Lloyd Chambers wrote:
Worth noting:

'man' pages are wholly inadequate to document some jar files; one would be in the awkward position of enumerating all the classes, and possibly all the methods/constants in those classes.

There are jar files that are nothing but interfaces, some that are interfaces and code, some that are mostly code.  I don't think a man page will ever be in a position to do anything but a very coarse (and therefore risk) job at documenting what's the stability.

Lloyd

On May 12, 2009, at 3:28 PM, Mark Martin wrote:

Margot Miller wrote:
Hey All,

I am derailing this case as it misses the non-controversial requirement
for a fast track and would like an email vote on this case by
Friday May 15th.

My impression from today's meeting was that LSARC will have
a future case that will address the issue of how to publicize interface
classifications for jar files and that it was okay for this project team and
other teams to optionally ship a man page for a jar file.  This would be setting
precedent.

Below is the proposed verbiage for the opinion.

The project team is delivering a man page for the java jar file.  It was
noted that this is not standard practice as most Java developers look
for java documentation via javadocs, not via man.  However, others stated that
having a minimal man page for a java jar file would allow the interface
classification to be visible to the end user and a few other ARC cases have
shipped these man pages.   This case proposes letting the project team and
others optionally ship a man page for a jar file.

I vote against.

I'm presuming you're voting against this case as spec'd, with the offered opinion, correct?  The project team hasn't been given a chance to make any advised or required modifications, so it seems a bit imprudent to deny a case in that manner.
The intent here is that the man page inclusion precedent will be set here and now, right?  If the vote sustains for approval with a man page, then there's no need to bring another case forth, right?  Seems like Jim's gap would be addressed in that case.  Or should the "optionally" token in the opinion text be taken as a failure to cover the gap?

On the topic, though, I think Jim brings a very good point -- how does the project team communicate the expected stability?  Lloyd brings an interesting solution with the use of Java Attributes as documentation decoration, although I have a few issues with it on technical grounds.  For those not on the call, I see the problem as this:

At some point, Sun must have established the precedent and the _expectation_ that stability levels of most types of interfaces were to be expressed to consumers of those interfaces in the man pages.  I'm sorry I can't quote chapter and verse.  This is, as far as I'm aware, a communication norm that I don't see in other systems, Sun originated or otherwise.  Java certainly does not have it as part of any standard, nor does Linux, as we discussed in the bsh vs. beanshell debate in PSARC.

As we're ramping up integration of java components, we're creating new gaps from old practice.  One of these is the nomenclature surrounding the naming of the jar files themselves (jars as "libraries"), which I won't go into here.  The other is the point which Jim raised -- there's currently no expected way to communicate stability level other than man pages.  Adding man pages to java jar projects (projects which deliver only .jars) _feels_ wrong, since the consumers of these jars aren't going to expect to find a man page -- they're on a very different usage model than most other consumers of C libraries and command line interfaces.  Consumers in this case typically use JavaDocs as their source of API information, and that _feels_ like a better place to put that information.

If the man pages are explicitly NOT to be delivered with "jar" projects, then where is the stability level expressed?    If in JavaDocs, then what does that look like, assuming we need precision for that nomenclature?

Does the very same taxonomy even apply to jars?   The current taxonomy is, as a core component of its definition, dependent on release versions of Solaris.  Obviously, java jar's are more tightly coupled to Java versions than on OS release versions, no?


Thanks,
Margot


_______________________________________________
opensolaris-arc mailing list
opensolaris-arc@opensolaris.org


Lloyd Chambers
GlassFish Team




--
Michael Kearney
Staff Software Engineer

Sun Microsystems, Inc.
MS UBRM05-390, 500 Eldorado Blvd
Broomfield, CO 80021 US
Phone 303-272-2402
Fax 303-272-6554
Email Michael.Kearney@Sun.COM
--Boundary_(ID_opC+soFuJN6HVfsVPmOFQA) Content-type: text/x-vcard; CHARSET=US-ASCII; name=Michael_Kearney.vcf Content-transfer-encoding: 7BIT Content-disposition: attachment; filename=Michael_Kearney.vcf begin:vcard fn:Michael Kearney n:Kearney;Michael org:Sun Microsystems, Inc.;Archive Core Engineering adr:500 Eldorado Blvd.;;Mailstop UBRM05-390;Broomfield;CO;80021;US email;internet:Michael.Kearney@Sun.com title:Staff Software Engineer tel;work:303-272-2402 tel;fax:303-272-6554 x-mozilla-html:TRUE url:http://www.sun.com/ version:2.1 end:vcard --Boundary_(ID_opC+soFuJN6HVfsVPmOFQA)-- From margot.miller@sun.com Wed May 13 08:17:16 2009 Received: from sunmail3mpk.sfbay.sun.com (sunmail3mpk.SFBay.Sun.COM [129.146.11.52]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4DFHG74013319 for ; Wed, 13 May 2009 08:17:16 -0700 (PDT) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by sunmail3mpk.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4DFHDK1005051; Wed, 13 May 2009 08:17:14 -0700 (PDT) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJL00K0D94OD200@nwk-avmta-2.sfbay.sun.com>; Wed, 13 May 2009 08:17:12 -0700 (PDT) Received: from jurassic-x4600.sfbay.sun.com ([129.146.17.59]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJL00CS594M7U90@nwk-avmta-2.sfbay.sun.com>; Wed, 13 May 2009 08:17:10 -0700 (PDT) Received: from [10.7.250.251] (punchin-client-10-7-250-251.SFBay.Sun.COM [10.7.250.251]) by jurassic-x4600.sfbay.sun.com (8.14.3+Sun/8.14.3) with ESMTP id n4DFH5WF979517; Wed, 13 May 2009 08:17:06 -0700 (PDT) Date: Wed, 13 May 2009 08:17:05 -0700 From: Margot Miller Subject: Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] In-reply-to: <4A09FEC8.5060105@sun.com> To: Mark Martin , LSARC-ext@sun.com Cc: Vivek Titarmare Message-id: <4A0AE471.9040905@sun.com> MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <4A09EB8D.6090800@sun.com> <4A09F80D.6080305@gmail.com> <4A09FEC8.5060105@sun.com> User-Agent: Thunderbird 2.0b1 (X11/20070115) Status: RO Content-Length: 4629 Instead of doing this via email, let's put this on the agenda for next week. At that time we can decide whether the below: Do not ship man pages with jar files should be a TCR, TCA, or Advice. That is the only outstanding issue on this case. Then, if everyone is ready, we can then vote on the entire case. Thanks, Margot Margot Miller wrote: > The case hasn't been denied; it's been derailed so an opinion can be > written and it will be clear if precedence has been set or not with > this case. > > From the LSARC meeting today, it seemed like the majority of > the committee thought it was fine for the project team and other > teams to ship a man page. I don't think that is the right way > to go, in that some jar files will have man pages, some won't > and Java developers probably won't look for a man page > anyway. > > I think Jim identified correctly a real problem - how do > we communicate the interface classification of a jar file to the > end user. I think we need a comprehensive and > consistent solution. And the javadocs proposal has a lot of > merit to it. > We are voting on whether the project team should be allowed > to ship the man page. (I thought the majority wanted that > but need to take an explicit vote) > > So if after the vote, I am in the minority, than the case is approved > and I write a section stating the minority opinion. If after the vote, > I am in the majority, then the case is approved, the team doesn't > ship a man page, and the minority can write their section of > the opinion if they chose. > > Margot > > > Mark Martin wrote: >> >> I'm presuming you're voting against this case as spec'd, with the >> offered opinion, correct? The project team hasn't been given a >> chance to make any advised or required modifications, so it seems a >> bit imprudent to deny a case in that manner. >> The intent here is that the man page inclusion precedent will be set >> here and now, right? If the vote sustains for approval with a man >> page, then there's no need to bring another case forth, right? Seems >> like Jim's gap would be addressed in that case. Or should the >> "optionally" token in the opinion text be taken as a failure to cover >> the gap? >> >> On the topic, though, I think Jim brings a very good point -- how >> does the project team communicate the expected stability? Lloyd >> brings an interesting solution with the use of Java Attributes as >> documentation decoration, although I have a few issues with it on >> technical grounds. For those not on the call, I see the problem as >> this: >> >> At some point, Sun must have established the precedent and the >> _expectation_ that stability levels of most types of interfaces were >> to be expressed to consumers of those interfaces in the man pages. >> I'm sorry I can't quote chapter and verse. This is, as far as I'm >> aware, a communication norm that I don't see in other systems, Sun >> originated or otherwise. Java certainly does not have it as part of >> any standard, nor does Linux, as we discussed in the bsh vs. >> beanshell debate in PSARC. >> >> As we're ramping up integration of java components, we're creating >> new gaps from old practice. One of these is the nomenclature >> surrounding the naming of the jar files themselves (jars as >> "libraries"), which I won't go into here. The other is the point >> which Jim raised -- there's currently no expected way to communicate >> stability level other than man pages. Adding man pages to java jar >> projects (projects which deliver only .jars) _feels_ wrong, since the >> consumers of these jars aren't going to expect to find a man page -- >> they're on a very different usage model than most other consumers of >> C libraries and command line interfaces. Consumers in this case >> typically use JavaDocs as their source of API information, and that >> _feels_ like a better place to put that information. >> >> If the man pages are explicitly NOT to be delivered with "jar" >> projects, then where is the stability level expressed? If in >> JavaDocs, then what does that look like, assuming we need precision >> for that nomenclature? >> >> Does the very same taxonomy even apply to jars? The current >> taxonomy is, as a core component of its definition, dependent on >> release versions of Solaris. Obviously, java jar's are more tightly >> coupled to Java versions than on OS release versions, no? >> >>> >>> Thanks, >>> Margot >>> >>> >>> _______________________________________________ >>> opensolaris-arc mailing list >>> opensolaris-arc@opensolaris.org >> > From James.Walker@sun.com Wed May 13 11:31:27 2009 Received: from sunmail3mpk.sfbay.sun.com (sunmail3mpk.SFBay.Sun.COM [129.146.11.52]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4DIVRxg022858; Wed, 13 May 2009 11:31:27 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail3mpk.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4DIVQqu025215; Wed, 13 May 2009 11:31:27 -0700 (PDT) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJL00515I4E7P00@nwk-avmta-1.sfbay.Sun.COM>; Wed, 13 May 2009 11:31:26 -0700 (PDT) Received: from brmea-mail-1.sun.com ([192.18.98.31]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJL004J2I4DWS90@nwk-avmta-1.sfbay.Sun.COM>; Wed, 13 May 2009 11:31:25 -0700 (PDT) Received: from fe-amer-09.sun.com ([192.18.109.79]) by brmea-mail-1.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n4DIVPCZ009606; Wed, 13 May 2009 18:31:25 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJL00D00C53C200@mail-amer.sun.com>; Wed, 13 May 2009 12:31:25 -0600 (MDT) Received: from c-67-166-22-238.hsd1.co.comcast.net ([unknown] [129.150.34.241]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJL00A5VI3NQ9B0@mail-amer.sun.com>; Wed, 13 May 2009 12:31:00 -0600 (MDT) Date: Wed, 13 May 2009 12:30:59 -0600 From: Jim Walker Subject: jar file man pages - was Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] In-reply-to: <4A0AD25A.7070508@Sun.com> Sender: James.Walker@sun.com To: Michael Kearney Cc: LSARC-ext@sun.com, Norm Jacobs , PSARC-ext@sun.com Reply-to: James.Walker@sun.com Message-id: <4A0B11E3.90203@sun.com> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <4A09EB8D.6090800@sun.com> <4A09F80D.6080305@gmail.com> <10008ADD-B6FC-4D0F-85A1-5DD4393E4532@sun.com> <4A0AD25A.7070508@Sun.com> User-Agent: Thunderbird 2.0.0.21 (Macintosh/20090302) Status: RO Content-Length: 2458 For LSARC, PSARC and the opinion writer(s) to consider.... Michael Kearney wrote: > 1. Lloyd, I like the idea of your annotation but have a couple of > concerns. > - Would teams be expected to update third party, open source jar > files with the annotation? > - Would the ARC provide the common @Taxonomy annotation Java code? I have concerns too. In general, we will not be able to change FOSS code upstream like this. We normally try to do as little modification as possible (ie. just enough to get it to run well on Solaris/OpenSolaris). This is another reason why short man pages are being tacked on. Is it possible to tack on a page to the javadoc? I don't want to see big javadoc patches in the SFW consolidation that document detailed taxonomy information that we have to carry forever because they will never be accepted into the upstream community. Why would a FOSS project creating jar files even care about our taxonomy rules? > 2. What if the man page simple documented the stability at the > granularity of the jar file and > nothing else. Perhaps the man page could generically reference the Javadoc? Not every jar file in /usr/share/lib/java has a man page, but that is the current practice, for the ones that do: $ man asm $ man mvel $ man janino $ man jettison $ man joda-time $ man jaxen-core $ man junit $ man ant (needs a more direct reference to javadoc) ... As I see it, having jar file man pages... 1. Provides users stability and availability (taxonomy) information about jar file packages on Solaris/OpenSolaris not available anywhere else. 2. Is pretty painless for project teams to produce and support. 3. Man pages do no harm, and I think users are already getting use to having them. Some information is better than no information. 4. Until there is a better way, man pages should be required for any new jar file submissions into Solaris/OpenSolaris. I thought this was already true. 5. Man pages are used by most Solaris/OpenSolaris packages. 6. I appreciate where Java developers are coming from, but "not standard practice for Java developers to look for man pages" alone, doesn't seem enough reason to stop man pages being delivered with jar file packages. We can't control how jar files are delivered or documented on windows or other environments, but we can on Solaris/OpenSolaris. BTW. ccing Norm (sfw c-team lead) since one of the requirements to integrate into sfw is a man page. Cheers, Jim From James.Walker@sun.com Wed May 13 11:31:27 2009 Received: from sunmail3mpk.sfbay.sun.com (sunmail3mpk.SFBay.Sun.COM [129.146.11.52]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4DIVRxg022858; Wed, 13 May 2009 11:31:27 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail3mpk.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4DIVQqu025215; Wed, 13 May 2009 11:31:27 -0700 (PDT) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJL00515I4E7P00@nwk-avmta-1.sfbay.Sun.COM>; Wed, 13 May 2009 11:31:26 -0700 (PDT) Received: from brmea-mail-1.sun.com ([192.18.98.31]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJL004J2I4DWS90@nwk-avmta-1.sfbay.Sun.COM>; Wed, 13 May 2009 11:31:25 -0700 (PDT) Received: from fe-amer-09.sun.com ([192.18.109.79]) by brmea-mail-1.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n4DIVPCZ009606; Wed, 13 May 2009 18:31:25 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJL00D00C53C200@mail-amer.sun.com>; Wed, 13 May 2009 12:31:25 -0600 (MDT) Received: from c-67-166-22-238.hsd1.co.comcast.net ([unknown] [129.150.34.241]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJL00A5VI3NQ9B0@mail-amer.sun.com>; Wed, 13 May 2009 12:31:00 -0600 (MDT) Date: Wed, 13 May 2009 12:30:59 -0600 From: Jim Walker Subject: jar file man pages - was Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] In-reply-to: <4A0AD25A.7070508@Sun.com> Sender: James.Walker@sun.com To: Michael Kearney Cc: LSARC-ext@sun.com, Norm Jacobs , PSARC-ext@sun.com Reply-to: James.Walker@sun.com Message-id: <4A0B11E3.90203@sun.com> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <4A09EB8D.6090800@sun.com> <4A09F80D.6080305@gmail.com> <10008ADD-B6FC-4D0F-85A1-5DD4393E4532@sun.com> <4A0AD25A.7070508@Sun.com> User-Agent: Thunderbird 2.0.0.21 (Macintosh/20090302) Status: RO Content-Length: 2458 For LSARC, PSARC and the opinion writer(s) to consider.... Michael Kearney wrote: > 1. Lloyd, I like the idea of your annotation but have a couple of > concerns. > - Would teams be expected to update third party, open source jar > files with the annotation? > - Would the ARC provide the common @Taxonomy annotation Java code? I have concerns too. In general, we will not be able to change FOSS code upstream like this. We normally try to do as little modification as possible (ie. just enough to get it to run well on Solaris/OpenSolaris). This is another reason why short man pages are being tacked on. Is it possible to tack on a page to the javadoc? I don't want to see big javadoc patches in the SFW consolidation that document detailed taxonomy information that we have to carry forever because they will never be accepted into the upstream community. Why would a FOSS project creating jar files even care about our taxonomy rules? > 2. What if the man page simple documented the stability at the > granularity of the jar file and > nothing else. Perhaps the man page could generically reference the Javadoc? Not every jar file in /usr/share/lib/java has a man page, but that is the current practice, for the ones that do: $ man asm $ man mvel $ man janino $ man jettison $ man joda-time $ man jaxen-core $ man junit $ man ant (needs a more direct reference to javadoc) ... As I see it, having jar file man pages... 1. Provides users stability and availability (taxonomy) information about jar file packages on Solaris/OpenSolaris not available anywhere else. 2. Is pretty painless for project teams to produce and support. 3. Man pages do no harm, and I think users are already getting use to having them. Some information is better than no information. 4. Until there is a better way, man pages should be required for any new jar file submissions into Solaris/OpenSolaris. I thought this was already true. 5. Man pages are used by most Solaris/OpenSolaris packages. 6. I appreciate where Java developers are coming from, but "not standard practice for Java developers to look for man pages" alone, doesn't seem enough reason to stop man pages being delivered with jar file packages. We can't control how jar files are delivered or documented on windows or other environments, but we can on Solaris/OpenSolaris. BTW. ccing Norm (sfw c-team lead) since one of the requirements to integrate into sfw is a man page. Cheers, Jim From John.Fischer@Sun.COM Thu May 14 15:25:44 2009 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4EMPhgE016312 for ; Thu, 14 May 2009 15:25:43 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail5.uk.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n4EMPdhn006220; Thu, 14 May 2009 23:25:42 +0100 (BST) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJN0012NNMTPB00@nwk-avmta-1.sfbay.Sun.COM>; Thu, 14 May 2009 15:25:41 -0700 (PDT) Received: from brmea-mail-2.sun.com ([192.18.98.43]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJN00HZ7NMSXUC0@nwk-avmta-1.sfbay.Sun.COM>; Thu, 14 May 2009 15:25:41 -0700 (PDT) Received: from fe-amer-09.sun.com ([192.18.109.79]) by brmea-mail-2.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n4EMPegc010985; Thu, 14 May 2009 22:25:40 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJN00900N482I00@mail-amer.sun.com>; Thu, 14 May 2009 16:25:40 -0600 (MDT) Received: from [192.168.10.8] ([unknown] [76.20.56.47]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJN0061ANM0UQ30@mail-amer.sun.com>; Thu, 14 May 2009 16:25:12 -0600 (MDT) Date: Thu, 14 May 2009 15:23:58 -0700 From: John Fischer Subject: LSARC 2009/262 - trove [was LSARC Agenda - 05/12/2009] In-reply-to: <4A0C933C.6070505@sun.com> Sender: John.Fischer@Sun.COM To: Asa Romberger Cc: LSARC-ext@Sun.COM, psarc-members@Sun.COM, Vivek.Titarmare@Sun.COM Reply-to: John.Fischer@Sun.COM Message-id: <4A0C99FE.9090704@sun.com> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <200905142140.n4ELePwO017727@ivrel.sfbay.sun.com> <4A0C933C.6070505@sun.com> User-Agent: Thunderbird 2.0.0.21 (X11/20090323) Status: RO Content-Length: 1200 Asa, Although you are correct that the trove case (LSARC 2009/262) started the discussion. It was also derailed for an opinion/discussion. Thus the agenda item. Mark, Please be sure to archive the discussion from the Agenda announcement into the mail log for the case. All, Please discuss this via this email going forward. Thanks, John Asa Romberger wrote: > Glen, > > On 05/14/09 14:40, Glenn Skinner wrote: >> Date: Thu, 14 May 2009 12:17:21 -0700 >> From: Asa Romberger >> Subject: LSARC Agenda - 05/12/2009 >> >> I have specifically copied PSARC on this announcement because of >> the discussion on man pages for jar files. >> >> Regarding that discussion: >> >> It ought to be captured in a case, if only so that we can all avoid >> spamming the *-announce aliases with discussion about it. >> >> (I have additional comments, but am awaiting creation of the case in >> an attempt to minimize additional spammage.) >> >> -- Glenn >> > > The case that started the discussion is the one that is further down in > the agenda: > LSARC/2009/262: trove-2.0.4 > It just happens to be the one that started the discussion. > > Asa From sacadmin Thu May 14 15:25:45 2009 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4EMPiMq016316 for ; Thu, 14 May 2009 15:25:45 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail5.uk.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n4EMPdhn006220; Thu, 14 May 2009 23:25:42 +0100 (BST) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJN0012NNMTPB00@nwk-avmta-1.sfbay.Sun.COM>; Thu, 14 May 2009 15:25:41 -0700 (PDT) Received: from brmea-mail-2.sun.com ([192.18.98.43]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJN00HZ7NMSXUC0@nwk-avmta-1.sfbay.Sun.COM>; Thu, 14 May 2009 15:25:41 -0700 (PDT) Received: from fe-amer-09.sun.com ([192.18.109.79]) by brmea-mail-2.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n4EMPegc010985; Thu, 14 May 2009 22:25:40 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJN00900N482I00@mail-amer.sun.com>; Thu, 14 May 2009 16:25:40 -0600 (MDT) Received: from [192.168.10.8] ([unknown] [76.20.56.47]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJN0061ANM0UQ30@mail-amer.sun.com>; Thu, 14 May 2009 16:25:12 -0600 (MDT) Date: Thu, 14 May 2009 15:23:58 -0700 From: John Fischer Subject: LSARC 2009/262 - trove [was LSARC Agenda - 05/12/2009] In-reply-to: <4A0C933C.6070505@sun.com> Sender: John.Fischer@Sun.COM To: Asa Romberger Cc: LSARC-ext@Sun.COM, psarc-members@Sun.COM, Vivek.Titarmare@Sun.COM Reply-to: John.Fischer@Sun.COM Message-id: <4A0C99FE.9090704@sun.com> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <200905142140.n4ELePwO017727@ivrel.sfbay.sun.com> <4A0C933C.6070505@sun.com> User-Agent: Thunderbird 2.0.0.21 (X11/20090323) Status: RO Content-Length: 1200 Asa, Although you are correct that the trove case (LSARC 2009/262) started the discussion. It was also derailed for an opinion/discussion. Thus the agenda item. Mark, Please be sure to archive the discussion from the Agenda announcement into the mail log for the case. All, Please discuss this via this email going forward. Thanks, John Asa Romberger wrote: > Glen, > > On 05/14/09 14:40, Glenn Skinner wrote: >> Date: Thu, 14 May 2009 12:17:21 -0700 >> From: Asa Romberger >> Subject: LSARC Agenda - 05/12/2009 >> >> I have specifically copied PSARC on this announcement because of >> the discussion on man pages for jar files. >> >> Regarding that discussion: >> >> It ought to be captured in a case, if only so that we can all avoid >> spamming the *-announce aliases with discussion about it. >> >> (I have additional comments, but am awaiting creation of the case in >> an attempt to minimize additional spammage.) >> >> -- Glenn >> > > The case that started the discussion is the one that is further down in > the agenda: > LSARC/2009/262: trove-2.0.4 > It just happens to be the one that started the discussion. > > Asa From norm.jacobs@sun.com Thu May 14 15:48:25 2009 Received: from sunmail4.singapore.sun.com (sunmail4.Singapore.Sun.COM [129.158.71.19]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4EMmOI5016974; Thu, 14 May 2009 15:48:25 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail4.singapore.sun.com (8.13.4+Sun/8.13.3/ENSMAIL,v2.2) with ESMTP id n4EMmHN4019479; Fri, 15 May 2009 06:48:22 +0800 (SGT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJN00J11OOMHZ00@brm-avmta-1.central.sun.com>; Thu, 14 May 2009 16:48:22 -0600 (MDT) Received: from jurassic-x4600.sfbay.sun.com ([129.146.17.63]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJN00G8GOOGUGB0@brm-avmta-1.central.sun.com>; Thu, 14 May 2009 16:48:16 -0600 (MDT) Received: from [10.7.251.237] (punchin-jacobs.SFBay.Sun.COM [10.7.251.237]) by jurassic-x4600.sfbay.sun.com (8.14.3+Sun/8.14.3) with ESMTP id n4EMmFmu356663; Thu, 14 May 2009 15:48:15 -0700 (PDT) Date: Thu, 14 May 2009 17:48:14 -0500 From: Norm Jacobs Subject: Re: jar file man pages - was Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] In-reply-to: <4A0B11E3.90203@sun.com> To: James.Walker@sun.com Cc: Michael Kearney , LSARC-ext@sun.com, PSARC-ext@sun.com Message-id: <4A0C9FAE.8070504@Sun.COM> MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <4A09EB8D.6090800@sun.com> <4A09F80D.6080305@gmail.com> <10008ADD-B6FC-4D0F-85A1-5DD4393E4532@sun.com> <4A0AD25A.7070508@Sun.com> <4A0B11E3.90203@sun.com> User-Agent: Thunderbird 2.0.0.21 (X11/20090323) Status: RO Content-Length: 4210 Jim Walker wrote: > For LSARC, PSARC and the opinion writer(s) to consider.... > > Michael Kearney wrote: >> 1. Lloyd, I like the idea of your annotation but have a couple of >> concerns. >> - Would teams be expected to update third party, open source jar >> files with the annotation? >> - Would the ARC provide the common @Taxonomy annotation Java code? NO, NO, NO. We don't want to be in the business of patching this bit of Sun lore into source and or documentation delivered by existing open source projects. Largely, the projects are not going to be interested in this type of change. This should be handled by a separate mechanism that falls outside of that arena, perhap by the taxonomy(1) command. > > I have concerns too. > > In general, we will not be able to change FOSS code upstream like > this. We normally try to do as little modification as possible (ie. > just enough to get it to run well on Solaris/OpenSolaris). This > is another reason why short man pages are being tacked on. Is it > possible to tack on a page to the javadoc? Simply put, If we can leave the upstream bits alone, we should. If we have to make changes to make it build, install, or function properly then coordinate those changes with the upstream community. For SFW, it's ok to deliver them as a patch initially, but the expectation is that the next update will obsolete the patch unless there is a really compelling reason to deviate from the upstream. This doesn't mean that you can't include support for SMF, RBAC, ... It just means that we want something that doesn't require new patches at each update and ultimately, no patching at all would be preferred. So again, leave the open source bits (docs in this case) alone unless there is a really compelling reason to deviate. > > I don't want to see big javadoc patches in the SFW consolidation that > document detailed taxonomy information that we have to carry forever > because they will never be accepted into the upstream community. > Why would a FOSS project creating jar files even care about our > taxonomy rules? They won't. >> 2. What if the man page simple documented the stability at the >> granularity of the jar file and >> nothing else. Perhaps the man page could generically reference the >> Javadoc? > > Not every jar file in /usr/share/lib/java has a man page, but > that is the current practice, for the ones that do: > > $ man asm > $ man mvel > $ man janino > $ man jettison > $ man joda-time > $ man jaxen-core > $ man junit > $ man ant (needs a more direct reference to javadoc) > ... > > As I see it, having jar file man pages... > > 1. Provides users stability and availability (taxonomy) information > about jar file packages on Solaris/OpenSolaris not available anywhere > else. > 2. Is pretty painless for project teams to produce and support. > 3. Man pages do no harm, and I think users are already getting > use to having them. Some information is better than no information. > 4. Until there is a better way, man pages should be required for > any new jar file submissions into Solaris/OpenSolaris. I thought > this was already true. > 5. Man pages are used by most Solaris/OpenSolaris packages. > 6. I appreciate where Java developers are coming from, but "not standard > practice for Java developers to look for man pages" alone, doesn't seem > enough reason to stop man pages being delivered with jar file packages. > > We can't control how jar files are delivered or documented on > windows or other environments, but we can on Solaris/OpenSolaris. > > BTW. ccing Norm (sfw c-team lead) since one of the requirements to > integrate into sfw is a man page. The requirement has really been to provide documentation. We have not forced folks to deliver man pages when the software they were delivering had it's own documentation. If it comes with texinfo, javadoc, html, ... then we have let them deliver that documentation and not required a man page for everything. If software was lacking documentation, we have asked for documentation that describes it, usually a man page. The intent is to provide the documentation that is expected by the users of the software. -Norm From norm.jacobs@sun.com Thu May 14 15:48:25 2009 Received: from sunmail4.singapore.sun.com (sunmail4.Singapore.Sun.COM [129.158.71.19]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4EMmOI5016974; Thu, 14 May 2009 15:48:25 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail4.singapore.sun.com (8.13.4+Sun/8.13.3/ENSMAIL,v2.2) with ESMTP id n4EMmHN4019479; Fri, 15 May 2009 06:48:22 +0800 (SGT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJN00J11OOMHZ00@brm-avmta-1.central.sun.com>; Thu, 14 May 2009 16:48:22 -0600 (MDT) Received: from jurassic-x4600.sfbay.sun.com ([129.146.17.63]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJN00G8GOOGUGB0@brm-avmta-1.central.sun.com>; Thu, 14 May 2009 16:48:16 -0600 (MDT) Received: from [10.7.251.237] (punchin-jacobs.SFBay.Sun.COM [10.7.251.237]) by jurassic-x4600.sfbay.sun.com (8.14.3+Sun/8.14.3) with ESMTP id n4EMmFmu356663; Thu, 14 May 2009 15:48:15 -0700 (PDT) Date: Thu, 14 May 2009 17:48:14 -0500 From: Norm Jacobs Subject: Re: jar file man pages - was Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] In-reply-to: <4A0B11E3.90203@sun.com> To: James.Walker@sun.com Cc: Michael Kearney , LSARC-ext@sun.com, PSARC-ext@sun.com Message-id: <4A0C9FAE.8070504@Sun.COM> MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <4A09EB8D.6090800@sun.com> <4A09F80D.6080305@gmail.com> <10008ADD-B6FC-4D0F-85A1-5DD4393E4532@sun.com> <4A0AD25A.7070508@Sun.com> <4A0B11E3.90203@sun.com> User-Agent: Thunderbird 2.0.0.21 (X11/20090323) Status: RO Content-Length: 4210 Jim Walker wrote: > For LSARC, PSARC and the opinion writer(s) to consider.... > > Michael Kearney wrote: >> 1. Lloyd, I like the idea of your annotation but have a couple of >> concerns. >> - Would teams be expected to update third party, open source jar >> files with the annotation? >> - Would the ARC provide the common @Taxonomy annotation Java code? NO, NO, NO. We don't want to be in the business of patching this bit of Sun lore into source and or documentation delivered by existing open source projects. Largely, the projects are not going to be interested in this type of change. This should be handled by a separate mechanism that falls outside of that arena, perhap by the taxonomy(1) command. > > I have concerns too. > > In general, we will not be able to change FOSS code upstream like > this. We normally try to do as little modification as possible (ie. > just enough to get it to run well on Solaris/OpenSolaris). This > is another reason why short man pages are being tacked on. Is it > possible to tack on a page to the javadoc? Simply put, If we can leave the upstream bits alone, we should. If we have to make changes to make it build, install, or function properly then coordinate those changes with the upstream community. For SFW, it's ok to deliver them as a patch initially, but the expectation is that the next update will obsolete the patch unless there is a really compelling reason to deviate from the upstream. This doesn't mean that you can't include support for SMF, RBAC, ... It just means that we want something that doesn't require new patches at each update and ultimately, no patching at all would be preferred. So again, leave the open source bits (docs in this case) alone unless there is a really compelling reason to deviate. > > I don't want to see big javadoc patches in the SFW consolidation that > document detailed taxonomy information that we have to carry forever > because they will never be accepted into the upstream community. > Why would a FOSS project creating jar files even care about our > taxonomy rules? They won't. >> 2. What if the man page simple documented the stability at the >> granularity of the jar file and >> nothing else. Perhaps the man page could generically reference the >> Javadoc? > > Not every jar file in /usr/share/lib/java has a man page, but > that is the current practice, for the ones that do: > > $ man asm > $ man mvel > $ man janino > $ man jettison > $ man joda-time > $ man jaxen-core > $ man junit > $ man ant (needs a more direct reference to javadoc) > ... > > As I see it, having jar file man pages... > > 1. Provides users stability and availability (taxonomy) information > about jar file packages on Solaris/OpenSolaris not available anywhere > else. > 2. Is pretty painless for project teams to produce and support. > 3. Man pages do no harm, and I think users are already getting > use to having them. Some information is better than no information. > 4. Until there is a better way, man pages should be required for > any new jar file submissions into Solaris/OpenSolaris. I thought > this was already true. > 5. Man pages are used by most Solaris/OpenSolaris packages. > 6. I appreciate where Java developers are coming from, but "not standard > practice for Java developers to look for man pages" alone, doesn't seem > enough reason to stop man pages being delivered with jar file packages. > > We can't control how jar files are delivered or documented on > windows or other environments, but we can on Solaris/OpenSolaris. > > BTW. ccing Norm (sfw c-team lead) since one of the requirements to > integrate into sfw is a man page. The requirement has really been to provide documentation. We have not forced folks to deliver man pages when the software they were delivering had it's own documentation. If it comes with texinfo, javadoc, html, ... then we have let them deliver that documentation and not required a man page for everything. If software was lacking documentation, we have asked for documentation that describes it, usually a man page. The intent is to provide the documentation that is expected by the users of the software. -Norm From carlsonj@phorcys.east.sun.com Fri May 15 06:07:10 2009 Received: from sunmail3mpk.sfbay.sun.com (sunmail3mpk.SFBay.Sun.COM [129.146.11.52]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4FD7AYW019653; Fri, 15 May 2009 06:07:10 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail3mpk.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4FD76wr012288; Fri, 15 May 2009 06:07:09 -0700 (PDT) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJO00F1TSFV9Y00@nwk-avmta-1.sfbay.Sun.COM>; Fri, 15 May 2009 06:07:07 -0700 (PDT) Received: from dm-east-01.east.sun.com ([129.148.9.192]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJO00MTMSFTJQ90@nwk-avmta-1.sfbay.Sun.COM>; Fri, 15 May 2009 06:07:05 -0700 (PDT) Received: from phorcys.east.sun.com (phorcys.East.Sun.COM [129.148.174.143]) by dm-east-01.east.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n4FD73BX057820; Fri, 15 May 2009 09:07:03 -0400 (EDT) Received: from phorcys.east.sun.com (phorcys.local [127.0.0.1]) by phorcys.east.sun.com (8.14.3+Sun/8.14.3) with ESMTP id n4FD6A6h017856; Fri, 15 May 2009 09:06:10 -0400 (EDT) Received: (from carlsonj@localhost) by phorcys.east.sun.com (8.14.3+Sun/8.14.3/Submit) id n4FD6ARP017853; Fri, 15 May 2009 09:06:10 -0400 (EDT) Date: Fri, 15 May 2009 09:06:10 -0400 From: James Carlson Subject: LSARC/2009/262 trove-2.0.4 In-reply-to: <4A0C8F6C.1000505@sun.com> To: "Garrett D'Amore" Cc: Michael Kearney , Lloyd Chambers , lsarc-ext@sun.com, psarc-ext@sun.com, Vivek Titarmare Message-id: <18957.26818.520122.579037@gargle.gargle.HOWL> MIME-version: 1.0 X-Mailer: VM 7.01 under Emacs 21.3.1 Content-type: text/plain; charset=us-ascii Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <4A0C6E41.1020607@sun.com> <4A0C87FE.2040404@Sun.com> <4A0C8AAA.1010200@sun.com> <4A0C8F6C.1000505@sun.com> Status: RO Content-Length: 674 [repaired incorrect subject line and cc list] Garrett D'Amore writes: > This is all driven by my believe that the Java platform is just that -- > a platform -- that stands apart from Solaris. That part doesn't sound right to me. Neither LSARC nor PSARC nor the ARC in general are in any way specific to Solaris. They're Sun engineering processes. Simply saying that the Java system is its own platform isn't enough to determine the ARC's role. -- James Carlson, Solaris Networking Sun Microsystems / 35 Network Drive 71.232W Vox +1 781 442 2084 MS UBUR02-212 / Burlington MA 01803-2757 42.496N Fax +1 781 442 1677 From carlsonj@phorcys.east.sun.com Fri May 15 06:07:10 2009 Received: from sunmail3mpk.sfbay.sun.com (sunmail3mpk.SFBay.Sun.COM [129.146.11.52]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4FD7AYW019653; Fri, 15 May 2009 06:07:10 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail3mpk.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4FD76wr012288; Fri, 15 May 2009 06:07:09 -0700 (PDT) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJO00F1TSFV9Y00@nwk-avmta-1.sfbay.Sun.COM>; Fri, 15 May 2009 06:07:07 -0700 (PDT) Received: from dm-east-01.east.sun.com ([129.148.9.192]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJO00MTMSFTJQ90@nwk-avmta-1.sfbay.Sun.COM>; Fri, 15 May 2009 06:07:05 -0700 (PDT) Received: from phorcys.east.sun.com (phorcys.East.Sun.COM [129.148.174.143]) by dm-east-01.east.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n4FD73BX057820; Fri, 15 May 2009 09:07:03 -0400 (EDT) Received: from phorcys.east.sun.com (phorcys.local [127.0.0.1]) by phorcys.east.sun.com (8.14.3+Sun/8.14.3) with ESMTP id n4FD6A6h017856; Fri, 15 May 2009 09:06:10 -0400 (EDT) Received: (from carlsonj@localhost) by phorcys.east.sun.com (8.14.3+Sun/8.14.3/Submit) id n4FD6ARP017853; Fri, 15 May 2009 09:06:10 -0400 (EDT) Date: Fri, 15 May 2009 09:06:10 -0400 From: James Carlson Subject: LSARC/2009/262 trove-2.0.4 In-reply-to: <4A0C8F6C.1000505@sun.com> To: "Garrett D'Amore" Cc: Michael Kearney , Lloyd Chambers , lsarc-ext@sun.com, psarc-ext@sun.com, Vivek Titarmare Message-id: <18957.26818.520122.579037@gargle.gargle.HOWL> MIME-version: 1.0 X-Mailer: VM 7.01 under Emacs 21.3.1 Content-type: text/plain; charset=us-ascii Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <4A0C6E41.1020607@sun.com> <4A0C87FE.2040404@Sun.com> <4A0C8AAA.1010200@sun.com> <4A0C8F6C.1000505@sun.com> Status: RO Content-Length: 674 [repaired incorrect subject line and cc list] Garrett D'Amore writes: > This is all driven by my believe that the Java platform is just that -- > a platform -- that stands apart from Solaris. That part doesn't sound right to me. Neither LSARC nor PSARC nor the ARC in general are in any way specific to Solaris. They're Sun engineering processes. Simply saying that the Java system is its own platform isn't enough to determine the ARC's role. -- James Carlson, Solaris Networking Sun Microsystems / 35 Network Drive 71.232W Vox +1 781 442 2084 MS UBUR02-212 / Burlington MA 01803-2757 42.496N Fax +1 781 442 1677 From storycrafter@gmail.com Fri May 15 08:17:27 2009 Received: from sunmail2sca.sfbay.sun.com (sunmail2sca.SFBay.Sun.COM [129.145.155.234]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4FFHQaV019248; Fri, 15 May 2009 08:17:26 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail2sca.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4FFHPUL025809; Fri, 15 May 2009 08:17:25 -0700 (PDT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJO00801YH13B00@brm-avmta-1.central.sun.com>; Fri, 15 May 2009 09:17:25 -0600 (MDT) Received: from brmea-mail-4.sun.com ([192.18.98.36]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJO00I0VYH0MYB0@brm-avmta-1.central.sun.com>; Fri, 15 May 2009 09:17:24 -0600 (MDT) Received: from relay41i.sun.com ([192.5.209.70]) by brmea-mail-4.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n4FFHOoS019439; Fri, 15 May 2009 15:17:24 +0000 (GMT) Received: from mms49es.mms.us.syntegra.com ([160.41.221.232] [160.41.221.232]) by relay41i.sun.com with ESMTP id BT-MMP-3812801; Fri, 15 May 2009 15:15:24 +0000 (Z) Received: from relay43i.sun.com (relay43i.sun.com [192.5.209.74]) by mms49es.mms.us.syntegra.com with ESMTP id BT-MMP-13293996; Fri, 15 May 2009 15:15:23 +0000 (Z) Received: from qw-out-1920.google.com ([74.125.92.145] [74.125.92.145]) by relay4i.sun.com with ESMTP id BT-MMP-15074231; Fri, 15 May 2009 15:15:23 +0000 (Z) Received: by qw-out-1920.google.com with SMTP id 9so1400387qwj.50 for ; Fri, 15 May 2009 08:14:33 -0700 (PDT) Received: by 10.220.85.198 with SMTP id p6mr4881182vcl.63.1242400472969; Fri, 15 May 2009 08:14:32 -0700 (PDT) Date: Fri, 15 May 2009 10:14:32 -0500 From: Mark Martin Subject: Re: LSARC/2009/262 trove-2.0.4 In-reply-to: <18957.26818.520122.579037@gargle.gargle.HOWL> To: James Carlson Cc: "Garrett D'Amore" , psarc-ext@sun.com, Michael Kearney , lsarc-ext@sun.com, Lloyd Chambers Message-id: MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=domainkey-signature:mime-version:received:in-reply-to:references :date:message-id:subject:from:to:cc:content-type :content-transfer-encoding; bh=Fs/KQiWmT0iffTTMMMj3O3sLEFtvFKIbYuhG5lRmHkA=; b=sxSQU3CwCiT+7MHzxWXgoOZY3DEC9cgBXPWi4jIDRjd8lMb5JCEP3v/F3kq4e79Tv/ MuI/8DUBvrPbJ63qlwAss5Gl/sRecA2yjvjghml6YEGl4yB4vAbPEYloQtsIrRvkrizO npVaaQUIawZjf4apo+15PiGrR8rwr5BxPbNWM= DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :cc:content-type:content-transfer-encoding; b=qcastP32H7/1s7ndmfOwx1ganUg/bF4ZdvXXK1NRquojNUh5Q+Kbcx2YjODrGxab9C ysYbCXpWUsFSLHy84t42qFVRabFfQQlcQE9ooT9kOjXsL/mJahFEYQnA5qj/U4eqWXKu 1z6HjkQ+oIH9BTdJ8b5N62BjSj//cVJgPXFMA= X-PMX-Version: 5.4.1.325704 X-Brightmail-Tracker: AAAAAA== X-Antispam: No, score=-2.6/5.0, scanned in 0.076sec at (localhost [127.0.0.1]) by smf-spamd v1.3.1 - http://smfs.sf.net/ References: <4A0C6E41.1020607@sun.com> <4A0C87FE.2040404@Sun.com> <4A0C8AAA.1010200@sun.com> <4A0C8F6C.1000505@sun.com> <18957.26818.520122.579037@gargle.gargle.HOWL> Content-Transfer-Encoding: 8bit X-MIME-Autoconverted: from quoted-printable to 8bit by sac.sfbay.sun.com id n4FFHQaV019248 Status: RO Content-Length: 2043 On Fri, May 15, 2009 at 8:06 AM, James Carlson wrote: > [repaired incorrect subject line and cc list] Thanks. > > Garrett D'Amore writes: >> This is all driven by my believe that the Java platform is just that -- >> a platform -- that stands apart from Solaris. > > That part doesn't sound right to me.  Neither LSARC nor PSARC nor the > ARC in general are in any way specific to Solaris.  They're Sun > engineering processes. > > Simply saying that the Java system is its own platform isn't enough to > determine the ARC's role. > I wish I had the original thread. I would agree with Garrett in at least one respect -- Java is its own platform -- with its own ecosystem, practices, and requirements. Many Java applications have their own update mechanism and delivery channels. Java applications and libraries depend on JRE releases as much as more as OS releases. They have their own documentation. Etc. It's more than, say Python, for instance -- Java was arguably designed with a lot more intent surrounding packaging and distribution (manifests), and a more dynamic run-time (classloaders). It seems somewhat like a shoe-horn to package it onto such a relatively static delivery vehicle. I'm thinking of Netbeans, which can update itself. I'm thinking of Eclipse, that we hindered from updating itself. I'm thinking of all those common jars that got integrated project private. I don't think this changes the ARC's role (i.e. no JARC) at all, but I do wish there was a more complete, consistent, and robust picture of what it means to integrate Java packages, no matter from where they come. Maybe we'll get it right eventually as we plug along. > -- > James Carlson, Solaris Networking               > Sun Microsystems / 35 Network Drive        71.232W   Vox +1 781 442 2084 > MS UBUR02-212 / Burlington MA 01803-2757   42.496N   Fax +1 781 442 1677 > _______________________________________________ > opensolaris-arc mailing list > opensolaris-arc@opensolaris.org > From storycrafter@gmail.com Fri May 15 08:17:27 2009 Received: from sunmail2sca.sfbay.sun.com (sunmail2sca.SFBay.Sun.COM [129.145.155.234]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4FFHQaV019248; Fri, 15 May 2009 08:17:26 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail2sca.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4FFHPUL025809; Fri, 15 May 2009 08:17:25 -0700 (PDT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJO00801YH13B00@brm-avmta-1.central.sun.com>; Fri, 15 May 2009 09:17:25 -0600 (MDT) Received: from brmea-mail-4.sun.com ([192.18.98.36]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJO00I0VYH0MYB0@brm-avmta-1.central.sun.com>; Fri, 15 May 2009 09:17:24 -0600 (MDT) Received: from relay41i.sun.com ([192.5.209.70]) by brmea-mail-4.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n4FFHOoS019439; Fri, 15 May 2009 15:17:24 +0000 (GMT) Received: from mms49es.mms.us.syntegra.com ([160.41.221.232] [160.41.221.232]) by relay41i.sun.com with ESMTP id BT-MMP-3812801; Fri, 15 May 2009 15:15:24 +0000 (Z) Received: from relay43i.sun.com (relay43i.sun.com [192.5.209.74]) by mms49es.mms.us.syntegra.com with ESMTP id BT-MMP-13293996; Fri, 15 May 2009 15:15:23 +0000 (Z) Received: from qw-out-1920.google.com ([74.125.92.145] [74.125.92.145]) by relay4i.sun.com with ESMTP id BT-MMP-15074231; Fri, 15 May 2009 15:15:23 +0000 (Z) Received: by qw-out-1920.google.com with SMTP id 9so1400387qwj.50 for ; Fri, 15 May 2009 08:14:33 -0700 (PDT) Received: by 10.220.85.198 with SMTP id p6mr4881182vcl.63.1242400472969; Fri, 15 May 2009 08:14:32 -0700 (PDT) Date: Fri, 15 May 2009 10:14:32 -0500 From: Mark Martin Subject: Re: LSARC/2009/262 trove-2.0.4 In-reply-to: <18957.26818.520122.579037@gargle.gargle.HOWL> To: James Carlson Cc: "Garrett D'Amore" , psarc-ext@sun.com, Michael Kearney , lsarc-ext@sun.com, Lloyd Chambers Message-id: MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=domainkey-signature:mime-version:received:in-reply-to:references :date:message-id:subject:from:to:cc:content-type :content-transfer-encoding; bh=Fs/KQiWmT0iffTTMMMj3O3sLEFtvFKIbYuhG5lRmHkA=; b=sxSQU3CwCiT+7MHzxWXgoOZY3DEC9cgBXPWi4jIDRjd8lMb5JCEP3v/F3kq4e79Tv/ MuI/8DUBvrPbJ63qlwAss5Gl/sRecA2yjvjghml6YEGl4yB4vAbPEYloQtsIrRvkrizO npVaaQUIawZjf4apo+15PiGrR8rwr5BxPbNWM= DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :cc:content-type:content-transfer-encoding; b=qcastP32H7/1s7ndmfOwx1ganUg/bF4ZdvXXK1NRquojNUh5Q+Kbcx2YjODrGxab9C ysYbCXpWUsFSLHy84t42qFVRabFfQQlcQE9ooT9kOjXsL/mJahFEYQnA5qj/U4eqWXKu 1z6HjkQ+oIH9BTdJ8b5N62BjSj//cVJgPXFMA= X-PMX-Version: 5.4.1.325704 X-Brightmail-Tracker: AAAAAA== X-Antispam: No, score=-2.6/5.0, scanned in 0.076sec at (localhost [127.0.0.1]) by smf-spamd v1.3.1 - http://smfs.sf.net/ References: <4A0C6E41.1020607@sun.com> <4A0C87FE.2040404@Sun.com> <4A0C8AAA.1010200@sun.com> <4A0C8F6C.1000505@sun.com> <18957.26818.520122.579037@gargle.gargle.HOWL> Content-Transfer-Encoding: 8bit X-MIME-Autoconverted: from quoted-printable to 8bit by sac.sfbay.sun.com id n4FFHQaV019248 Status: RO Content-Length: 2043 On Fri, May 15, 2009 at 8:06 AM, James Carlson wrote: > [repaired incorrect subject line and cc list] Thanks. > > Garrett D'Amore writes: >> This is all driven by my believe that the Java platform is just that -- >> a platform -- that stands apart from Solaris. > > That part doesn't sound right to me.  Neither LSARC nor PSARC nor the > ARC in general are in any way specific to Solaris.  They're Sun > engineering processes. > > Simply saying that the Java system is its own platform isn't enough to > determine the ARC's role. > I wish I had the original thread. I would agree with Garrett in at least one respect -- Java is its own platform -- with its own ecosystem, practices, and requirements. Many Java applications have their own update mechanism and delivery channels. Java applications and libraries depend on JRE releases as much as more as OS releases. They have their own documentation. Etc. It's more than, say Python, for instance -- Java was arguably designed with a lot more intent surrounding packaging and distribution (manifests), and a more dynamic run-time (classloaders). It seems somewhat like a shoe-horn to package it onto such a relatively static delivery vehicle. I'm thinking of Netbeans, which can update itself. I'm thinking of Eclipse, that we hindered from updating itself. I'm thinking of all those common jars that got integrated project private. I don't think this changes the ARC's role (i.e. no JARC) at all, but I do wish there was a more complete, consistent, and robust picture of what it means to integrate Java packages, no matter from where they come. Maybe we'll get it right eventually as we plug along. > -- > James Carlson, Solaris Networking               > Sun Microsystems / 35 Network Drive        71.232W   Vox +1 781 442 2084 > MS UBUR02-212 / Burlington MA 01803-2757   42.496N   Fax +1 781 442 1677 > _______________________________________________ > opensolaris-arc mailing list > opensolaris-arc@opensolaris.org > From gdamore@sun.com Fri May 15 13:28:08 2009 Received: from sunmail3mpk.sfbay.sun.com (sunmail3mpk.SFBay.Sun.COM [129.146.11.52]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4FKS8p8023708; Fri, 15 May 2009 13:28:08 -0700 (PDT) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by sunmail3mpk.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4FKS572010509; Fri, 15 May 2009 13:28:07 -0700 (PDT) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJP0040TCURD200@nwk-avmta-2.sfbay.sun.com>; Fri, 15 May 2009 13:28:03 -0700 (PDT) Received: from sca-es-mail-1.sun.com ([192.18.43.132]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJP00EM4CUP90E0@nwk-avmta-2.sfbay.sun.com>; Fri, 15 May 2009 13:28:01 -0700 (PDT) Received: from fe-sfbay-10.sun.com ([192.18.43.129]) by sca-es-mail-1.sun.com (8.13.7+Sun/8.12.9) with ESMTP id n4FKS5N3005637; Fri, 15 May 2009 13:28:05 -0700 (PDT) Received: from conversion-daemon.fe-sfbay-10.sun.com by fe-sfbay-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJP00J00CAHWF00@fe-sfbay-10.sun.com>; Fri, 15 May 2009 13:28:05 -0700 (PDT) Received: from [192.168.251.11] ([unknown] [76.93.15.33]) by fe-sfbay-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJP00324CUTAOG0@fe-sfbay-10.sun.com>; Fri, 15 May 2009 13:28:05 -0700 (PDT) Date: Fri, 15 May 2009 13:28:04 -0700 From: "Garrett D'Amore" Subject: Re: LSARC/2009/262 trove-2.0.4 In-reply-to: <18957.26818.520122.579037@gargle.gargle.HOWL> Sender: Garrett.Damore@sun.com To: James Carlson Cc: Michael Kearney , Lloyd Chambers , lsarc-ext@sun.com, psarc-ext@sun.com, Vivek Titarmare Message-id: <4A0DD054.2080707@sun.com> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <4A0C6E41.1020607@sun.com> <4A0C87FE.2040404@Sun.com> <4A0C8AAA.1010200@sun.com> <4A0C8F6C.1000505@sun.com> <18957.26818.520122.579037@gargle.gargle.HOWL> User-Agent: Thunderbird 2.0.0.18 (X11/20081201) Status: RO Content-Length: 1539 James Carlson wrote: > [repaired incorrect subject line and cc list] > > Garrett D'Amore writes: > >> This is all driven by my believe that the Java platform is just that -- >> a platform -- that stands apart from Solaris. >> > > That part doesn't sound right to me. Neither LSARC nor PSARC nor the > ARC in general are in any way specific to Solaris. They're Sun > engineering processes. > > Simply saying that the Java system is its own platform isn't enough to > determine the ARC's role. > > My point here is that Java already has its own processes... and IMO its not really relevant for ARC to be reviewing Java APIs anymore that it is relevant for ARC to be reviewing updates to the ISO C standard. Like it or not, I believe ARC review (or at least PSARC review) is most pertinent for Solaris -- and supporting technologies -- and probably far less relevant for other things that have nothing to do with Solaris. (Review of technologies that we ship to facilitate platforms which run Solaris -- such as compilers and service processors -- does, however, make sense -- at least IMO.) Some of this determination needs to be made, IMO, by human judgment. But I don't think it makes sense to apply ARC review to *everything* that Sun engineers produce. Do we (for example), want to get involved with reviewing the deliverables that make up the bits that we ship for use on Cell phones as part of J2ME? Are there ARC members who are even *qualified* to offer a meaningful review of such? -- Garrett From gdamore@sun.com Fri May 15 13:28:08 2009 Received: from sunmail3mpk.sfbay.sun.com (sunmail3mpk.SFBay.Sun.COM [129.146.11.52]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4FKS8p8023708; Fri, 15 May 2009 13:28:08 -0700 (PDT) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by sunmail3mpk.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4FKS572010509; Fri, 15 May 2009 13:28:07 -0700 (PDT) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJP0040TCURD200@nwk-avmta-2.sfbay.sun.com>; Fri, 15 May 2009 13:28:03 -0700 (PDT) Received: from sca-es-mail-1.sun.com ([192.18.43.132]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJP00EM4CUP90E0@nwk-avmta-2.sfbay.sun.com>; Fri, 15 May 2009 13:28:01 -0700 (PDT) Received: from fe-sfbay-10.sun.com ([192.18.43.129]) by sca-es-mail-1.sun.com (8.13.7+Sun/8.12.9) with ESMTP id n4FKS5N3005637; Fri, 15 May 2009 13:28:05 -0700 (PDT) Received: from conversion-daemon.fe-sfbay-10.sun.com by fe-sfbay-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJP00J00CAHWF00@fe-sfbay-10.sun.com>; Fri, 15 May 2009 13:28:05 -0700 (PDT) Received: from [192.168.251.11] ([unknown] [76.93.15.33]) by fe-sfbay-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJP00324CUTAOG0@fe-sfbay-10.sun.com>; Fri, 15 May 2009 13:28:05 -0700 (PDT) Date: Fri, 15 May 2009 13:28:04 -0700 From: "Garrett D'Amore" Subject: Re: LSARC/2009/262 trove-2.0.4 In-reply-to: <18957.26818.520122.579037@gargle.gargle.HOWL> Sender: Garrett.Damore@sun.com To: James Carlson Cc: Michael Kearney , Lloyd Chambers , lsarc-ext@sun.com, psarc-ext@sun.com, Vivek Titarmare Message-id: <4A0DD054.2080707@sun.com> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <4A0C6E41.1020607@sun.com> <4A0C87FE.2040404@Sun.com> <4A0C8AAA.1010200@sun.com> <4A0C8F6C.1000505@sun.com> <18957.26818.520122.579037@gargle.gargle.HOWL> User-Agent: Thunderbird 2.0.0.18 (X11/20081201) Status: RO Content-Length: 1539 James Carlson wrote: > [repaired incorrect subject line and cc list] > > Garrett D'Amore writes: > >> This is all driven by my believe that the Java platform is just that -- >> a platform -- that stands apart from Solaris. >> > > That part doesn't sound right to me. Neither LSARC nor PSARC nor the > ARC in general are in any way specific to Solaris. They're Sun > engineering processes. > > Simply saying that the Java system is its own platform isn't enough to > determine the ARC's role. > > My point here is that Java already has its own processes... and IMO its not really relevant for ARC to be reviewing Java APIs anymore that it is relevant for ARC to be reviewing updates to the ISO C standard. Like it or not, I believe ARC review (or at least PSARC review) is most pertinent for Solaris -- and supporting technologies -- and probably far less relevant for other things that have nothing to do with Solaris. (Review of technologies that we ship to facilitate platforms which run Solaris -- such as compilers and service processors -- does, however, make sense -- at least IMO.) Some of this determination needs to be made, IMO, by human judgment. But I don't think it makes sense to apply ARC review to *everything* that Sun engineers produce. Do we (for example), want to get involved with reviewing the deliverables that make up the bits that we ship for use on Cell phones as part of J2ME? Are there ARC members who are even *qualified* to offer a meaningful review of such? -- Garrett From glenn.skinner@sun.com Mon May 18 10:54:37 2009 Received: from sunmail4.singapore.sun.com (sunmail4.Singapore.Sun.COM [129.158.71.19]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4IHsZMF006035 for ; Mon, 18 May 2009 10:54:35 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail4.singapore.sun.com (8.13.4+Sun/8.13.3/ENSMAIL,v2.2) with ESMTP id n4IHsOgq017362; Tue, 19 May 2009 01:54:34 +0800 (SGT) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJU00I17PQVRA00@nwk-avmta-1.sfbay.Sun.COM>; Mon, 18 May 2009 10:54:31 -0700 (PDT) Received: from ivrel.sfbay.sun.com ([129.146.74.76]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJU00IINPQU04E0@nwk-avmta-1.sfbay.Sun.COM>; Mon, 18 May 2009 10:54:30 -0700 (PDT) Received: from ivrel (ivrel [129.146.74.76]) by ivrel.sfbay.sun.com (8.13.8+Sun/8.13.8) with SMTP id n4IHsUwN021842; Mon, 18 May 2009 10:54:30 -0700 (PDT) Date: Mon, 18 May 2009 10:54:30 -0700 (PDT) From: Glenn Skinner Subject: Re: LSARC 2009/262 - trove (JAR documentation requirements) To: LSARC-ext@sun.com Cc: psarc-members@sun.com, Vivek.Titarmare@sun.com Reply-to: Glenn Skinner Message-id: <200905181754.n4IHsUwN021842@ivrel.sfbay.sun.com> MIME-version: 1.0 X-Mailer: dtmail 1.3.0 @(#)CDE Version 1.6_36 SunOS 5.11 sun4u sparc Content-type: TEXT/plain; charset=us-ascii Content-transfer-encoding: 7BIT Content-MD5: T2Ff5C1KnPsxORJbIFiCMg== X-PMX-Version: 5.4.1.325704 Status: RO Content-Length: 1635 1) I agree with others who have stated that we can't impose a taxonomy classification scheme on software that we import from an external community. But that doesn't mean that we can't do so for software that our community develops. 2) I agree with those who have said that documentation expectations for the Java platform differ from those for (say) Solaris. When working in the Java world, people expect javadocs to be the primary source of documentation, with other sources such as man pages coming in a distant second. Providing stability classifications for a JAR file by means of a man page for that JAR file is an awkward solution that's unlikely to reach a substantial fraction of its target audience. (But it may be the best we can do for JAR files developed by external communities with their own expectations and procedures.) 3) I think Lloyd's proposal is technically quite interesting for use in Java project developed within our community. My main concern with it is one of logistics. Where will the annotation classes that it depends on live? What Java packages will contain them? How will those packages be delivered? Can all projects developed within our community that might wish to use these annotations be assured that they'll be available in the delivery and deployment contexts that those projects will use? (I fear that the proposal will only become useful should its annotation classes become part of the standard Java platform, so that nothing explicit need be done to gain access to them.) -- Glenn From sacadmin Mon May 18 10:54:39 2009 Received: from sunmail4.singapore.sun.com (sunmail4.Singapore.Sun.COM [129.158.71.19]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4IHsbqL006037 for ; Mon, 18 May 2009 10:54:38 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail4.singapore.sun.com (8.13.4+Sun/8.13.3/ENSMAIL,v2.2) with ESMTP id n4IHsOgq017362; Tue, 19 May 2009 01:54:34 +0800 (SGT) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJU00I17PQVRA00@nwk-avmta-1.sfbay.Sun.COM>; Mon, 18 May 2009 10:54:31 -0700 (PDT) Received: from ivrel.sfbay.sun.com ([129.146.74.76]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJU00IINPQU04E0@nwk-avmta-1.sfbay.Sun.COM>; Mon, 18 May 2009 10:54:30 -0700 (PDT) Received: from ivrel (ivrel [129.146.74.76]) by ivrel.sfbay.sun.com (8.13.8+Sun/8.13.8) with SMTP id n4IHsUwN021842; Mon, 18 May 2009 10:54:30 -0700 (PDT) Date: Mon, 18 May 2009 10:54:30 -0700 (PDT) From: Glenn Skinner Subject: Re: LSARC 2009/262 - trove (JAR documentation requirements) To: LSARC-ext@sun.com Cc: psarc-members@sun.com, Vivek.Titarmare@sun.com Reply-to: Glenn Skinner Message-id: <200905181754.n4IHsUwN021842@ivrel.sfbay.sun.com> MIME-version: 1.0 X-Mailer: dtmail 1.3.0 @(#)CDE Version 1.6_36 SunOS 5.11 sun4u sparc Content-type: TEXT/plain; charset=us-ascii Content-transfer-encoding: 7BIT Content-MD5: T2Ff5C1KnPsxORJbIFiCMg== X-PMX-Version: 5.4.1.325704 Status: RO Content-Length: 1635 1) I agree with others who have stated that we can't impose a taxonomy classification scheme on software that we import from an external community. But that doesn't mean that we can't do so for software that our community develops. 2) I agree with those who have said that documentation expectations for the Java platform differ from those for (say) Solaris. When working in the Java world, people expect javadocs to be the primary source of documentation, with other sources such as man pages coming in a distant second. Providing stability classifications for a JAR file by means of a man page for that JAR file is an awkward solution that's unlikely to reach a substantial fraction of its target audience. (But it may be the best we can do for JAR files developed by external communities with their own expectations and procedures.) 3) I think Lloyd's proposal is technically quite interesting for use in Java project developed within our community. My main concern with it is one of logistics. Where will the annotation classes that it depends on live? What Java packages will contain them? How will those packages be delivered? Can all projects developed within our community that might wish to use these annotations be assured that they'll be available in the delivery and deployment contexts that those projects will use? (I fear that the proposal will only become useful should its annotation classes become part of the standard Java platform, so that nothing explicit need be done to gain access to them.) -- Glenn From Richard.Matthews@sun.com Tue May 19 08:17:48 2009 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4JFHl9i011839; Tue, 19 May 2009 08:17:47 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail5.uk.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n4JFHZ5I010715; Tue, 19 May 2009 16:17:46 +0100 (BST) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJW00C1TD5KXY00@nwk-avmta-1.sfbay.Sun.COM>; Tue, 19 May 2009 08:17:44 -0700 (PDT) Received: from brmea-mail-2.sun.com ([192.18.98.43]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJW00BYQD5IFU10@nwk-avmta-1.sfbay.Sun.COM>; Tue, 19 May 2009 08:17:42 -0700 (PDT) Received: from fe-amer-10.sun.com ([192.18.109.80]) by brmea-mail-2.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n4JFHgWa001463; Tue, 19 May 2009 15:17:42 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJW00200AOD5F00@mail-amer.sun.com>; Tue, 19 May 2009 09:17:42 -0600 (MDT) Received: from [129.152.9.11] ([unknown] [129.152.9.11]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJW00EYGD5CFA90@mail-amer.sun.com>; Tue, 19 May 2009 09:17:37 -0600 (MDT) Date: Tue, 19 May 2009 10:17:36 -0500 From: Rick Matthews Subject: Re: jar file man pages - was Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] In-reply-to: <4A0B11E3.90203@sun.com> Sender: Richard.Matthews@sun.com To: James.Walker@sun.com Cc: Michael Kearney , LSARC-ext@sun.com, Norm Jacobs , PSARC-ext@sun.com Reply-to: Richard.Matthews@sun.com Message-id: <4A12CD90.5050603@Sun.COM> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <4A09EB8D.6090800@sun.com> <4A09F80D.6080305@gmail.com> <10008ADD-B6FC-4D0F-85A1-5DD4393E4532@sun.com> <4A0AD25A.7070508@Sun.com> <4A0B11E3.90203@sun.com> User-Agent: Thunderbird 2.0.0.19 (X11/20090110) Status: RO Content-Length: 5295 I agree in principle with Jim's points. In particular, > 1. Provides users stability and availability (taxonomy) information > about jar file packages on Solaris/OpenSolaris not available anywhere > else. If ARCs are going to require this information, it should be documented somewhere that a user can find it a normal operating environment. Currently, I'd have to agree this is man pages. I think a further point of this discussion is a need for ARCs to adopt a consistent means of doing so, and stick to it. In several of the cited cases with man pages, the man pages were produced as part of the Fast Track process. In the case of LSARC/2009/262, it was questioned why we would have man pages for jar/java release vehicles. That is inconsistent, which is why I believe Jim raised the issue. Toward that end, issues continue to be raised with jar/java FOSS projects. There doesn't seem to be a "checklist" of items needed for a FOSS jar project (and of course, many checklists are incomplete). As I recall, the following issues resulted from FOSS cases delivering jar s: 1) How to deliver javadocs to OpenSolaris (mostly due to web site volume issues) 2) Man pages for stability and taxonomy 3) What portions need to have declared stability, etc. (like package name) 4) What JDK version(s)? 5) Versioning of jar files Mark Martin brought up number 5 quite awhile ago. There was no further action taken. The jar files really seem to parallel C libraries, and should have a best practice for versioning similar to (or maybe expanded) "Library and Shared Object Requirements". IMHO, man page declaration of stability and taxonomy works. Let's keep that until there is a suitable "better way". Lloyd's method of documenting is a good start, but we can't hope to force external communities to use such a method, except by general acceptance. We could make it a best practice for non-FOSS jar deliverables that are being ARCed. This assumes Lloyd's proposal is sound, which I don't feel qualified to have opinion. I think the ARCs need to look into these issues (as is being done), and reasonable methods/ practices be established, and then those be consistently applied. -- Rick On 05/13/09 13:30, Jim Walker wrote: > For LSARC, PSARC and the opinion writer(s) to consider.... > > Michael Kearney wrote: >> 1. Lloyd, I like the idea of your annotation but have a couple of >> concerns. - Would teams be expected to update third party, open >> source jar files with the annotation? >> - Would the ARC provide the common @Taxonomy annotation Java code? > > I have concerns too. > > In general, we will not be able to change FOSS code upstream like > this. We normally try to do as little modification as possible (ie. > just enough to get it to run well on Solaris/OpenSolaris). This > is another reason why short man pages are being tacked on. Is it > possible to tack on a page to the javadoc? > > I don't want to see big javadoc patches in the SFW consolidation that > document detailed taxonomy information that we have to carry forever > because they will never be accepted into the upstream community. > Why would a FOSS project creating jar files even care about our > taxonomy rules? > >> 2. What if the man page simple documented the stability at the >> granularity of the jar file and >> nothing else. Perhaps the man page could generically reference the >> Javadoc? > > Not every jar file in /usr/share/lib/java has a man page, but > that is the current practice, for the ones that do: > > $ man asm > $ man mvel > $ man janino > $ man jettison > $ man joda-time > $ man jaxen-core > $ man junit > $ man ant (needs a more direct reference to javadoc) > ... > > As I see it, having jar file man pages... > > 1. Provides users stability and availability (taxonomy) information > about jar file packages on Solaris/OpenSolaris not available anywhere > else. > 2. Is pretty painless for project teams to produce and support. > 3. Man pages do no harm, and I think users are already getting > use to having them. Some information is better than no information. > 4. Until there is a better way, man pages should be required for > any new jar file submissions into Solaris/OpenSolaris. I thought > this was already true. > 5. Man pages are used by most Solaris/OpenSolaris packages. > 6. I appreciate where Java developers are coming from, but "not standard > practice for Java developers to look for man pages" alone, doesn't seem > enough reason to stop man pages being delivered with jar file packages. > > We can't control how jar files are delivered or documented on > windows or other environments, but we can on Solaris/OpenSolaris. > > BTW. ccing Norm (sfw c-team lead) since one of the requirements to > integrate into sfw is a man page. > > Cheers, > Jim -- --------------------------------------------------------------------- Rick Matthews email: Rick.Matthews@sun.com Sun Microsystems, Inc. phone:+1(651) 554-1518 1270 Eagan Industrial Road phone(internal): 54418 Suite 160 fax: +1(651) 554-1540 Eagan, MN 55121-1231 USA main: +1(651) 554-1500 --------------------------------------------------------------------- From Richard.Matthews@sun.com Tue May 19 08:17:48 2009 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4JFHl9i011839; Tue, 19 May 2009 08:17:47 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail5.uk.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n4JFHZ5I010715; Tue, 19 May 2009 16:17:46 +0100 (BST) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJW00C1TD5KXY00@nwk-avmta-1.sfbay.Sun.COM>; Tue, 19 May 2009 08:17:44 -0700 (PDT) Received: from brmea-mail-2.sun.com ([192.18.98.43]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJW00BYQD5IFU10@nwk-avmta-1.sfbay.Sun.COM>; Tue, 19 May 2009 08:17:42 -0700 (PDT) Received: from fe-amer-10.sun.com ([192.18.109.80]) by brmea-mail-2.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n4JFHgWa001463; Tue, 19 May 2009 15:17:42 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJW00200AOD5F00@mail-amer.sun.com>; Tue, 19 May 2009 09:17:42 -0600 (MDT) Received: from [129.152.9.11] ([unknown] [129.152.9.11]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJW00EYGD5CFA90@mail-amer.sun.com>; Tue, 19 May 2009 09:17:37 -0600 (MDT) Date: Tue, 19 May 2009 10:17:36 -0500 From: Rick Matthews Subject: Re: jar file man pages - was Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] In-reply-to: <4A0B11E3.90203@sun.com> Sender: Richard.Matthews@sun.com To: James.Walker@sun.com Cc: Michael Kearney , LSARC-ext@sun.com, Norm Jacobs , PSARC-ext@sun.com Reply-to: Richard.Matthews@sun.com Message-id: <4A12CD90.5050603@Sun.COM> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <4A09EB8D.6090800@sun.com> <4A09F80D.6080305@gmail.com> <10008ADD-B6FC-4D0F-85A1-5DD4393E4532@sun.com> <4A0AD25A.7070508@Sun.com> <4A0B11E3.90203@sun.com> User-Agent: Thunderbird 2.0.0.19 (X11/20090110) Status: RO Content-Length: 5295 I agree in principle with Jim's points. In particular, > 1. Provides users stability and availability (taxonomy) information > about jar file packages on Solaris/OpenSolaris not available anywhere > else. If ARCs are going to require this information, it should be documented somewhere that a user can find it a normal operating environment. Currently, I'd have to agree this is man pages. I think a further point of this discussion is a need for ARCs to adopt a consistent means of doing so, and stick to it. In several of the cited cases with man pages, the man pages were produced as part of the Fast Track process. In the case of LSARC/2009/262, it was questioned why we would have man pages for jar/java release vehicles. That is inconsistent, which is why I believe Jim raised the issue. Toward that end, issues continue to be raised with jar/java FOSS projects. There doesn't seem to be a "checklist" of items needed for a FOSS jar project (and of course, many checklists are incomplete). As I recall, the following issues resulted from FOSS cases delivering jar s: 1) How to deliver javadocs to OpenSolaris (mostly due to web site volume issues) 2) Man pages for stability and taxonomy 3) What portions need to have declared stability, etc. (like package name) 4) What JDK version(s)? 5) Versioning of jar files Mark Martin brought up number 5 quite awhile ago. There was no further action taken. The jar files really seem to parallel C libraries, and should have a best practice for versioning similar to (or maybe expanded) "Library and Shared Object Requirements". IMHO, man page declaration of stability and taxonomy works. Let's keep that until there is a suitable "better way". Lloyd's method of documenting is a good start, but we can't hope to force external communities to use such a method, except by general acceptance. We could make it a best practice for non-FOSS jar deliverables that are being ARCed. This assumes Lloyd's proposal is sound, which I don't feel qualified to have opinion. I think the ARCs need to look into these issues (as is being done), and reasonable methods/ practices be established, and then those be consistently applied. -- Rick On 05/13/09 13:30, Jim Walker wrote: > For LSARC, PSARC and the opinion writer(s) to consider.... > > Michael Kearney wrote: >> 1. Lloyd, I like the idea of your annotation but have a couple of >> concerns. - Would teams be expected to update third party, open >> source jar files with the annotation? >> - Would the ARC provide the common @Taxonomy annotation Java code? > > I have concerns too. > > In general, we will not be able to change FOSS code upstream like > this. We normally try to do as little modification as possible (ie. > just enough to get it to run well on Solaris/OpenSolaris). This > is another reason why short man pages are being tacked on. Is it > possible to tack on a page to the javadoc? > > I don't want to see big javadoc patches in the SFW consolidation that > document detailed taxonomy information that we have to carry forever > because they will never be accepted into the upstream community. > Why would a FOSS project creating jar files even care about our > taxonomy rules? > >> 2. What if the man page simple documented the stability at the >> granularity of the jar file and >> nothing else. Perhaps the man page could generically reference the >> Javadoc? > > Not every jar file in /usr/share/lib/java has a man page, but > that is the current practice, for the ones that do: > > $ man asm > $ man mvel > $ man janino > $ man jettison > $ man joda-time > $ man jaxen-core > $ man junit > $ man ant (needs a more direct reference to javadoc) > ... > > As I see it, having jar file man pages... > > 1. Provides users stability and availability (taxonomy) information > about jar file packages on Solaris/OpenSolaris not available anywhere > else. > 2. Is pretty painless for project teams to produce and support. > 3. Man pages do no harm, and I think users are already getting > use to having them. Some information is better than no information. > 4. Until there is a better way, man pages should be required for > any new jar file submissions into Solaris/OpenSolaris. I thought > this was already true. > 5. Man pages are used by most Solaris/OpenSolaris packages. > 6. I appreciate where Java developers are coming from, but "not standard > practice for Java developers to look for man pages" alone, doesn't seem > enough reason to stop man pages being delivered with jar file packages. > > We can't control how jar files are delivered or documented on > windows or other environments, but we can on Solaris/OpenSolaris. > > BTW. ccing Norm (sfw c-team lead) since one of the requirements to > integrate into sfw is a man page. > > Cheers, > Jim -- --------------------------------------------------------------------- Rick Matthews email: Rick.Matthews@sun.com Sun Microsystems, Inc. phone:+1(651) 554-1518 1270 Eagan Industrial Road phone(internal): 54418 Suite 160 fax: +1(651) 554-1540 Eagan, MN 55121-1231 USA main: +1(651) 554-1500 --------------------------------------------------------------------- From Michael.Kearney@Sun.COM Tue May 19 08:54:10 2009 Received: from sunmail4.singapore.sun.com (sunmail4.Singapore.Sun.COM [129.158.71.19]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4JFs9uu013461; Tue, 19 May 2009 08:54:09 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail4.singapore.sun.com (8.13.4+Sun/8.13.3/ENSMAIL,v2.2) with ESMTP id n4JFs7eI018400; Tue, 19 May 2009 23:54:07 +0800 (SGT) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJW00J0JEU6A000@nwk-avmta-1.sfbay.Sun.COM>; Tue, 19 May 2009 08:54:06 -0700 (PDT) Received: from brmea-mail-4.sun.com ([192.18.98.36]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJW00BD7EU5FW80@nwk-avmta-1.sfbay.Sun.COM>; Tue, 19 May 2009 08:54:05 -0700 (PDT) Received: from fe-amer-09.sun.com ([192.18.109.79]) by brmea-mail-4.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n4JFs5iC011433; Tue, 19 May 2009 15:54:05 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJW00800E0VHJ00@mail-amer.sun.com>; Tue, 19 May 2009 09:54:05 -0600 (MDT) Received: from [129.147.49.125] ([unknown] [129.147.49.125]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJW00DVDETWLY70@mail-amer.sun.com>; Tue, 19 May 2009 09:53:57 -0600 (MDT) Date: Tue, 19 May 2009 09:53:55 -0600 From: Michael Kearney Subject: Re: jar file man pages - was Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] In-reply-to: <4A0C9FAE.8070504@Sun.COM> Sender: Michael.Kearney@Sun.COM To: Norm Jacobs Cc: James.Walker@Sun.COM, LSARC-ext@Sun.COM, PSARC-ext@Sun.COM Message-id: <4A12D613.1080803@Sun.com> MIME-version: 1.0 Content-type: multipart/mixed; boundary="Boundary_(ID_6VDab7X4R6c8Jzx7vYgUeA)" X-PMX-Version: 5.4.1.325704 References: <4A09EB8D.6090800@sun.com> <4A09F80D.6080305@gmail.com> <10008ADD-B6FC-4D0F-85A1-5DD4393E4532@sun.com> <4A0AD25A.7070508@Sun.com> <4A0B11E3.90203@sun.com> <4A0C9FAE.8070504@Sun.COM> User-Agent: Thunderbird 2.0.0.17 (Windows/20080914) Status: RO Content-Length: 7437 This is a multi-part message in MIME format. --Boundary_(ID_6VDab7X4R6c8Jzx7vYgUeA) Content-type: text/html; CHARSET=US-ASCII Content-transfer-encoding: 7BIT I wouldn't want to see the Sun jar files have the @Taxonomy annotation and a completely
different (or non-existent) method, such as a man page for FOSS jar files.
I'd like to see a single, consistent method and I think that's a short and simple man page.

          -Michael

Norm Jacobs wrote:
Jim Walker wrote:
For LSARC, PSARC and the opinion writer(s) to consider....

Michael Kearney wrote:
1. Lloyd, I like the idea of your annotation but have a couple of concerns.

    - Would teams be expected to update third party, open source jar files with the annotation?
    - Would the ARC provide the common @Taxonomy annotation Java code?
NO, NO, NO.  We don't want to be in the business of patching this bit of Sun lore into source and or documentation delivered by existing open source projects.  Largely, the projects are not going to be interested in this type of change.  This should be handled by a separate mechanism that falls outside of that arena, perhap by the taxonomy(1) command.

I have concerns too.

In general, we will not be able to change FOSS code upstream like
this. We normally try to do as little modification as possible (ie.
just enough to get it to run well on Solaris/OpenSolaris). This
is another reason why short man pages are being tacked on. Is it
possible to tack on a page to the javadoc?

Simply put, If we can leave the upstream bits alone, we should.  If we have to make changes to make it build, install, or function properly then coordinate those changes with the upstream community.  For SFW, it's ok to deliver them as a patch initially, but the expectation is that the next update will obsolete the patch unless there is a really compelling reason to deviate from the upstream.  This doesn't mean that you can't include support for SMF, RBAC, ...  It just means that we want something that doesn't require new patches at each update and ultimately, no patching at all would be preferred.  So again, leave the open source bits (docs in this case) alone unless there is a really compelling reason to deviate.


I don't want to see big javadoc patches in the SFW consolidation that
document detailed taxonomy information that we have to carry forever
because they will never be accepted into the upstream community.
Why would a FOSS project creating jar files even care about our
taxonomy rules?
They won't.

2. What if the man page simple documented the stability at the granularity of the jar file and
nothing else.  Perhaps the man page could generically reference the Javadoc?

Not every jar file in /usr/share/lib/java has a man page, but
that is the current practice, for the ones that do:

$ man asm
$ man mvel
$ man janino
$ man jettison
$ man joda-time
$ man jaxen-core
$ man junit
$ man ant (needs a more direct reference to javadoc)
...

As I see it, having jar file man pages...

1. Provides users stability and availability (taxonomy) information about jar file packages on Solaris/OpenSolaris not available anywhere
else.
2. Is pretty painless for project teams to produce and support.
3. Man pages do no harm, and I think users are already getting
use to having them. Some information is better than no information.
4. Until there is a better way, man pages should be required for
any new jar file submissions into Solaris/OpenSolaris. I thought
this was already true.
5. Man pages are used by most Solaris/OpenSolaris packages.
6. I appreciate where Java developers are coming from, but "not standard
practice for Java developers to look for man pages" alone, doesn't seem
enough reason to stop man pages being delivered with jar file packages.

We can't control how jar files are delivered or documented on
windows or other environments, but we can on Solaris/OpenSolaris.

BTW. ccing Norm (sfw c-team lead) since one of the requirements to
integrate into sfw is a man page.
The requirement has really been to provide documentation.  We have not forced folks to deliver man pages when the software they were delivering had it's own documentation.  If it comes with texinfo, javadoc, html, ... then we have let them deliver that documentation and not required a man page for everything.  If software was lacking documentation, we have asked for documentation that describes it, usually a man page.  The intent is to provide the documentation that is expected by the users of the software.

   -Norm




--
Michael Kearney
Staff Software Engineer

Sun Microsystems, Inc.
MS UBRM05-390, 500 Eldorado Blvd
Broomfield, CO 80021 US
Phone 303-272-2402
Fax 303-272-6554
Email Michael.Kearney@Sun.COM
--Boundary_(ID_6VDab7X4R6c8Jzx7vYgUeA) Content-type: text/x-vcard; CHARSET=US-ASCII; name=Michael_Kearney.vcf Content-transfer-encoding: 7BIT Content-disposition: attachment; filename=Michael_Kearney.vcf begin:vcard fn:Michael Kearney n:Kearney;Michael org:Sun Microsystems, Inc.;Archive Core Engineering adr:500 Eldorado Blvd.;;Mailstop UBRM05-390;Broomfield;CO;80021;US email;internet:Michael.Kearney@Sun.com title:Staff Software Engineer tel;work:303-272-2402 tel;fax:303-272-6554 x-mozilla-html:TRUE url:http://www.sun.com/ version:2.1 end:vcard --Boundary_(ID_6VDab7X4R6c8Jzx7vYgUeA)-- From Michael.Kearney@Sun.COM Tue May 19 08:54:10 2009 Received: from sunmail4.singapore.sun.com (sunmail4.Singapore.Sun.COM [129.158.71.19]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4JFs9uu013461; Tue, 19 May 2009 08:54:09 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail4.singapore.sun.com (8.13.4+Sun/8.13.3/ENSMAIL,v2.2) with ESMTP id n4JFs7eI018400; Tue, 19 May 2009 23:54:07 +0800 (SGT) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJW00J0JEU6A000@nwk-avmta-1.sfbay.Sun.COM>; Tue, 19 May 2009 08:54:06 -0700 (PDT) Received: from brmea-mail-4.sun.com ([192.18.98.36]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJW00BD7EU5FW80@nwk-avmta-1.sfbay.Sun.COM>; Tue, 19 May 2009 08:54:05 -0700 (PDT) Received: from fe-amer-09.sun.com ([192.18.109.79]) by brmea-mail-4.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n4JFs5iC011433; Tue, 19 May 2009 15:54:05 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJW00800E0VHJ00@mail-amer.sun.com>; Tue, 19 May 2009 09:54:05 -0600 (MDT) Received: from [129.147.49.125] ([unknown] [129.147.49.125]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJW00DVDETWLY70@mail-amer.sun.com>; Tue, 19 May 2009 09:53:57 -0600 (MDT) Date: Tue, 19 May 2009 09:53:55 -0600 From: Michael Kearney Subject: Re: jar file man pages - was Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] In-reply-to: <4A0C9FAE.8070504@Sun.COM> Sender: Michael.Kearney@Sun.COM To: Norm Jacobs Cc: James.Walker@Sun.COM, LSARC-ext@Sun.COM, PSARC-ext@Sun.COM Message-id: <4A12D613.1080803@Sun.com> MIME-version: 1.0 Content-type: multipart/mixed; boundary="Boundary_(ID_6VDab7X4R6c8Jzx7vYgUeA)" X-PMX-Version: 5.4.1.325704 References: <4A09EB8D.6090800@sun.com> <4A09F80D.6080305@gmail.com> <10008ADD-B6FC-4D0F-85A1-5DD4393E4532@sun.com> <4A0AD25A.7070508@Sun.com> <4A0B11E3.90203@sun.com> <4A0C9FAE.8070504@Sun.COM> User-Agent: Thunderbird 2.0.0.17 (Windows/20080914) Status: RO Content-Length: 7437 This is a multi-part message in MIME format. --Boundary_(ID_6VDab7X4R6c8Jzx7vYgUeA) Content-type: text/html; CHARSET=US-ASCII Content-transfer-encoding: 7BIT I wouldn't want to see the Sun jar files have the @Taxonomy annotation and a completely
different (or non-existent) method, such as a man page for FOSS jar files.
I'd like to see a single, consistent method and I think that's a short and simple man page.

          -Michael

Norm Jacobs wrote:
Jim Walker wrote:
For LSARC, PSARC and the opinion writer(s) to consider....

Michael Kearney wrote:
1. Lloyd, I like the idea of your annotation but have a couple of concerns.

    - Would teams be expected to update third party, open source jar files with the annotation?
    - Would the ARC provide the common @Taxonomy annotation Java code?
NO, NO, NO.  We don't want to be in the business of patching this bit of Sun lore into source and or documentation delivered by existing open source projects.  Largely, the projects are not going to be interested in this type of change.  This should be handled by a separate mechanism that falls outside of that arena, perhap by the taxonomy(1) command.

I have concerns too.

In general, we will not be able to change FOSS code upstream like
this. We normally try to do as little modification as possible (ie.
just enough to get it to run well on Solaris/OpenSolaris). This
is another reason why short man pages are being tacked on. Is it
possible to tack on a page to the javadoc?

Simply put, If we can leave the upstream bits alone, we should.  If we have to make changes to make it build, install, or function properly then coordinate those changes with the upstream community.  For SFW, it's ok to deliver them as a patch initially, but the expectation is that the next update will obsolete the patch unless there is a really compelling reason to deviate from the upstream.  This doesn't mean that you can't include support for SMF, RBAC, ...  It just means that we want something that doesn't require new patches at each update and ultimately, no patching at all would be preferred.  So again, leave the open source bits (docs in this case) alone unless there is a really compelling reason to deviate.


I don't want to see big javadoc patches in the SFW consolidation that
document detailed taxonomy information that we have to carry forever
because they will never be accepted into the upstream community.
Why would a FOSS project creating jar files even care about our
taxonomy rules?
They won't.

2. What if the man page simple documented the stability at the granularity of the jar file and
nothing else.  Perhaps the man page could generically reference the Javadoc?

Not every jar file in /usr/share/lib/java has a man page, but
that is the current practice, for the ones that do:

$ man asm
$ man mvel
$ man janino
$ man jettison
$ man joda-time
$ man jaxen-core
$ man junit
$ man ant (needs a more direct reference to javadoc)
...

As I see it, having jar file man pages...

1. Provides users stability and availability (taxonomy) information about jar file packages on Solaris/OpenSolaris not available anywhere
else.
2. Is pretty painless for project teams to produce and support.
3. Man pages do no harm, and I think users are already getting
use to having them. Some information is better than no information.
4. Until there is a better way, man pages should be required for
any new jar file submissions into Solaris/OpenSolaris. I thought
this was already true.
5. Man pages are used by most Solaris/OpenSolaris packages.
6. I appreciate where Java developers are coming from, but "not standard
practice for Java developers to look for man pages" alone, doesn't seem
enough reason to stop man pages being delivered with jar file packages.

We can't control how jar files are delivered or documented on
windows or other environments, but we can on Solaris/OpenSolaris.

BTW. ccing Norm (sfw c-team lead) since one of the requirements to
integrate into sfw is a man page.
The requirement has really been to provide documentation.  We have not forced folks to deliver man pages when the software they were delivering had it's own documentation.  If it comes with texinfo, javadoc, html, ... then we have let them deliver that documentation and not required a man page for everything.  If software was lacking documentation, we have asked for documentation that describes it, usually a man page.  The intent is to provide the documentation that is expected by the users of the software.

   -Norm




--
Michael Kearney
Staff Software Engineer

Sun Microsystems, Inc.
MS UBRM05-390, 500 Eldorado Blvd
Broomfield, CO 80021 US
Phone 303-272-2402
Fax 303-272-6554
Email Michael.Kearney@Sun.COM
--Boundary_(ID_6VDab7X4R6c8Jzx7vYgUeA) Content-type: text/x-vcard; CHARSET=US-ASCII; name=Michael_Kearney.vcf Content-transfer-encoding: 7BIT Content-disposition: attachment; filename=Michael_Kearney.vcf begin:vcard fn:Michael Kearney n:Kearney;Michael org:Sun Microsystems, Inc.;Archive Core Engineering adr:500 Eldorado Blvd.;;Mailstop UBRM05-390;Broomfield;CO;80021;US email;internet:Michael.Kearney@Sun.com title:Staff Software Engineer tel;work:303-272-2402 tel;fax:303-272-6554 x-mozilla-html:TRUE url:http://www.sun.com/ version:2.1 end:vcard --Boundary_(ID_6VDab7X4R6c8Jzx7vYgUeA)-- From Darren.Kenny@sun.com Tue May 19 09:12:34 2009 Received: from sunmail3mpk.sfbay.sun.com (sunmail3mpk.SFBay.Sun.COM [129.146.11.52]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4JGCXCH014603; Tue, 19 May 2009 09:12:33 -0700 (PDT) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by sunmail3mpk.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4JGCWQ8007943; Tue, 19 May 2009 09:12:33 -0700 (PDT) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJW00603FOWU700@nwk-avmta-2.sfbay.sun.com>; Tue, 19 May 2009 09:12:32 -0700 (PDT) Received: from gmp-eb-inf-2.sun.com ([192.18.6.24]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJW0039PFOTSY50@nwk-avmta-2.sfbay.sun.com>; Tue, 19 May 2009 09:12:30 -0700 (PDT) Received: from fe-emea-10.sun.com (gmp-eb-lb-1-fe3.eu.sun.com [192.18.6.10]) by gmp-eb-inf-2.sun.com (8.13.7+Sun/8.12.9) with ESMTP id n4JGCTCF025049; Tue, 19 May 2009 16:12:29 +0000 (GMT) Received: from conversion-daemon.fe-emea-10.sun.com by fe-emea-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJW00F00FMU0K00@fe-emea-10.sun.com>; Tue, 19 May 2009 17:12:29 +0100 (BST) Received: from [192.168.1.3] ([unknown] [86.42.214.40]) by fe-emea-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJW00FFMFNT0600@fe-emea-10.sun.com>; Tue, 19 May 2009 17:11:54 +0100 (BST) Date: Tue, 19 May 2009 17:11:51 +0100 From: Darren Kenny Subject: Re: jar file man pages - was Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] In-reply-to: <4A12D613.1080803@Sun.com> Sender: Darren.Kenny@sun.com To: Michael Kearney Cc: Norm Jacobs , James.Walker@sun.com, LSARC-ext@sun.com, PSARC-ext@sun.com Message-id: <4A12DA47.9080501@Sun.COM> MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1 Content-transfer-encoding: 8BIT X-PMX-Version: 5.4.1.325704 References: <4A09EB8D.6090800@sun.com> <4A09F80D.6080305@gmail.com> <10008ADD-B6FC-4D0F-85A1-5DD4393E4532@sun.com> <4A0AD25A.7070508@Sun.com> <4A0B11E3.90203@sun.com> <4A0C9FAE.8070504@Sun.COM> <4A12D613.1080803@Sun.com> User-Agent: Mozilla/5.0 (X11; U; SunOS i86pc; en-US; rv:1.9.1b5pre) Gecko/20090513 Lightning/1.0pre Shredder/3.0b3pre ThunderBrowse/3.2.4 Status: RO Content-Length: 5336 Could we not add something like a stability file to the META-INF directory in a JAR file then provide something (like extension in IDE, or CLI) to extract it? I was going to suggest adding it to the manifest, but it would seem to be more strict about the format of the file - while the directory META-INF would be more flexible. Just my 2˘, Darren. On 19/05/2009 16:53, Michael Kearney wrote: > I wouldn't want to see the Sun jar files have the @Taxonomy annotation and a > completely > different (or non-existent) method, such as a man page for FOSS jar files. > I'd like to see a single, consistent method and I think that's a short and > simple man page. > > -Michael > > Norm Jacobs wrote: >> Jim Walker wrote: >>> For LSARC, PSARC and the opinion writer(s) to consider.... >>> >>> Michael Kearney wrote: >>>> 1. Lloyd, I like the idea of your annotation but have a couple of concerns. >> >>>> - Would teams be expected to update third party, open source jar files with >>>> the annotation? >>>> - Would the ARC provide the common @Taxonomy annotation Java code? >> NO, NO, NO. We don't want to be in the business of patching this bit of Sun >> lore into source and or documentation delivered by existing open source >> projects. Largely, the projects are not going to be interested in this type of >> change. This should be handled by a separate mechanism that falls outside of >> that arena, perhap by the taxonomy(1) command. >>> >>> I have concerns too. >>> >>> In general, we will not be able to change FOSS code upstream like >>> this. We normally try to do as little modification as possible (ie. >>> just enough to get it to run well on Solaris/OpenSolaris). This >>> is another reason why short man pages are being tacked on. Is it >>> possible to tack on a page to the javadoc? >> >> Simply put, If we can leave the upstream bits alone, we should. If we have to >> make changes to make it build, install, or function properly then coordinate >> those changes with the upstream community. For SFW, it's ok to deliver them as >> a patch initially, but the expectation is that the next update will obsolete >> the patch unless there is a really compelling reason to deviate from the >> upstream. This doesn't mean that you can't include support for SMF, RBAC, ... >> It just means that we want something that doesn't require new patches at each >> update and ultimately, no patching at all would be preferred. So again, leave >> the open source bits (docs in this case) alone unless there is a really >> compelling reason to deviate. >> >>> >>> I don't want to see big javadoc patches in the SFW consolidation that >>> document detailed taxonomy information that we have to carry forever >>> because they will never be accepted into the upstream community. >>> Why would a FOSS project creating jar files even care about our >>> taxonomy rules? >> They won't. >> >>>> 2. What if the man page simple documented the stability at the granularity >>>> of the jar file and >>>> nothing else. Perhaps the man page could generically reference the Javadoc? >>> >>> Not every jar file in /usr/share/lib/java has a man page, but >>> that is the current practice, for the ones that do: >>> >>> $ man asm >>> $ man mvel >>> $ man janino >>> $ man jettison >>> $ man joda-time >>> $ man jaxen-core >>> $ man junit >>> $ man ant (needs a more direct reference to javadoc) >>> ... >>> >>> As I see it, having jar file man pages... >>> >>> 1. Provides users stability and availability (taxonomy) information about jar >>> file packages on Solaris/OpenSolaris not available anywhere >>> else. >>> 2. Is pretty painless for project teams to produce and support. >>> 3. Man pages do no harm, and I think users are already getting >>> use to having them. Some information is better than no information. >>> 4. Until there is a better way, man pages should be required for >>> any new jar file submissions into Solaris/OpenSolaris. I thought >>> this was already true. >>> 5. Man pages are used by most Solaris/OpenSolaris packages. >>> 6. I appreciate where Java developers are coming from, but "not standard >>> practice for Java developers to look for man pages" alone, doesn't seem >>> enough reason to stop man pages being delivered with jar file packages. >>> >>> We can't control how jar files are delivered or documented on >>> windows or other environments, but we can on Solaris/OpenSolaris. >>> >>> BTW. ccing Norm (sfw c-team lead) since one of the requirements to >>> integrate into sfw is a man page. >> The requirement has really been to provide documentation. We have not forced >> folks to deliver man pages when the software they were delivering had it's own >> documentation. If it comes with texinfo, javadoc, html, ... then we have let >> them deliver that documentation and not required a man page for everything. If >> software was lacking documentation, we have asked for documentation that >> describes it, usually a man page. The intent is to provide the documentation >> that is expected by the users of the software. >> >> -Norm >> >> >> > > -- > * Michael Kearney * > Staff Software Engineer > > *Sun Microsystems, Inc.* > MS UBRM05-390, 500 Eldorado Blvd > Broomfield, CO 80021 US > Phone 303-272-2402 > Fax 303-272-6554 > Email Michael.Kearney@Sun.COM > > From Darren.Kenny@sun.com Tue May 19 09:12:34 2009 Received: from sunmail3mpk.sfbay.sun.com (sunmail3mpk.SFBay.Sun.COM [129.146.11.52]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4JGCXCH014603; Tue, 19 May 2009 09:12:33 -0700 (PDT) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by sunmail3mpk.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4JGCWQ8007943; Tue, 19 May 2009 09:12:33 -0700 (PDT) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJW00603FOWU700@nwk-avmta-2.sfbay.sun.com>; Tue, 19 May 2009 09:12:32 -0700 (PDT) Received: from gmp-eb-inf-2.sun.com ([192.18.6.24]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJW0039PFOTSY50@nwk-avmta-2.sfbay.sun.com>; Tue, 19 May 2009 09:12:30 -0700 (PDT) Received: from fe-emea-10.sun.com (gmp-eb-lb-1-fe3.eu.sun.com [192.18.6.10]) by gmp-eb-inf-2.sun.com (8.13.7+Sun/8.12.9) with ESMTP id n4JGCTCF025049; Tue, 19 May 2009 16:12:29 +0000 (GMT) Received: from conversion-daemon.fe-emea-10.sun.com by fe-emea-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJW00F00FMU0K00@fe-emea-10.sun.com>; Tue, 19 May 2009 17:12:29 +0100 (BST) Received: from [192.168.1.3] ([unknown] [86.42.214.40]) by fe-emea-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJW00FFMFNT0600@fe-emea-10.sun.com>; Tue, 19 May 2009 17:11:54 +0100 (BST) Date: Tue, 19 May 2009 17:11:51 +0100 From: Darren Kenny Subject: Re: jar file man pages - was Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] In-reply-to: <4A12D613.1080803@Sun.com> Sender: Darren.Kenny@sun.com To: Michael Kearney Cc: Norm Jacobs , James.Walker@sun.com, LSARC-ext@sun.com, PSARC-ext@sun.com Message-id: <4A12DA47.9080501@Sun.COM> MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1 Content-transfer-encoding: 8BIT X-PMX-Version: 5.4.1.325704 References: <4A09EB8D.6090800@sun.com> <4A09F80D.6080305@gmail.com> <10008ADD-B6FC-4D0F-85A1-5DD4393E4532@sun.com> <4A0AD25A.7070508@Sun.com> <4A0B11E3.90203@sun.com> <4A0C9FAE.8070504@Sun.COM> <4A12D613.1080803@Sun.com> User-Agent: Mozilla/5.0 (X11; U; SunOS i86pc; en-US; rv:1.9.1b5pre) Gecko/20090513 Lightning/1.0pre Shredder/3.0b3pre ThunderBrowse/3.2.4 Status: RO Content-Length: 5336 Could we not add something like a stability file to the META-INF directory in a JAR file then provide something (like extension in IDE, or CLI) to extract it? I was going to suggest adding it to the manifest, but it would seem to be more strict about the format of the file - while the directory META-INF would be more flexible. Just my 2˘, Darren. On 19/05/2009 16:53, Michael Kearney wrote: > I wouldn't want to see the Sun jar files have the @Taxonomy annotation and a > completely > different (or non-existent) method, such as a man page for FOSS jar files. > I'd like to see a single, consistent method and I think that's a short and > simple man page. > > -Michael > > Norm Jacobs wrote: >> Jim Walker wrote: >>> For LSARC, PSARC and the opinion writer(s) to consider.... >>> >>> Michael Kearney wrote: >>>> 1. Lloyd, I like the idea of your annotation but have a couple of concerns. >> >>>> - Would teams be expected to update third party, open source jar files with >>>> the annotation? >>>> - Would the ARC provide the common @Taxonomy annotation Java code? >> NO, NO, NO. We don't want to be in the business of patching this bit of Sun >> lore into source and or documentation delivered by existing open source >> projects. Largely, the projects are not going to be interested in this type of >> change. This should be handled by a separate mechanism that falls outside of >> that arena, perhap by the taxonomy(1) command. >>> >>> I have concerns too. >>> >>> In general, we will not be able to change FOSS code upstream like >>> this. We normally try to do as little modification as possible (ie. >>> just enough to get it to run well on Solaris/OpenSolaris). This >>> is another reason why short man pages are being tacked on. Is it >>> possible to tack on a page to the javadoc? >> >> Simply put, If we can leave the upstream bits alone, we should. If we have to >> make changes to make it build, install, or function properly then coordinate >> those changes with the upstream community. For SFW, it's ok to deliver them as >> a patch initially, but the expectation is that the next update will obsolete >> the patch unless there is a really compelling reason to deviate from the >> upstream. This doesn't mean that you can't include support for SMF, RBAC, ... >> It just means that we want something that doesn't require new patches at each >> update and ultimately, no patching at all would be preferred. So again, leave >> the open source bits (docs in this case) alone unless there is a really >> compelling reason to deviate. >> >>> >>> I don't want to see big javadoc patches in the SFW consolidation that >>> document detailed taxonomy information that we have to carry forever >>> because they will never be accepted into the upstream community. >>> Why would a FOSS project creating jar files even care about our >>> taxonomy rules? >> They won't. >> >>>> 2. What if the man page simple documented the stability at the granularity >>>> of the jar file and >>>> nothing else. Perhaps the man page could generically reference the Javadoc? >>> >>> Not every jar file in /usr/share/lib/java has a man page, but >>> that is the current practice, for the ones that do: >>> >>> $ man asm >>> $ man mvel >>> $ man janino >>> $ man jettison >>> $ man joda-time >>> $ man jaxen-core >>> $ man junit >>> $ man ant (needs a more direct reference to javadoc) >>> ... >>> >>> As I see it, having jar file man pages... >>> >>> 1. Provides users stability and availability (taxonomy) information about jar >>> file packages on Solaris/OpenSolaris not available anywhere >>> else. >>> 2. Is pretty painless for project teams to produce and support. >>> 3. Man pages do no harm, and I think users are already getting >>> use to having them. Some information is better than no information. >>> 4. Until there is a better way, man pages should be required for >>> any new jar file submissions into Solaris/OpenSolaris. I thought >>> this was already true. >>> 5. Man pages are used by most Solaris/OpenSolaris packages. >>> 6. I appreciate where Java developers are coming from, but "not standard >>> practice for Java developers to look for man pages" alone, doesn't seem >>> enough reason to stop man pages being delivered with jar file packages. >>> >>> We can't control how jar files are delivered or documented on >>> windows or other environments, but we can on Solaris/OpenSolaris. >>> >>> BTW. ccing Norm (sfw c-team lead) since one of the requirements to >>> integrate into sfw is a man page. >> The requirement has really been to provide documentation. We have not forced >> folks to deliver man pages when the software they were delivering had it's own >> documentation. If it comes with texinfo, javadoc, html, ... then we have let >> them deliver that documentation and not required a man page for everything. If >> software was lacking documentation, we have asked for documentation that >> describes it, usually a man page. The intent is to provide the documentation >> that is expected by the users of the software. >> >> -Norm >> >> >> > > -- > * Michael Kearney * > Staff Software Engineer > > *Sun Microsystems, Inc.* > MS UBRM05-390, 500 Eldorado Blvd > Broomfield, CO 80021 US > Phone 303-272-2402 > Fax 303-272-6554 > Email Michael.Kearney@Sun.COM > > From Mark.Carlson@sun.com Tue May 19 09:26:37 2009 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4JGQaL5014909; Tue, 19 May 2009 09:26:36 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail5.uk.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n4JGQPnK005894; Tue, 19 May 2009 17:26:35 +0100 (BST) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJW0020BGCB7L00@nwk-avmta-1.sfbay.Sun.COM>; Tue, 19 May 2009 09:26:35 -0700 (PDT) Received: from brmea-mail-1.sun.com ([192.18.98.31]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJW00B3RGCAFUE0@nwk-avmta-1.sfbay.Sun.COM>; Tue, 19 May 2009 09:26:34 -0700 (PDT) Received: from fe-amer-10.sun.com ([192.18.109.80]) by brmea-mail-1.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n4JGQXfU013044; Tue, 19 May 2009 16:26:33 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJW00000EQU8900@mail-amer.sun.com>; Tue, 19 May 2009 10:26:33 -0600 (MDT) Received: from Macintosh-335.local ([unknown] [129.150.32.138]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJW00HAIGB2DEF0@mail-amer.sun.com>; Tue, 19 May 2009 10:25:51 -0600 (MDT) Date: Tue, 19 May 2009 10:25:49 -0600 From: "Mark A. Carlson" Subject: Re: jar file man pages - was Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] In-reply-to: <4A12CD90.5050603@Sun.COM> Sender: Mark.Carlson@sun.com To: Richard.Matthews@sun.com Cc: James.Walker@sun.com, Michael Kearney , LSARC-ext@sun.com, Norm Jacobs , PSARC-ext@sun.com Message-id: <4A12DD8D.9030802@sun.com> MIME-version: 1.0 Content-type: multipart/alternative; boundary="Boundary_(ID_6MWPGCQrbEdeTEXnLm5iWw)" X-PMX-Version: 5.4.1.325704 References: <4A09EB8D.6090800@sun.com> <4A09F80D.6080305@gmail.com> <10008ADD-B6FC-4D0F-85A1-5DD4393E4532@sun.com> <4A0AD25A.7070508@Sun.com> <4A0B11E3.90203@sun.com> <4A12CD90.5050603@Sun.COM> User-Agent: Thunderbird 2.0.0.21 (Macintosh/20090302) Status: RO Content-Length: 13386 This is a multi-part message in MIME format. --Boundary_(ID_6MWPGCQrbEdeTEXnLm5iWw) Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT Let's keep in mind that we are trying to document (in an easily accessible place) the interface classification of the OpenSolaris instance (not the Java interface across platforms). Given that we need to do this without massive patches to the upstream code, and that Java projects should use whatever native mechanism exists to document the classification across platforms, the OpenSolaris man page seems to be the best place. -- mark Rick Matthews wrote: > I agree in principle with Jim's points. In particular, >> 1. Provides users stability and availability (taxonomy) information >> about jar file packages on Solaris/OpenSolaris not available anywhere >> else. > If ARCs are going to require this information, it should be documented > somewhere that a user > can find it a normal operating environment. Currently, I'd have to > agree this is man pages. > > I think a further point of this discussion is a need for ARCs to adopt > a consistent means of > doing so, and stick to it. In several of the cited cases with man > pages, the man pages were > produced as part of the Fast Track process. In the case of > LSARC/2009/262, it was questioned > why we would have man pages for jar/java release vehicles. That is > inconsistent, which is why > I believe Jim raised the issue. > > Toward that end, issues continue to be raised with jar/java FOSS > projects. There doesn't seem > to be a "checklist" of items needed for a FOSS jar project (and of > course, many checklists are > incomplete). As I recall, the following issues resulted from FOSS > cases delivering jar s: > 1) How to deliver javadocs to OpenSolaris (mostly due to web site > volume issues) > 2) Man pages for stability and taxonomy > 3) What portions need to have declared stability, etc. (like > package name) > 4) What JDK version(s)? > 5) Versioning of jar files > > Mark Martin brought up number 5 quite awhile ago. There was no further > action taken. > The jar files really seem to parallel C libraries, and should have a > best practice for versioning > similar to (or maybe expanded) "Library and Shared Object Requirements". > > IMHO, man page declaration of stability and taxonomy works. Let's keep > that until there > is a suitable "better way". Lloyd's method of documenting is a good > start, but we can't > hope to force external communities to use such a method, except by > general acceptance. > We could make it a best practice for non-FOSS jar deliverables that > are being ARCed. > This assumes Lloyd's proposal is sound, which I don't feel qualified > to have opinion. > > I think the ARCs need to look into these issues (as is being done), > and reasonable methods/ > practices be established, and then those be consistently applied. > -- > Rick > > On 05/13/09 13:30, Jim Walker wrote: >> For LSARC, PSARC and the opinion writer(s) to consider.... >> >> Michael Kearney wrote: >>> 1. Lloyd, I like the idea of your annotation but have a couple of >>> concerns. - Would teams be expected to update third party, open >>> source jar files with the annotation? >>> - Would the ARC provide the common @Taxonomy annotation Java code? >> >> I have concerns too. >> >> In general, we will not be able to change FOSS code upstream like >> this. We normally try to do as little modification as possible (ie. >> just enough to get it to run well on Solaris/OpenSolaris). This >> is another reason why short man pages are being tacked on. Is it >> possible to tack on a page to the javadoc? >> >> I don't want to see big javadoc patches in the SFW consolidation that >> document detailed taxonomy information that we have to carry forever >> because they will never be accepted into the upstream community. >> Why would a FOSS project creating jar files even care about our >> taxonomy rules? >> >>> 2. What if the man page simple documented the stability at the >>> granularity of the jar file and >>> nothing else. Perhaps the man page could generically reference the >>> Javadoc? >> >> Not every jar file in /usr/share/lib/java has a man page, but >> that is the current practice, for the ones that do: >> >> $ man asm >> $ man mvel >> $ man janino >> $ man jettison >> $ man joda-time >> $ man jaxen-core >> $ man junit >> $ man ant (needs a more direct reference to javadoc) >> ... >> >> As I see it, having jar file man pages... >> >> 1. Provides users stability and availability (taxonomy) information >> about jar file packages on Solaris/OpenSolaris not available anywhere >> else. >> 2. Is pretty painless for project teams to produce and support. >> 3. Man pages do no harm, and I think users are already getting >> use to having them. Some information is better than no information. >> 4. Until there is a better way, man pages should be required for >> any new jar file submissions into Solaris/OpenSolaris. I thought >> this was already true. >> 5. Man pages are used by most Solaris/OpenSolaris packages. >> 6. I appreciate where Java developers are coming from, but "not standard >> practice for Java developers to look for man pages" alone, doesn't seem >> enough reason to stop man pages being delivered with jar file packages. >> >> We can't control how jar files are delivered or documented on >> windows or other environments, but we can on Solaris/OpenSolaris. >> >> BTW. ccing Norm (sfw c-team lead) since one of the requirements to >> integrate into sfw is a man page. >> >> Cheers, >> Jim > > -- * Mark A. Carlson * Sr. Architect *Systems Group* Phone x69559 / 303-223-6139 Email Mark.Carlson@Sun.COM --Boundary_(ID_6MWPGCQrbEdeTEXnLm5iWw) Content-type: text/html; CHARSET=US-ASCII Content-transfer-encoding: 7BIT Let's keep in mind that we are trying to document (in an easily accessible place) the
interface classification of the OpenSolaris instance (not the Java interface across platforms).
Given that we need to do this without massive patches to the upstream code, and that
Java projects should use whatever native mechanism exists to document the classification
across platforms, the OpenSolaris man page seems to be the best place.

-- mark

Rick Matthews wrote:
I agree in principle with Jim's points. In particular,
1. Provides users stability and availability (taxonomy) information about jar file packages on Solaris/OpenSolaris not available anywhere
else.
If ARCs are going to require this information, it should be documented somewhere that a user
can find it a normal operating environment. Currently, I'd have to agree this is man pages.

I think a further point of this discussion is a need for ARCs to adopt a consistent means of
doing so, and stick to it. In several of the cited cases with man pages, the man pages were
produced as part of the Fast Track process. In the case of LSARC/2009/262, it was questioned
why we would have man pages for jar/java release vehicles. That is inconsistent, which is why
I believe Jim raised the issue.

Toward that end, issues continue to be raised with jar/java FOSS projects. There doesn't seem
to be a "checklist" of items needed for a FOSS jar project (and of course, many checklists are
incomplete). As I recall, the following issues resulted from FOSS cases delivering jar s:
   1) How to deliver javadocs to OpenSolaris (mostly due to web site volume issues)
   2) Man pages for stability and taxonomy
   3) What portions need to have declared stability, etc. (like package name)
   4) What JDK version(s)?
   5) Versioning of jar files

Mark Martin brought up number 5 quite awhile ago. There was no further action taken.
The jar files really seem to parallel C libraries, and should have a best practice for versioning
similar to (or maybe expanded) "Library and Shared Object Requirements".

IMHO, man page declaration of stability and taxonomy works. Let's keep that until there
is a suitable "better way". Lloyd's method of documenting is a good start, but we can't
hope to force external communities to use such a method, except by general acceptance.
We could make it a best practice for non-FOSS jar deliverables that are being ARCed.
This assumes Lloyd's proposal is sound, which I don't feel qualified to have opinion.

I think the ARCs need to look into these issues (as is being done), and reasonable methods/
practices be established, and then those be consistently applied.
--
Rick

On 05/13/09 13:30, Jim Walker wrote:
For LSARC, PSARC and the opinion writer(s) to consider....

Michael Kearney wrote:
1. Lloyd, I like the idea of your annotation but have a couple of concerns.     - Would teams be expected to update third party, open source jar files with the annotation?
    - Would the ARC provide the common @Taxonomy annotation Java code?

I have concerns too.

In general, we will not be able to change FOSS code upstream like
this. We normally try to do as little modification as possible (ie.
just enough to get it to run well on Solaris/OpenSolaris). This
is another reason why short man pages are being tacked on. Is it
possible to tack on a page to the javadoc?

I don't want to see big javadoc patches in the SFW consolidation that
document detailed taxonomy information that we have to carry forever
because they will never be accepted into the upstream community.
Why would a FOSS project creating jar files even care about our
taxonomy rules?

2. What if the man page simple documented the stability at the granularity of the jar file and
nothing else.  Perhaps the man page could generically reference the Javadoc?

Not every jar file in /usr/share/lib/java has a man page, but
that is the current practice, for the ones that do:

$ man asm
$ man mvel
$ man janino
$ man jettison
$ man joda-time
$ man jaxen-core
$ man junit
$ man ant (needs a more direct reference to javadoc)
...

As I see it, having jar file man pages...

1. Provides users stability and availability (taxonomy) information about jar file packages on Solaris/OpenSolaris not available anywhere
else.
2. Is pretty painless for project teams to produce and support.
3. Man pages do no harm, and I think users are already getting
use to having them. Some information is better than no information.
4. Until there is a better way, man pages should be required for
any new jar file submissions into Solaris/OpenSolaris. I thought
this was already true.
5. Man pages are used by most Solaris/OpenSolaris packages.
6. I appreciate where Java developers are coming from, but "not standard
practice for Java developers to look for man pages" alone, doesn't seem
enough reason to stop man pages being delivered with jar file packages.

We can't control how jar files are delivered or documented on
windows or other environments, but we can on Solaris/OpenSolaris.

BTW. ccing Norm (sfw c-team lead) since one of the requirements to
integrate into sfw is a man page.

Cheers,
Jim



--
Mark A. Carlson
Sr. Architect

Systems Group
Phone x69559 / 303-223-6139
Email Mark.Carlson@Sun.COM

--Boundary_(ID_6MWPGCQrbEdeTEXnLm5iWw)-- From Mark.Carlson@sun.com Tue May 19 09:26:37 2009 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4JGQaL5014909; Tue, 19 May 2009 09:26:36 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail5.uk.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n4JGQPnK005894; Tue, 19 May 2009 17:26:35 +0100 (BST) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJW0020BGCB7L00@nwk-avmta-1.sfbay.Sun.COM>; Tue, 19 May 2009 09:26:35 -0700 (PDT) Received: from brmea-mail-1.sun.com ([192.18.98.31]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJW00B3RGCAFUE0@nwk-avmta-1.sfbay.Sun.COM>; Tue, 19 May 2009 09:26:34 -0700 (PDT) Received: from fe-amer-10.sun.com ([192.18.109.80]) by brmea-mail-1.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n4JGQXfU013044; Tue, 19 May 2009 16:26:33 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJW00000EQU8900@mail-amer.sun.com>; Tue, 19 May 2009 10:26:33 -0600 (MDT) Received: from Macintosh-335.local ([unknown] [129.150.32.138]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJW00HAIGB2DEF0@mail-amer.sun.com>; Tue, 19 May 2009 10:25:51 -0600 (MDT) Date: Tue, 19 May 2009 10:25:49 -0600 From: "Mark A. Carlson" Subject: Re: jar file man pages - was Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] In-reply-to: <4A12CD90.5050603@Sun.COM> Sender: Mark.Carlson@sun.com To: Richard.Matthews@sun.com Cc: James.Walker@sun.com, Michael Kearney , LSARC-ext@sun.com, Norm Jacobs , PSARC-ext@sun.com Message-id: <4A12DD8D.9030802@sun.com> MIME-version: 1.0 Content-type: multipart/alternative; boundary="Boundary_(ID_6MWPGCQrbEdeTEXnLm5iWw)" X-PMX-Version: 5.4.1.325704 References: <4A09EB8D.6090800@sun.com> <4A09F80D.6080305@gmail.com> <10008ADD-B6FC-4D0F-85A1-5DD4393E4532@sun.com> <4A0AD25A.7070508@Sun.com> <4A0B11E3.90203@sun.com> <4A12CD90.5050603@Sun.COM> User-Agent: Thunderbird 2.0.0.21 (Macintosh/20090302) Status: RO Content-Length: 13386 This is a multi-part message in MIME format. --Boundary_(ID_6MWPGCQrbEdeTEXnLm5iWw) Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT Let's keep in mind that we are trying to document (in an easily accessible place) the interface classification of the OpenSolaris instance (not the Java interface across platforms). Given that we need to do this without massive patches to the upstream code, and that Java projects should use whatever native mechanism exists to document the classification across platforms, the OpenSolaris man page seems to be the best place. -- mark Rick Matthews wrote: > I agree in principle with Jim's points. In particular, >> 1. Provides users stability and availability (taxonomy) information >> about jar file packages on Solaris/OpenSolaris not available anywhere >> else. > If ARCs are going to require this information, it should be documented > somewhere that a user > can find it a normal operating environment. Currently, I'd have to > agree this is man pages. > > I think a further point of this discussion is a need for ARCs to adopt > a consistent means of > doing so, and stick to it. In several of the cited cases with man > pages, the man pages were > produced as part of the Fast Track process. In the case of > LSARC/2009/262, it was questioned > why we would have man pages for jar/java release vehicles. That is > inconsistent, which is why > I believe Jim raised the issue. > > Toward that end, issues continue to be raised with jar/java FOSS > projects. There doesn't seem > to be a "checklist" of items needed for a FOSS jar project (and of > course, many checklists are > incomplete). As I recall, the following issues resulted from FOSS > cases delivering jar s: > 1) How to deliver javadocs to OpenSolaris (mostly due to web site > volume issues) > 2) Man pages for stability and taxonomy > 3) What portions need to have declared stability, etc. (like > package name) > 4) What JDK version(s)? > 5) Versioning of jar files > > Mark Martin brought up number 5 quite awhile ago. There was no further > action taken. > The jar files really seem to parallel C libraries, and should have a > best practice for versioning > similar to (or maybe expanded) "Library and Shared Object Requirements". > > IMHO, man page declaration of stability and taxonomy works. Let's keep > that until there > is a suitable "better way". Lloyd's method of documenting is a good > start, but we can't > hope to force external communities to use such a method, except by > general acceptance. > We could make it a best practice for non-FOSS jar deliverables that > are being ARCed. > This assumes Lloyd's proposal is sound, which I don't feel qualified > to have opinion. > > I think the ARCs need to look into these issues (as is being done), > and reasonable methods/ > practices be established, and then those be consistently applied. > -- > Rick > > On 05/13/09 13:30, Jim Walker wrote: >> For LSARC, PSARC and the opinion writer(s) to consider.... >> >> Michael Kearney wrote: >>> 1. Lloyd, I like the idea of your annotation but have a couple of >>> concerns. - Would teams be expected to update third party, open >>> source jar files with the annotation? >>> - Would the ARC provide the common @Taxonomy annotation Java code? >> >> I have concerns too. >> >> In general, we will not be able to change FOSS code upstream like >> this. We normally try to do as little modification as possible (ie. >> just enough to get it to run well on Solaris/OpenSolaris). This >> is another reason why short man pages are being tacked on. Is it >> possible to tack on a page to the javadoc? >> >> I don't want to see big javadoc patches in the SFW consolidation that >> document detailed taxonomy information that we have to carry forever >> because they will never be accepted into the upstream community. >> Why would a FOSS project creating jar files even care about our >> taxonomy rules? >> >>> 2. What if the man page simple documented the stability at the >>> granularity of the jar file and >>> nothing else. Perhaps the man page could generically reference the >>> Javadoc? >> >> Not every jar file in /usr/share/lib/java has a man page, but >> that is the current practice, for the ones that do: >> >> $ man asm >> $ man mvel >> $ man janino >> $ man jettison >> $ man joda-time >> $ man jaxen-core >> $ man junit >> $ man ant (needs a more direct reference to javadoc) >> ... >> >> As I see it, having jar file man pages... >> >> 1. Provides users stability and availability (taxonomy) information >> about jar file packages on Solaris/OpenSolaris not available anywhere >> else. >> 2. Is pretty painless for project teams to produce and support. >> 3. Man pages do no harm, and I think users are already getting >> use to having them. Some information is better than no information. >> 4. Until there is a better way, man pages should be required for >> any new jar file submissions into Solaris/OpenSolaris. I thought >> this was already true. >> 5. Man pages are used by most Solaris/OpenSolaris packages. >> 6. I appreciate where Java developers are coming from, but "not standard >> practice for Java developers to look for man pages" alone, doesn't seem >> enough reason to stop man pages being delivered with jar file packages. >> >> We can't control how jar files are delivered or documented on >> windows or other environments, but we can on Solaris/OpenSolaris. >> >> BTW. ccing Norm (sfw c-team lead) since one of the requirements to >> integrate into sfw is a man page. >> >> Cheers, >> Jim > > -- * Mark A. Carlson * Sr. Architect *Systems Group* Phone x69559 / 303-223-6139 Email Mark.Carlson@Sun.COM --Boundary_(ID_6MWPGCQrbEdeTEXnLm5iWw) Content-type: text/html; CHARSET=US-ASCII Content-transfer-encoding: 7BIT Let's keep in mind that we are trying to document (in an easily accessible place) the
interface classification of the OpenSolaris instance (not the Java interface across platforms).
Given that we need to do this without massive patches to the upstream code, and that
Java projects should use whatever native mechanism exists to document the classification
across platforms, the OpenSolaris man page seems to be the best place.

-- mark

Rick Matthews wrote:
I agree in principle with Jim's points. In particular,
1. Provides users stability and availability (taxonomy) information about jar file packages on Solaris/OpenSolaris not available anywhere
else.
If ARCs are going to require this information, it should be documented somewhere that a user
can find it a normal operating environment. Currently, I'd have to agree this is man pages.

I think a further point of this discussion is a need for ARCs to adopt a consistent means of
doing so, and stick to it. In several of the cited cases with man pages, the man pages were
produced as part of the Fast Track process. In the case of LSARC/2009/262, it was questioned
why we would have man pages for jar/java release vehicles. That is inconsistent, which is why
I believe Jim raised the issue.

Toward that end, issues continue to be raised with jar/java FOSS projects. There doesn't seem
to be a "checklist" of items needed for a FOSS jar project (and of course, many checklists are
incomplete). As I recall, the following issues resulted from FOSS cases delivering jar s:
   1) How to deliver javadocs to OpenSolaris (mostly due to web site volume issues)
   2) Man pages for stability and taxonomy
   3) What portions need to have declared stability, etc. (like package name)
   4) What JDK version(s)?
   5) Versioning of jar files

Mark Martin brought up number 5 quite awhile ago. There was no further action taken.
The jar files really seem to parallel C libraries, and should have a best practice for versioning
similar to (or maybe expanded) "Library and Shared Object Requirements".

IMHO, man page declaration of stability and taxonomy works. Let's keep that until there
is a suitable "better way". Lloyd's method of documenting is a good start, but we can't
hope to force external communities to use such a method, except by general acceptance.
We could make it a best practice for non-FOSS jar deliverables that are being ARCed.
This assumes Lloyd's proposal is sound, which I don't feel qualified to have opinion.

I think the ARCs need to look into these issues (as is being done), and reasonable methods/
practices be established, and then those be consistently applied.
--
Rick

On 05/13/09 13:30, Jim Walker wrote:
For LSARC, PSARC and the opinion writer(s) to consider....

Michael Kearney wrote:
1. Lloyd, I like the idea of your annotation but have a couple of concerns.     - Would teams be expected to update third party, open source jar files with the annotation?
    - Would the ARC provide the common @Taxonomy annotation Java code?

I have concerns too.

In general, we will not be able to change FOSS code upstream like
this. We normally try to do as little modification as possible (ie.
just enough to get it to run well on Solaris/OpenSolaris). This
is another reason why short man pages are being tacked on. Is it
possible to tack on a page to the javadoc?

I don't want to see big javadoc patches in the SFW consolidation that
document detailed taxonomy information that we have to carry forever
because they will never be accepted into the upstream community.
Why would a FOSS project creating jar files even care about our
taxonomy rules?

2. What if the man page simple documented the stability at the granularity of the jar file and
nothing else.  Perhaps the man page could generically reference the Javadoc?

Not every jar file in /usr/share/lib/java has a man page, but
that is the current practice, for the ones that do:

$ man asm
$ man mvel
$ man janino
$ man jettison
$ man joda-time
$ man jaxen-core
$ man junit
$ man ant (needs a more direct reference to javadoc)
...

As I see it, having jar file man pages...

1. Provides users stability and availability (taxonomy) information about jar file packages on Solaris/OpenSolaris not available anywhere
else.
2. Is pretty painless for project teams to produce and support.
3. Man pages do no harm, and I think users are already getting
use to having them. Some information is better than no information.
4. Until there is a better way, man pages should be required for
any new jar file submissions into Solaris/OpenSolaris. I thought
this was already true.
5. Man pages are used by most Solaris/OpenSolaris packages.
6. I appreciate where Java developers are coming from, but "not standard
practice for Java developers to look for man pages" alone, doesn't seem
enough reason to stop man pages being delivered with jar file packages.

We can't control how jar files are delivered or documented on
windows or other environments, but we can on Solaris/OpenSolaris.

BTW. ccing Norm (sfw c-team lead) since one of the requirements to
integrate into sfw is a man page.

Cheers,
Jim



--
Mark A. Carlson
Sr. Architect

Systems Group
Phone x69559 / 303-223-6139
Email Mark.Carlson@Sun.COM

--Boundary_(ID_6MWPGCQrbEdeTEXnLm5iWw)-- From gdamore@sun.com Tue May 19 09:38:34 2009 Received: from newsunmail1brm.central.sun.com (newsunmail1brm.Central.Sun.COM [129.147.62.245]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4JGcYjW015168; Tue, 19 May 2009 09:38:34 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by newsunmail1brm.central.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4JGcXfI055526; Tue, 19 May 2009 10:38:34 -0600 (MDT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJW00109GW9OZ00@brm-avmta-1.central.sun.com>; Tue, 19 May 2009 10:38:33 -0600 (MDT) Received: from sca-es-mail-1.sun.com ([192.18.43.132]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJW00D08GW89IC0@brm-avmta-1.central.sun.com>; Tue, 19 May 2009 10:38:32 -0600 (MDT) Received: from fe-sfbay-10.sun.com ([192.18.43.129]) by sca-es-mail-1.sun.com (8.13.7+Sun/8.12.9) with ESMTP id n4JGcW8C014663; Tue, 19 May 2009 09:38:32 -0700 (PDT) Received: from conversion-daemon.fe-sfbay-10.sun.com by fe-sfbay-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJW00M00GNRQG00@fe-sfbay-10.sun.com>; Tue, 19 May 2009 09:38:32 -0700 (PDT) Received: from [192.168.251.11] ([unknown] [76.93.15.33]) by fe-sfbay-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJW00C90GVZGXC0@fe-sfbay-10.sun.com>; Tue, 19 May 2009 09:38:23 -0700 (PDT) Date: Tue, 19 May 2009 09:38:22 -0700 From: "Garrett D'Amore" Subject: Re: jar file man pages - was Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] In-reply-to: <4A12DD8D.9030802@sun.com> Sender: Garrett.Damore@sun.com To: "Mark A. Carlson" Cc: Richard.Matthews@sun.com, James.Walker@sun.com, Michael Kearney , LSARC-ext@sun.com, Norm Jacobs , PSARC-ext@sun.com Message-id: <4A12E07E.7020802@sun.com> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <4A09EB8D.6090800@sun.com> <4A09F80D.6080305@gmail.com> <10008ADD-B6FC-4D0F-85A1-5DD4393E4532@sun.com> <4A0AD25A.7070508@Sun.com> <4A0B11E3.90203@sun.com> <4A12CD90.5050603@Sun.COM> <4A12DD8D.9030802@sun.com> User-Agent: Thunderbird 2.0.0.18 (X11/20081201) Status: RO Content-Length: 6165 Mark A. Carlson wrote: > Let's keep in mind that we are trying to document (in an easily > accessible place) the > interface classification of the OpenSolaris instance (not the Java > interface across platforms). > Given that we need to do this without massive patches to the upstream > code, and that > Java projects should use whatever native mechanism exists to document > the classification > across platforms, the OpenSolaris man page seems to be the best place. I remain unconvinced that we (OpenSolaris) should even be concerned about stability of Java APIs upon OpenSolaris. (With the possible exception of APIs that are designed specifically to *support* OpenSolaris itself.) Do other members see value in having another layer of commitment and review beyond whatever is already done as part of the Java community? - Garrett > > -- mark > > Rick Matthews wrote: >> I agree in principle with Jim's points. In particular, >>> 1. Provides users stability and availability (taxonomy) information >>> about jar file packages on Solaris/OpenSolaris not available anywhere >>> else. >> If ARCs are going to require this information, it should be >> documented somewhere that a user >> can find it a normal operating environment. Currently, I'd have to >> agree this is man pages. >> >> I think a further point of this discussion is a need for ARCs to >> adopt a consistent means of >> doing so, and stick to it. In several of the cited cases with man >> pages, the man pages were >> produced as part of the Fast Track process. In the case of >> LSARC/2009/262, it was questioned >> why we would have man pages for jar/java release vehicles. That is >> inconsistent, which is why >> I believe Jim raised the issue. >> >> Toward that end, issues continue to be raised with jar/java FOSS >> projects. There doesn't seem >> to be a "checklist" of items needed for a FOSS jar project (and of >> course, many checklists are >> incomplete). As I recall, the following issues resulted from FOSS >> cases delivering jar s: >> 1) How to deliver javadocs to OpenSolaris (mostly due to web site >> volume issues) >> 2) Man pages for stability and taxonomy >> 3) What portions need to have declared stability, etc. (like >> package name) >> 4) What JDK version(s)? >> 5) Versioning of jar files >> >> Mark Martin brought up number 5 quite awhile ago. There was no >> further action taken. >> The jar files really seem to parallel C libraries, and should have a >> best practice for versioning >> similar to (or maybe expanded) "Library and Shared Object Requirements". >> >> IMHO, man page declaration of stability and taxonomy works. Let's >> keep that until there >> is a suitable "better way". Lloyd's method of documenting is a good >> start, but we can't >> hope to force external communities to use such a method, except by >> general acceptance. >> We could make it a best practice for non-FOSS jar deliverables that >> are being ARCed. >> This assumes Lloyd's proposal is sound, which I don't feel qualified >> to have opinion. >> >> I think the ARCs need to look into these issues (as is being done), >> and reasonable methods/ >> practices be established, and then those be consistently applied. >> -- >> Rick >> >> On 05/13/09 13:30, Jim Walker wrote: >>> For LSARC, PSARC and the opinion writer(s) to consider.... >>> >>> Michael Kearney wrote: >>>> 1. Lloyd, I like the idea of your annotation but have a couple of >>>> concerns. - Would teams be expected to update third party, open >>>> source jar files with the annotation? >>>> - Would the ARC provide the common @Taxonomy annotation Java code? >>> >>> I have concerns too. >>> >>> In general, we will not be able to change FOSS code upstream like >>> this. We normally try to do as little modification as possible (ie. >>> just enough to get it to run well on Solaris/OpenSolaris). This >>> is another reason why short man pages are being tacked on. Is it >>> possible to tack on a page to the javadoc? >>> >>> I don't want to see big javadoc patches in the SFW consolidation that >>> document detailed taxonomy information that we have to carry forever >>> because they will never be accepted into the upstream community. >>> Why would a FOSS project creating jar files even care about our >>> taxonomy rules? >>> >>>> 2. What if the man page simple documented the stability at the >>>> granularity of the jar file and >>>> nothing else. Perhaps the man page could generically reference the >>>> Javadoc? >>> >>> Not every jar file in /usr/share/lib/java has a man page, but >>> that is the current practice, for the ones that do: >>> >>> $ man asm >>> $ man mvel >>> $ man janino >>> $ man jettison >>> $ man joda-time >>> $ man jaxen-core >>> $ man junit >>> $ man ant (needs a more direct reference to javadoc) >>> ... >>> >>> As I see it, having jar file man pages... >>> >>> 1. Provides users stability and availability (taxonomy) information >>> about jar file packages on Solaris/OpenSolaris not available anywhere >>> else. >>> 2. Is pretty painless for project teams to produce and support. >>> 3. Man pages do no harm, and I think users are already getting >>> use to having them. Some information is better than no information. >>> 4. Until there is a better way, man pages should be required for >>> any new jar file submissions into Solaris/OpenSolaris. I thought >>> this was already true. >>> 5. Man pages are used by most Solaris/OpenSolaris packages. >>> 6. I appreciate where Java developers are coming from, but "not >>> standard >>> practice for Java developers to look for man pages" alone, doesn't seem >>> enough reason to stop man pages being delivered with jar file packages. >>> >>> We can't control how jar files are delivered or documented on >>> windows or other environments, but we can on Solaris/OpenSolaris. >>> >>> BTW. ccing Norm (sfw c-team lead) since one of the requirements to >>> integrate into sfw is a man page. >>> >>> Cheers, >>> Jim >> >> > > -- > * Mark A. Carlson * > Sr. Architect > > *Systems Group* > Phone x69559 / 303-223-6139 > Email Mark.Carlson@Sun.COM > > > From gdamore@sun.com Tue May 19 09:38:34 2009 Received: from newsunmail1brm.central.sun.com (newsunmail1brm.Central.Sun.COM [129.147.62.245]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4JGcYjW015168; Tue, 19 May 2009 09:38:34 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by newsunmail1brm.central.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4JGcXfI055526; Tue, 19 May 2009 10:38:34 -0600 (MDT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJW00109GW9OZ00@brm-avmta-1.central.sun.com>; Tue, 19 May 2009 10:38:33 -0600 (MDT) Received: from sca-es-mail-1.sun.com ([192.18.43.132]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJW00D08GW89IC0@brm-avmta-1.central.sun.com>; Tue, 19 May 2009 10:38:32 -0600 (MDT) Received: from fe-sfbay-10.sun.com ([192.18.43.129]) by sca-es-mail-1.sun.com (8.13.7+Sun/8.12.9) with ESMTP id n4JGcW8C014663; Tue, 19 May 2009 09:38:32 -0700 (PDT) Received: from conversion-daemon.fe-sfbay-10.sun.com by fe-sfbay-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJW00M00GNRQG00@fe-sfbay-10.sun.com>; Tue, 19 May 2009 09:38:32 -0700 (PDT) Received: from [192.168.251.11] ([unknown] [76.93.15.33]) by fe-sfbay-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJW00C90GVZGXC0@fe-sfbay-10.sun.com>; Tue, 19 May 2009 09:38:23 -0700 (PDT) Date: Tue, 19 May 2009 09:38:22 -0700 From: "Garrett D'Amore" Subject: Re: jar file man pages - was Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] In-reply-to: <4A12DD8D.9030802@sun.com> Sender: Garrett.Damore@sun.com To: "Mark A. Carlson" Cc: Richard.Matthews@sun.com, James.Walker@sun.com, Michael Kearney , LSARC-ext@sun.com, Norm Jacobs , PSARC-ext@sun.com Message-id: <4A12E07E.7020802@sun.com> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <4A09EB8D.6090800@sun.com> <4A09F80D.6080305@gmail.com> <10008ADD-B6FC-4D0F-85A1-5DD4393E4532@sun.com> <4A0AD25A.7070508@Sun.com> <4A0B11E3.90203@sun.com> <4A12CD90.5050603@Sun.COM> <4A12DD8D.9030802@sun.com> User-Agent: Thunderbird 2.0.0.18 (X11/20081201) Status: RO Content-Length: 6165 Mark A. Carlson wrote: > Let's keep in mind that we are trying to document (in an easily > accessible place) the > interface classification of the OpenSolaris instance (not the Java > interface across platforms). > Given that we need to do this without massive patches to the upstream > code, and that > Java projects should use whatever native mechanism exists to document > the classification > across platforms, the OpenSolaris man page seems to be the best place. I remain unconvinced that we (OpenSolaris) should even be concerned about stability of Java APIs upon OpenSolaris. (With the possible exception of APIs that are designed specifically to *support* OpenSolaris itself.) Do other members see value in having another layer of commitment and review beyond whatever is already done as part of the Java community? - Garrett > > -- mark > > Rick Matthews wrote: >> I agree in principle with Jim's points. In particular, >>> 1. Provides users stability and availability (taxonomy) information >>> about jar file packages on Solaris/OpenSolaris not available anywhere >>> else. >> If ARCs are going to require this information, it should be >> documented somewhere that a user >> can find it a normal operating environment. Currently, I'd have to >> agree this is man pages. >> >> I think a further point of this discussion is a need for ARCs to >> adopt a consistent means of >> doing so, and stick to it. In several of the cited cases with man >> pages, the man pages were >> produced as part of the Fast Track process. In the case of >> LSARC/2009/262, it was questioned >> why we would have man pages for jar/java release vehicles. That is >> inconsistent, which is why >> I believe Jim raised the issue. >> >> Toward that end, issues continue to be raised with jar/java FOSS >> projects. There doesn't seem >> to be a "checklist" of items needed for a FOSS jar project (and of >> course, many checklists are >> incomplete). As I recall, the following issues resulted from FOSS >> cases delivering jar s: >> 1) How to deliver javadocs to OpenSolaris (mostly due to web site >> volume issues) >> 2) Man pages for stability and taxonomy >> 3) What portions need to have declared stability, etc. (like >> package name) >> 4) What JDK version(s)? >> 5) Versioning of jar files >> >> Mark Martin brought up number 5 quite awhile ago. There was no >> further action taken. >> The jar files really seem to parallel C libraries, and should have a >> best practice for versioning >> similar to (or maybe expanded) "Library and Shared Object Requirements". >> >> IMHO, man page declaration of stability and taxonomy works. Let's >> keep that until there >> is a suitable "better way". Lloyd's method of documenting is a good >> start, but we can't >> hope to force external communities to use such a method, except by >> general acceptance. >> We could make it a best practice for non-FOSS jar deliverables that >> are being ARCed. >> This assumes Lloyd's proposal is sound, which I don't feel qualified >> to have opinion. >> >> I think the ARCs need to look into these issues (as is being done), >> and reasonable methods/ >> practices be established, and then those be consistently applied. >> -- >> Rick >> >> On 05/13/09 13:30, Jim Walker wrote: >>> For LSARC, PSARC and the opinion writer(s) to consider.... >>> >>> Michael Kearney wrote: >>>> 1. Lloyd, I like the idea of your annotation but have a couple of >>>> concerns. - Would teams be expected to update third party, open >>>> source jar files with the annotation? >>>> - Would the ARC provide the common @Taxonomy annotation Java code? >>> >>> I have concerns too. >>> >>> In general, we will not be able to change FOSS code upstream like >>> this. We normally try to do as little modification as possible (ie. >>> just enough to get it to run well on Solaris/OpenSolaris). This >>> is another reason why short man pages are being tacked on. Is it >>> possible to tack on a page to the javadoc? >>> >>> I don't want to see big javadoc patches in the SFW consolidation that >>> document detailed taxonomy information that we have to carry forever >>> because they will never be accepted into the upstream community. >>> Why would a FOSS project creating jar files even care about our >>> taxonomy rules? >>> >>>> 2. What if the man page simple documented the stability at the >>>> granularity of the jar file and >>>> nothing else. Perhaps the man page could generically reference the >>>> Javadoc? >>> >>> Not every jar file in /usr/share/lib/java has a man page, but >>> that is the current practice, for the ones that do: >>> >>> $ man asm >>> $ man mvel >>> $ man janino >>> $ man jettison >>> $ man joda-time >>> $ man jaxen-core >>> $ man junit >>> $ man ant (needs a more direct reference to javadoc) >>> ... >>> >>> As I see it, having jar file man pages... >>> >>> 1. Provides users stability and availability (taxonomy) information >>> about jar file packages on Solaris/OpenSolaris not available anywhere >>> else. >>> 2. Is pretty painless for project teams to produce and support. >>> 3. Man pages do no harm, and I think users are already getting >>> use to having them. Some information is better than no information. >>> 4. Until there is a better way, man pages should be required for >>> any new jar file submissions into Solaris/OpenSolaris. I thought >>> this was already true. >>> 5. Man pages are used by most Solaris/OpenSolaris packages. >>> 6. I appreciate where Java developers are coming from, but "not >>> standard >>> practice for Java developers to look for man pages" alone, doesn't seem >>> enough reason to stop man pages being delivered with jar file packages. >>> >>> We can't control how jar files are delivered or documented on >>> windows or other environments, but we can on Solaris/OpenSolaris. >>> >>> BTW. ccing Norm (sfw c-team lead) since one of the requirements to >>> integrate into sfw is a man page. >>> >>> Cheers, >>> Jim >> >> > > -- > * Mark A. Carlson * > Sr. Architect > > *Systems Group* > Phone x69559 / 303-223-6139 > Email Mark.Carlson@Sun.COM > > > From Mark.Carlson@sun.com Tue May 19 09:43:37 2009 Received: from newsunmail1brm.central.sun.com (newsunmail1brm.Central.Sun.COM [129.147.62.245]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4JGhaXT015512; Tue, 19 May 2009 09:43:36 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by newsunmail1brm.central.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4JGhYiD058596; Tue, 19 May 2009 10:43:36 -0600 (MDT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJW0020JH4O5T00@brm-avmta-1.central.sun.com>; Tue, 19 May 2009 10:43:36 -0600 (MDT) Received: from brmea-mail-1.sun.com ([192.18.98.31]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJW00DXZH4N9EA0@brm-avmta-1.central.sun.com>; Tue, 19 May 2009 10:43:35 -0600 (MDT) Received: from fe-amer-10.sun.com ([192.18.109.80]) by brmea-mail-1.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n4JGhZxt007160; Tue, 19 May 2009 16:43:35 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJW00200GU47600@mail-amer.sun.com>; Tue, 19 May 2009 10:43:35 -0600 (MDT) Received: from Macintosh-335.local ([unknown] [129.150.32.138]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJW00ASHH47JP70@mail-amer.sun.com>; Tue, 19 May 2009 10:43:24 -0600 (MDT) Date: Tue, 19 May 2009 10:43:18 -0600 From: "Mark A. Carlson" Subject: Re: jar file man pages - was Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] In-reply-to: <4A12E07E.7020802@sun.com> Sender: Mark.Carlson@sun.com To: "Garrett D'Amore" Cc: Richard.Matthews@sun.com, James.Walker@sun.com, Michael Kearney , LSARC-ext@sun.com, Norm Jacobs , PSARC-ext@sun.com Message-id: <4A12E1A6.5030801@sun.com> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <4A09EB8D.6090800@sun.com> <4A09F80D.6080305@gmail.com> <10008ADD-B6FC-4D0F-85A1-5DD4393E4532@sun.com> <4A0AD25A.7070508@Sun.com> <4A0B11E3.90203@sun.com> <4A12CD90.5050603@Sun.COM> <4A12DD8D.9030802@sun.com> <4A12E07E.7020802@sun.com> User-Agent: Thunderbird 2.0.0.21 (Macintosh/20090302) Status: RO Content-Length: 1043 Garrett D'Amore wrote: > Mark A. Carlson wrote: >> Let's keep in mind that we are trying to document (in an easily >> accessible place) the >> interface classification of the OpenSolaris instance (not the Java >> interface across platforms). >> Given that we need to do this without massive patches to the upstream >> code, and that >> Java projects should use whatever native mechanism exists to document >> the classification >> across platforms, the OpenSolaris man page seems to be the best place. > > I remain unconvinced that we (OpenSolaris) should even be concerned > about stability of Java APIs upon OpenSolaris. (With the possible > exception of APIs that are designed specifically to *support* > OpenSolaris itself.) > > Do other members see value in having another layer of commitment and > review beyond whatever is already done as part of the Java community? At a minimum, the definition of stability levels may not be the same, not to mention having a lower or higher commitment on the OpenSolaris platform. -- mark From Darren.Moffat@Sun.COM Tue May 19 09:44:25 2009 Received: from sunmail4.singapore.sun.com (sunmail4.Singapore.Sun.COM [129.158.71.19]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4JGiNjk015533; Tue, 19 May 2009 09:44:24 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail4.singapore.sun.com (8.13.4+Sun/8.13.3/ENSMAIL,v2.2) with ESMTP id n4JGi45v017989; Wed, 20 May 2009 00:44:22 +0800 (SGT) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJW00501H5Y2N00@nwk-avmta-1.sfbay.Sun.COM>; Tue, 19 May 2009 09:44:22 -0700 (PDT) Received: from gmp-eb-inf-1.sun.com ([192.18.6.21]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJW0024JH5XV590@nwk-avmta-1.sfbay.Sun.COM>; Tue, 19 May 2009 09:44:22 -0700 (PDT) Received: from fe-emea-09.sun.com (gmp-eb-lb-1-fe3.eu.sun.com [192.18.6.10]) by gmp-eb-inf-1.sun.com (8.13.7+Sun/8.12.9) with ESMTP id n4JGiLKt002606; Tue, 19 May 2009 16:44:21 +0000 (GMT) Received: from conversion-daemon.fe-emea-09.sun.com by fe-emea-09.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJW00800GXZG200@fe-emea-09.sun.com>; Tue, 19 May 2009 17:44:21 +0100 (BST) Received: from [192.168.1.102] (cpc2-rdng20-2-0-cust917.15-3.cable.virginmedia.com [86.28.167.150]) by fe-emea-09.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJW003VSH5W8L40@fe-emea-09.sun.com>; Tue, 19 May 2009 17:44:20 +0100 (BST) Date: Tue, 19 May 2009 17:44:20 +0100 From: Darren J Moffat Subject: Re: jar file man pages - was Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] In-reply-to: <4A12E07E.7020802@sun.com> Sender: Darren.Moffat@Sun.COM To: "Garrett D'Amore" Cc: "Mark A. Carlson" , Richard.Matthews@Sun.COM, James.Walker@Sun.COM, Michael Kearney , LSARC-ext@Sun.COM, Norm Jacobs , PSARC-ext@Sun.COM Message-id: <4A12E1E4.8040202@Sun.COM> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <4A09EB8D.6090800@sun.com> <4A09F80D.6080305@gmail.com> <10008ADD-B6FC-4D0F-85A1-5DD4393E4532@sun.com> <4A0AD25A.7070508@Sun.com> <4A0B11E3.90203@sun.com> <4A12CD90.5050603@Sun.COM> <4A12DD8D.9030802@sun.com> <4A12E07E.7020802@sun.com> User-Agent: Thunderbird 2.0.0.21 (X11/20090323) Status: RO Content-Length: 1745 Garrett D'Amore wrote: > Mark A. Carlson wrote: >> Let's keep in mind that we are trying to document (in an easily >> accessible place) the >> interface classification of the OpenSolaris instance (not the Java >> interface across platforms). >> Given that we need to do this without massive patches to the upstream >> code, and that >> Java projects should use whatever native mechanism exists to document >> the classification >> across platforms, the OpenSolaris man page seems to be the best place. > > I remain unconvinced that we (OpenSolaris) should even be concerned > about stability of Java APIs upon OpenSolaris. (With the possible > exception of APIs that are designed specifically to *support* > OpenSolaris itself.) > > Do other members see value in having another layer of commitment and > review beyond whatever is already done as part of the Java community? I think the only real review that is relevant is where it is installed and how it is packaged. If it provides a service how that service is started. This is not really any different to what we allow for code written in other languages. For example the real documentation (including stability levels) for libcurl is html docs under /usr/share/ That is what came from upstream. Personally I find even the addition of some of the ATTRIBUTES section information more than is really necessary in some cases - like when it is blindinly obvious this isn't OpenSolaris/Sun developed components. However given there is a good working system for adding it and it does provide value I'm happy to see it continue. If there is no man page for something and its docs come in a different format then IMO we should leave those docs alone. -- Darren J Moffat From Mark.Carlson@sun.com Tue May 19 09:43:37 2009 Received: from newsunmail1brm.central.sun.com (newsunmail1brm.Central.Sun.COM [129.147.62.245]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4JGhaXT015512; Tue, 19 May 2009 09:43:36 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by newsunmail1brm.central.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4JGhYiD058596; Tue, 19 May 2009 10:43:36 -0600 (MDT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJW0020JH4O5T00@brm-avmta-1.central.sun.com>; Tue, 19 May 2009 10:43:36 -0600 (MDT) Received: from brmea-mail-1.sun.com ([192.18.98.31]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJW00DXZH4N9EA0@brm-avmta-1.central.sun.com>; Tue, 19 May 2009 10:43:35 -0600 (MDT) Received: from fe-amer-10.sun.com ([192.18.109.80]) by brmea-mail-1.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n4JGhZxt007160; Tue, 19 May 2009 16:43:35 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJW00200GU47600@mail-amer.sun.com>; Tue, 19 May 2009 10:43:35 -0600 (MDT) Received: from Macintosh-335.local ([unknown] [129.150.32.138]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJW00ASHH47JP70@mail-amer.sun.com>; Tue, 19 May 2009 10:43:24 -0600 (MDT) Date: Tue, 19 May 2009 10:43:18 -0600 From: "Mark A. Carlson" Subject: Re: jar file man pages - was Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] In-reply-to: <4A12E07E.7020802@sun.com> Sender: Mark.Carlson@sun.com To: "Garrett D'Amore" Cc: Richard.Matthews@sun.com, James.Walker@sun.com, Michael Kearney , LSARC-ext@sun.com, Norm Jacobs , PSARC-ext@sun.com Message-id: <4A12E1A6.5030801@sun.com> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <4A09EB8D.6090800@sun.com> <4A09F80D.6080305@gmail.com> <10008ADD-B6FC-4D0F-85A1-5DD4393E4532@sun.com> <4A0AD25A.7070508@Sun.com> <4A0B11E3.90203@sun.com> <4A12CD90.5050603@Sun.COM> <4A12DD8D.9030802@sun.com> <4A12E07E.7020802@sun.com> User-Agent: Thunderbird 2.0.0.21 (Macintosh/20090302) Status: RO Content-Length: 1043 Garrett D'Amore wrote: > Mark A. Carlson wrote: >> Let's keep in mind that we are trying to document (in an easily >> accessible place) the >> interface classification of the OpenSolaris instance (not the Java >> interface across platforms). >> Given that we need to do this without massive patches to the upstream >> code, and that >> Java projects should use whatever native mechanism exists to document >> the classification >> across platforms, the OpenSolaris man page seems to be the best place. > > I remain unconvinced that we (OpenSolaris) should even be concerned > about stability of Java APIs upon OpenSolaris. (With the possible > exception of APIs that are designed specifically to *support* > OpenSolaris itself.) > > Do other members see value in having another layer of commitment and > review beyond whatever is already done as part of the Java community? At a minimum, the definition of stability levels may not be the same, not to mention having a lower or higher commitment on the OpenSolaris platform. -- mark From Darren.Moffat@Sun.COM Tue May 19 09:44:25 2009 Received: from sunmail4.singapore.sun.com (sunmail4.Singapore.Sun.COM [129.158.71.19]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4JGiNjk015533; Tue, 19 May 2009 09:44:24 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail4.singapore.sun.com (8.13.4+Sun/8.13.3/ENSMAIL,v2.2) with ESMTP id n4JGi45v017989; Wed, 20 May 2009 00:44:22 +0800 (SGT) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJW00501H5Y2N00@nwk-avmta-1.sfbay.Sun.COM>; Tue, 19 May 2009 09:44:22 -0700 (PDT) Received: from gmp-eb-inf-1.sun.com ([192.18.6.21]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJW0024JH5XV590@nwk-avmta-1.sfbay.Sun.COM>; Tue, 19 May 2009 09:44:22 -0700 (PDT) Received: from fe-emea-09.sun.com (gmp-eb-lb-1-fe3.eu.sun.com [192.18.6.10]) by gmp-eb-inf-1.sun.com (8.13.7+Sun/8.12.9) with ESMTP id n4JGiLKt002606; Tue, 19 May 2009 16:44:21 +0000 (GMT) Received: from conversion-daemon.fe-emea-09.sun.com by fe-emea-09.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJW00800GXZG200@fe-emea-09.sun.com>; Tue, 19 May 2009 17:44:21 +0100 (BST) Received: from [192.168.1.102] (cpc2-rdng20-2-0-cust917.15-3.cable.virginmedia.com [86.28.167.150]) by fe-emea-09.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJW003VSH5W8L40@fe-emea-09.sun.com>; Tue, 19 May 2009 17:44:20 +0100 (BST) Date: Tue, 19 May 2009 17:44:20 +0100 From: Darren J Moffat Subject: Re: jar file man pages - was Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] In-reply-to: <4A12E07E.7020802@sun.com> Sender: Darren.Moffat@Sun.COM To: "Garrett D'Amore" Cc: "Mark A. Carlson" , Richard.Matthews@Sun.COM, James.Walker@Sun.COM, Michael Kearney , LSARC-ext@Sun.COM, Norm Jacobs , PSARC-ext@Sun.COM Message-id: <4A12E1E4.8040202@Sun.COM> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <4A09EB8D.6090800@sun.com> <4A09F80D.6080305@gmail.com> <10008ADD-B6FC-4D0F-85A1-5DD4393E4532@sun.com> <4A0AD25A.7070508@Sun.com> <4A0B11E3.90203@sun.com> <4A12CD90.5050603@Sun.COM> <4A12DD8D.9030802@sun.com> <4A12E07E.7020802@sun.com> User-Agent: Thunderbird 2.0.0.21 (X11/20090323) Status: RO Content-Length: 1745 Garrett D'Amore wrote: > Mark A. Carlson wrote: >> Let's keep in mind that we are trying to document (in an easily >> accessible place) the >> interface classification of the OpenSolaris instance (not the Java >> interface across platforms). >> Given that we need to do this without massive patches to the upstream >> code, and that >> Java projects should use whatever native mechanism exists to document >> the classification >> across platforms, the OpenSolaris man page seems to be the best place. > > I remain unconvinced that we (OpenSolaris) should even be concerned > about stability of Java APIs upon OpenSolaris. (With the possible > exception of APIs that are designed specifically to *support* > OpenSolaris itself.) > > Do other members see value in having another layer of commitment and > review beyond whatever is already done as part of the Java community? I think the only real review that is relevant is where it is installed and how it is packaged. If it provides a service how that service is started. This is not really any different to what we allow for code written in other languages. For example the real documentation (including stability levels) for libcurl is html docs under /usr/share/ That is what came from upstream. Personally I find even the addition of some of the ATTRIBUTES section information more than is really necessary in some cases - like when it is blindinly obvious this isn't OpenSolaris/Sun developed components. However given there is a good working system for adding it and it does provide value I'm happy to see it continue. If there is no man page for something and its docs come in a different format then IMO we should leave those docs alone. -- Darren J Moffat From carlsonj@phorcys.east.sun.com Tue May 19 10:10:07 2009 Received: from sunmail3mpk.sfbay.sun.com (sunmail3mpk.SFBay.Sun.COM [129.146.11.52]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4JHA7gp018414; Tue, 19 May 2009 10:10:07 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail3mpk.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4JH9xmo018488; Tue, 19 May 2009 10:10:06 -0700 (PDT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJW0044LICSM400@brm-avmta-1.central.sun.com>; Tue, 19 May 2009 11:10:04 -0600 (MDT) Received: from dm-east-01.east.sun.com ([129.148.9.192]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJW00DS8ICS9IE0@brm-avmta-1.central.sun.com>; Tue, 19 May 2009 11:10:04 -0600 (MDT) Received: from phorcys.east.sun.com (phorcys.East.Sun.COM [129.148.174.143]) by dm-east-01.east.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n4JHA1aC003884; Tue, 19 May 2009 13:10:01 -0400 (EDT) Received: from phorcys.east.sun.com (phorcys.local [127.0.0.1]) by phorcys.east.sun.com (8.14.3+Sun/8.14.3) with ESMTP id n4JH94Zs028680; Tue, 19 May 2009 13:09:04 -0400 (EDT) Received: (from carlsonj@localhost) by phorcys.east.sun.com (8.14.3+Sun/8.14.3/Submit) id n4JH94j9028677; Tue, 19 May 2009 13:09:04 -0400 (EDT) Date: Tue, 19 May 2009 13:09:04 -0400 From: James Carlson Subject: Re: jar file man pages - was Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] In-reply-to: <4A12E07E.7020802@sun.com> To: "Garrett D'Amore" Cc: "Mark A. Carlson" , Michael Kearney , Norm Jacobs , LSARC-ext@sun.com, Richard.Matthews@sun.com, PSARC-ext@sun.com Message-id: <18962.59312.882172.463694@gargle.gargle.HOWL> MIME-version: 1.0 X-Mailer: VM 7.01 under Emacs 21.3.1 Content-type: text/plain; charset=us-ascii Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <4A09EB8D.6090800@sun.com> <4A09F80D.6080305@gmail.com> <10008ADD-B6FC-4D0F-85A1-5DD4393E4532@sun.com> <4A0AD25A.7070508@Sun.com> <4A0B11E3.90203@sun.com> <4A12CD90.5050603@Sun.COM> <4A12DD8D.9030802@sun.com> <4A12E07E.7020802@sun.com> Status: RO Content-Length: 2698 Garrett D'Amore writes: > Mark A. Carlson wrote: > > Let's keep in mind that we are trying to document (in an easily > > accessible place) the > > interface classification of the OpenSolaris instance (not the Java > > interface across platforms). > > Given that we need to do this without massive patches to the upstream > > code, and that > > Java projects should use whatever native mechanism exists to document > > the classification > > across platforms, the OpenSolaris man page seems to be the best place. > > I remain unconvinced that we (OpenSolaris) should even be concerned > about stability of Java APIs upon OpenSolaris. (With the possible > exception of APIs that are designed specifically to *support* > OpenSolaris itself.) > > Do other members see value in having another layer of commitment and > review beyond whatever is already done as part of the Java community? It's not "another layer of review." It's architectural review as required by the process. No matter how important a project team may be, we simply do not defer to project teams to do all architectural review on our behalf. There's only one ARC, and the system is designed that way on purpose. So, JCP may do whatever reviews it desires in its own way (as may other quasi-ARC-like bodies, such as CLARC and Sun Ray ARC), but to be shipped as a Sun product -- including but not limited to being part of the OpenSolaris distribution -- it's necessary that the engineering work goes through architectural review. In this case, I think we *are* concerned about advertising the right stability level for these interfaces, because that's an inherent part of software design, and not just some artifice that comes out of the ARC. If there's some local definition of stability levels and reference documentation, and these are well understood by users, then that's great. It doesn't matter to me much that it's not identical to our taxonomy or to man pages. We may as well use what's natural (and in fact require its use in all reviewed projects) so that users will understand it better. However, I do not agree that this means that we take a pass on it. If that's what we're planning to do (or if it's what you're suggesting here), then either (a) Java needs to create a SAC-sponsored process to play nice with the rest of us or (b) we need a much bigger rule (from the CTO's office) giving Java a get-out-of-ARC-free card. I don't think we can or should do that on our own. -- James Carlson, Solaris Networking Sun Microsystems / 35 Network Drive 71.232W Vox +1 781 442 2084 MS UBUR02-212 / Burlington MA 01803-2757 42.496N Fax +1 781 442 1677 From carlsonj@phorcys.east.sun.com Tue May 19 10:10:07 2009 Received: from sunmail3mpk.sfbay.sun.com (sunmail3mpk.SFBay.Sun.COM [129.146.11.52]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4JHA7gp018414; Tue, 19 May 2009 10:10:07 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail3mpk.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4JH9xmo018488; Tue, 19 May 2009 10:10:06 -0700 (PDT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJW0044LICSM400@brm-avmta-1.central.sun.com>; Tue, 19 May 2009 11:10:04 -0600 (MDT) Received: from dm-east-01.east.sun.com ([129.148.9.192]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJW00DS8ICS9IE0@brm-avmta-1.central.sun.com>; Tue, 19 May 2009 11:10:04 -0600 (MDT) Received: from phorcys.east.sun.com (phorcys.East.Sun.COM [129.148.174.143]) by dm-east-01.east.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n4JHA1aC003884; Tue, 19 May 2009 13:10:01 -0400 (EDT) Received: from phorcys.east.sun.com (phorcys.local [127.0.0.1]) by phorcys.east.sun.com (8.14.3+Sun/8.14.3) with ESMTP id n4JH94Zs028680; Tue, 19 May 2009 13:09:04 -0400 (EDT) Received: (from carlsonj@localhost) by phorcys.east.sun.com (8.14.3+Sun/8.14.3/Submit) id n4JH94j9028677; Tue, 19 May 2009 13:09:04 -0400 (EDT) Date: Tue, 19 May 2009 13:09:04 -0400 From: James Carlson Subject: Re: jar file man pages - was Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] In-reply-to: <4A12E07E.7020802@sun.com> To: "Garrett D'Amore" Cc: "Mark A. Carlson" , Michael Kearney , Norm Jacobs , LSARC-ext@sun.com, Richard.Matthews@sun.com, PSARC-ext@sun.com Message-id: <18962.59312.882172.463694@gargle.gargle.HOWL> MIME-version: 1.0 X-Mailer: VM 7.01 under Emacs 21.3.1 Content-type: text/plain; charset=us-ascii Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <4A09EB8D.6090800@sun.com> <4A09F80D.6080305@gmail.com> <10008ADD-B6FC-4D0F-85A1-5DD4393E4532@sun.com> <4A0AD25A.7070508@Sun.com> <4A0B11E3.90203@sun.com> <4A12CD90.5050603@Sun.COM> <4A12DD8D.9030802@sun.com> <4A12E07E.7020802@sun.com> Status: RO Content-Length: 2698 Garrett D'Amore writes: > Mark A. Carlson wrote: > > Let's keep in mind that we are trying to document (in an easily > > accessible place) the > > interface classification of the OpenSolaris instance (not the Java > > interface across platforms). > > Given that we need to do this without massive patches to the upstream > > code, and that > > Java projects should use whatever native mechanism exists to document > > the classification > > across platforms, the OpenSolaris man page seems to be the best place. > > I remain unconvinced that we (OpenSolaris) should even be concerned > about stability of Java APIs upon OpenSolaris. (With the possible > exception of APIs that are designed specifically to *support* > OpenSolaris itself.) > > Do other members see value in having another layer of commitment and > review beyond whatever is already done as part of the Java community? It's not "another layer of review." It's architectural review as required by the process. No matter how important a project team may be, we simply do not defer to project teams to do all architectural review on our behalf. There's only one ARC, and the system is designed that way on purpose. So, JCP may do whatever reviews it desires in its own way (as may other quasi-ARC-like bodies, such as CLARC and Sun Ray ARC), but to be shipped as a Sun product -- including but not limited to being part of the OpenSolaris distribution -- it's necessary that the engineering work goes through architectural review. In this case, I think we *are* concerned about advertising the right stability level for these interfaces, because that's an inherent part of software design, and not just some artifice that comes out of the ARC. If there's some local definition of stability levels and reference documentation, and these are well understood by users, then that's great. It doesn't matter to me much that it's not identical to our taxonomy or to man pages. We may as well use what's natural (and in fact require its use in all reviewed projects) so that users will understand it better. However, I do not agree that this means that we take a pass on it. If that's what we're planning to do (or if it's what you're suggesting here), then either (a) Java needs to create a SAC-sponsored process to play nice with the rest of us or (b) we need a much bigger rule (from the CTO's office) giving Java a get-out-of-ARC-free card. I don't think we can or should do that on our own. -- James Carlson, Solaris Networking Sun Microsystems / 35 Network Drive 71.232W Vox +1 781 442 2084 MS UBUR02-212 / Burlington MA 01803-2757 42.496N Fax +1 781 442 1677 From john.plocher@gmail.com Tue May 19 10:28:44 2009 Received: from sunmail3mpk.sfbay.sun.com (sunmail3mpk.SFBay.Sun.COM [129.146.11.52]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4JHSiAF019001; Tue, 19 May 2009 10:28:44 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail3mpk.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4JHSf3u000476; Tue, 19 May 2009 10:28:43 -0700 (PDT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJW00609J7UCK00@brm-avmta-1.central.sun.com>; Tue, 19 May 2009 11:28:42 -0600 (MDT) Received: from brmea-mail-1.sun.com ([192.18.98.31]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJW005J0J7TT100@brm-avmta-1.central.sun.com>; Tue, 19 May 2009 11:28:42 -0600 (MDT) Received: from relay14i.sun.com (ip124.net129179-4.block1.us.syntegra.com [129.179.4.124]) by brmea-mail-1.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n4JHLNSw000246; Tue, 19 May 2009 17:28:41 +0000 (GMT) Received: from mmp14es.mmp.us.syntegra.com ([160.41.208.14] [160.41.208.14]) by relay14i.sun.com with ESMTP id BT-MMP-915935; Tue, 19 May 2009 17:28:41 +0000 (Z) Received: from relay15i.sun.com (relay15i.sun.com [129.179.4.125]) by mmp14es.mmp.us.syntegra.com with ESMTP id BT-MMP-253410; Tue, 19 May 2009 17:28:41 +0000 (Z) Received: from qw-out-1920.google.com ([74.125.92.144] [74.125.92.144]) by relay1i.sun.com with ESMTP id BT-MMP-4554162; Tue, 19 May 2009 17:28:41 +0000 (Z) Received: by qw-out-1920.google.com with SMTP id 9so2773582qwj.50 for ; Tue, 19 May 2009 10:27:47 -0700 (PDT) Received: by 10.229.100.77 with SMTP id x13mr139425qcn.105.1242754066911; Tue, 19 May 2009 10:27:46 -0700 (PDT) Date: Tue, 19 May 2009 10:27:46 -0700 From: John Plocher Subject: Re: jar file man pages - was Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] In-reply-to: <4A12E1A6.5030801@sun.com> To: "Mark A. Carlson" Cc: Michael Kearney , Norm Jacobs , LSARC-ext@sun.com, Richard.Matthews@sun.com, PSARC-ext@sun.com Message-id: MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1 Content-transfer-encoding: 7BIT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=domainkey-signature:mime-version:received:in-reply-to:references :date:message-id:subject:from:to:cc:content-type :content-transfer-encoding; bh=DmLwA31veYk3ECsZARnMw0lPsC3vnWjGWJw5HMmQRos=; b=qasF0D6uGXatjSS/DkcAkupOnF/mlwh85M7IJ3s/gSSW2IGgJj6HlCsZBuTNaUtluY eAo23/Nb5bhMMkgbtMsDsn9qiUnUb9jHg8kf/FYlDzUgPrd8dRIIcvORk0YPEK0vRhT4 bR5K7Bac6H7p2c1ImxbuSZXKVGX4q5ujwWgEI= DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :cc:content-type:content-transfer-encoding; b=KXz51dUVeepo0httKRmOJyazOZcLDLfFYfjECshqkjuovk+n/+Ttu3fffYw27bKEdT nSPoNX6UmCfB/JNDDG1eoD6NgrkhT04uxrEBCobc77Nziaj28GWG4AxTLc36qWKkGGeQ /OLSTOfFapLXT6wd3vqt2HHdKKg9KUuid0A48= X-PMX-Version: 5.4.1.325704 X-Brightmail-Tracker: AAAAAA== X-Antispam: No, score=0.0/5.0, scanned in 0.059sec at (localhost [127.0.0.1]) by smf-spamd v1.3.1 - http://smfs.sf.net/ References: <4A09EB8D.6090800@sun.com> <4A09F80D.6080305@gmail.com> <10008ADD-B6FC-4D0F-85A1-5DD4393E4532@sun.com> <4A0AD25A.7070508@Sun.com> <4A0B11E3.90203@sun.com> <4A12CD90.5050603@Sun.COM> <4A12DD8D.9030802@sun.com> <4A12E07E.7020802@sun.com> <4A12E1A6.5030801@sun.com> Status: RO Content-Length: 1098 +-- various people wrote: | | ... I remain unconvinced that we (OpenSolaris) should even be concerned | about stability of Java APIs | | ... Do other members see value in having another layer of commitment and | review beyond whatever is already done as part of the Java community? | | ... At a minimum, the definition of stability levels may not be the same, | +-- It should be noted that the Java community has a very restricted formal interface taxonomy, which is a subset of the ARC one. Anything covered by a JSR is "Committed, Standard"; /everything/ else is "Volatile". There are psuedo-exceptions for in-progress JSR-track interfaces and for defacto "probably committed, but not JSR track interfaces", which should (IMO) both be considered Volatile as well, since the various OpenSolaris project teams and the ARC have no interest in seriously tracking each and every change that go into them. Trying to force fit additional taxonomy levels onto artifacts built by a community which does not use or value those levels themselves is at best make-work, and at worst, foolish :-) -John From john.plocher@gmail.com Tue May 19 10:28:44 2009 Received: from sunmail3mpk.sfbay.sun.com (sunmail3mpk.SFBay.Sun.COM [129.146.11.52]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4JHSiAF019001; Tue, 19 May 2009 10:28:44 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail3mpk.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4JHSf3u000476; Tue, 19 May 2009 10:28:43 -0700 (PDT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJW00609J7UCK00@brm-avmta-1.central.sun.com>; Tue, 19 May 2009 11:28:42 -0600 (MDT) Received: from brmea-mail-1.sun.com ([192.18.98.31]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJW005J0J7TT100@brm-avmta-1.central.sun.com>; Tue, 19 May 2009 11:28:42 -0600 (MDT) Received: from relay14i.sun.com (ip124.net129179-4.block1.us.syntegra.com [129.179.4.124]) by brmea-mail-1.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n4JHLNSw000246; Tue, 19 May 2009 17:28:41 +0000 (GMT) Received: from mmp14es.mmp.us.syntegra.com ([160.41.208.14] [160.41.208.14]) by relay14i.sun.com with ESMTP id BT-MMP-915935; Tue, 19 May 2009 17:28:41 +0000 (Z) Received: from relay15i.sun.com (relay15i.sun.com [129.179.4.125]) by mmp14es.mmp.us.syntegra.com with ESMTP id BT-MMP-253410; Tue, 19 May 2009 17:28:41 +0000 (Z) Received: from qw-out-1920.google.com ([74.125.92.144] [74.125.92.144]) by relay1i.sun.com with ESMTP id BT-MMP-4554162; Tue, 19 May 2009 17:28:41 +0000 (Z) Received: by qw-out-1920.google.com with SMTP id 9so2773582qwj.50 for ; Tue, 19 May 2009 10:27:47 -0700 (PDT) Received: by 10.229.100.77 with SMTP id x13mr139425qcn.105.1242754066911; Tue, 19 May 2009 10:27:46 -0700 (PDT) Date: Tue, 19 May 2009 10:27:46 -0700 From: John Plocher Subject: Re: jar file man pages - was Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] In-reply-to: <4A12E1A6.5030801@sun.com> To: "Mark A. Carlson" Cc: Michael Kearney , Norm Jacobs , LSARC-ext@sun.com, Richard.Matthews@sun.com, PSARC-ext@sun.com Message-id: MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1 Content-transfer-encoding: 7BIT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=domainkey-signature:mime-version:received:in-reply-to:references :date:message-id:subject:from:to:cc:content-type :content-transfer-encoding; bh=DmLwA31veYk3ECsZARnMw0lPsC3vnWjGWJw5HMmQRos=; b=qasF0D6uGXatjSS/DkcAkupOnF/mlwh85M7IJ3s/gSSW2IGgJj6HlCsZBuTNaUtluY eAo23/Nb5bhMMkgbtMsDsn9qiUnUb9jHg8kf/FYlDzUgPrd8dRIIcvORk0YPEK0vRhT4 bR5K7Bac6H7p2c1ImxbuSZXKVGX4q5ujwWgEI= DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :cc:content-type:content-transfer-encoding; b=KXz51dUVeepo0httKRmOJyazOZcLDLfFYfjECshqkjuovk+n/+Ttu3fffYw27bKEdT nSPoNX6UmCfB/JNDDG1eoD6NgrkhT04uxrEBCobc77Nziaj28GWG4AxTLc36qWKkGGeQ /OLSTOfFapLXT6wd3vqt2HHdKKg9KUuid0A48= X-PMX-Version: 5.4.1.325704 X-Brightmail-Tracker: AAAAAA== X-Antispam: No, score=0.0/5.0, scanned in 0.059sec at (localhost [127.0.0.1]) by smf-spamd v1.3.1 - http://smfs.sf.net/ References: <4A09EB8D.6090800@sun.com> <4A09F80D.6080305@gmail.com> <10008ADD-B6FC-4D0F-85A1-5DD4393E4532@sun.com> <4A0AD25A.7070508@Sun.com> <4A0B11E3.90203@sun.com> <4A12CD90.5050603@Sun.COM> <4A12DD8D.9030802@sun.com> <4A12E07E.7020802@sun.com> <4A12E1A6.5030801@sun.com> Status: RO Content-Length: 1098 +-- various people wrote: | | ... I remain unconvinced that we (OpenSolaris) should even be concerned | about stability of Java APIs | | ... Do other members see value in having another layer of commitment and | review beyond whatever is already done as part of the Java community? | | ... At a minimum, the definition of stability levels may not be the same, | +-- It should be noted that the Java community has a very restricted formal interface taxonomy, which is a subset of the ARC one. Anything covered by a JSR is "Committed, Standard"; /everything/ else is "Volatile". There are psuedo-exceptions for in-progress JSR-track interfaces and for defacto "probably committed, but not JSR track interfaces", which should (IMO) both be considered Volatile as well, since the various OpenSolaris project teams and the ARC have no interest in seriously tracking each and every change that go into them. Trying to force fit additional taxonomy levels onto artifacts built by a community which does not use or value those levels themselves is at best make-work, and at worst, foolish :-) -John From gdamore@Sun.COM Tue May 19 10:39:45 2009 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4JHdimS019719; Tue, 19 May 2009 10:39:44 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail5.uk.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n4JHdcSb001788; Tue, 19 May 2009 18:39:43 +0100 (BST) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJW00E01JQ5R000@nwk-avmta-1.sfbay.Sun.COM>; Tue, 19 May 2009 10:39:41 -0700 (PDT) Received: from sca-es-mail-1.sun.com ([192.18.43.132]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJW006IDJQ5ZR40@nwk-avmta-1.sfbay.Sun.COM>; Tue, 19 May 2009 10:39:41 -0700 (PDT) Received: from fe-sfbay-10.sun.com ([192.18.43.129]) by sca-es-mail-1.sun.com (8.13.7+Sun/8.12.9) with ESMTP id n4JHdf90023993; Tue, 19 May 2009 10:39:41 -0700 (PDT) Received: from conversion-daemon.fe-sfbay-10.sun.com by fe-sfbay-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJW00700IVNIA00@fe-sfbay-10.sun.com>; Tue, 19 May 2009 10:39:41 -0700 (PDT) Received: from [192.168.251.11] ([unknown] [76.93.15.33]) by fe-sfbay-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJW00K2YJPV8940@fe-sfbay-10.sun.com>; Tue, 19 May 2009 10:39:31 -0700 (PDT) Date: Tue, 19 May 2009 10:39:30 -0700 From: "Garrett D'Amore" Subject: Re: jar file man pages - was Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] In-reply-to: <18962.59312.882172.463694@gargle.gargle.HOWL> Sender: Garrett.Damore@Sun.COM To: James Carlson Cc: "Mark A. Carlson" , Michael Kearney , Norm Jacobs , LSARC-ext@Sun.COM, Richard.Matthews@Sun.COM, PSARC-ext@Sun.COM Message-id: <4A12EED2.4070501@sun.com> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <4A09EB8D.6090800@sun.com> <4A09F80D.6080305@gmail.com> <10008ADD-B6FC-4D0F-85A1-5DD4393E4532@sun.com> <4A0AD25A.7070508@Sun.com> <4A0B11E3.90203@sun.com> <4A12CD90.5050603@Sun.COM> <4A12DD8D.9030802@sun.com> <4A12E07E.7020802@sun.com> <18962.59312.882172.463694@gargle.gargle.HOWL> User-Agent: Thunderbird 2.0.0.18 (X11/20081201) Status: RO Content-Length: 5908 James Carlson wrote: > Garrett D'Amore writes: > >> Mark A. Carlson wrote: >> >>> Let's keep in mind that we are trying to document (in an easily >>> accessible place) the >>> interface classification of the OpenSolaris instance (not the Java >>> interface across platforms). >>> Given that we need to do this without massive patches to the upstream >>> code, and that >>> Java projects should use whatever native mechanism exists to document >>> the classification >>> across platforms, the OpenSolaris man page seems to be the best place. >>> >> I remain unconvinced that we (OpenSolaris) should even be concerned >> about stability of Java APIs upon OpenSolaris. (With the possible >> exception of APIs that are designed specifically to *support* >> OpenSolaris itself.) >> >> Do other members see value in having another layer of commitment and >> review beyond whatever is already done as part of the Java community? >> > > It's not "another layer of review." > > It's architectural review as required by the process. No matter how > important a project team may be, we simply do not defer to project > teams to do all architectural review on our behalf. There's only one > ARC, and the system is designed that way on purpose. > This sounds like a self-serving statement to me. I've always believed (and maybe I've misunderstood) that ARC review is designed to ensure that the bits that we deliver are properly reviewed -- to prevent total anarchy, and to ensure that the right people are looking at the project. What I'm failing to understand is how PSARC (or LSARC) review of Java APIs is at all meaningful. The right parties to involve in those conversations are *not* (at least today) the members of the ARCs. In fact, I propose that the current ARCs are woefully inadequate to understanding the delivery concerns for software that it is intended to be used in environments that are not Unix-ish. Furthermore, what sense does it make to "deny" a Java API, or even issue TCRs against such an API, when the API comes from upstream (and the upstream might well be Sun itself!), and is concerned with portability and such. I'm opposed to the idea of process for its own sake -- the process needs to add something or its just a waste everyone's time. I think reviewing of Java APIs (and assigning "stability" levels to such) on any kind of fine grained scale qualifies as such a waste. What *does* make sense for review, IMO, is: 1) delivery of major new revisions or features, such as Java 1.6 or whatever. 2) location of deliverables (what directory are libraries and commands located in) 3) stability of *major* components. (I.e. Java 1.6 is assigned a Committed binding on Solaris or somesuch) Anything more than that, including trying to provide "man pages" for individual APIs, is utter nonsense, IMO. > So, JCP may do whatever reviews it desires in its own way (as may > other quasi-ARC-like bodies, such as CLARC and Sun Ray ARC), but to be > shipped as a Sun product -- including but not limited to being part of > the OpenSolaris distribution -- it's necessary that the engineering > work goes through architectural review. > I view Java as a bit special, because it has an entire runtime environment that is totally disconnected from the rest of the platform. Trying to review a whole different platform in that context makes little or no sense, except in the broadest terms of "Java is available, and the version number is X with Commitment Level Y. Here are the directories...') > In this case, I think we *are* concerned about advertising the right > stability level for these interfaces, because that's an inherent part > of software design, and not just some artifice that comes out of the > ARC. > But its totally redundant, except that in this case the folks reviewing the API are probably completely inadequate to the task of performing the review. For example, how many ARC members are familiar with the issues faced by software intended to be deployed on cell phones. Or Win32? Or even Linux, for that matter? What about the considerations for software deployed in the browser? Or the sandbox restrictions of Java? Like it or not, our specialty is Solaris. The further afield we get from that, the more inadequate our ability to meaningfully review it. At some point we either have to degenerate into a pointless rubber stamp, or (worse) a potentially harmful (because we lack adequate context) barrier to progress. > If there's some local definition of stability levels and reference > documentation, and these are well understood by users, then that's > great. It doesn't matter to me much that it's not identical to our > taxonomy or to man pages. We may as well use what's natural (and in > fact require its use in all reviewed projects) so that users will > understand it better. > > However, I do not agree that this means that we take a pass on it. If > that's what we're planning to do (or if it's what you're suggesting > here), then either (a) Java needs to create a SAC-sponsored process to > play nice with the rest of us or (b) we need a much bigger rule (from > the CTO's office) giving Java a get-out-of-ARC-free card. I don't > think we can or should do that on our own. > Okay, I'll agree that we need to figure out a solution. I believe the latter approach (a designation from the CTO) is probably appropriate -- although I'd probably still require some very high level review of how Java delivers on the platform (rather than the details of *what* it delivers) to be reviewed. And of course, an exception for software that is primarily intended to be used in platform specific (Solaris specific) contexts. (For example, a JKstat Solaris implementation would, IMO, merit review.) Maybe a Java ARC (JARC) is required. - Garrett From gdamore@Sun.COM Tue May 19 10:39:45 2009 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4JHdimS019719; Tue, 19 May 2009 10:39:44 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail5.uk.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n4JHdcSb001788; Tue, 19 May 2009 18:39:43 +0100 (BST) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJW00E01JQ5R000@nwk-avmta-1.sfbay.Sun.COM>; Tue, 19 May 2009 10:39:41 -0700 (PDT) Received: from sca-es-mail-1.sun.com ([192.18.43.132]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJW006IDJQ5ZR40@nwk-avmta-1.sfbay.Sun.COM>; Tue, 19 May 2009 10:39:41 -0700 (PDT) Received: from fe-sfbay-10.sun.com ([192.18.43.129]) by sca-es-mail-1.sun.com (8.13.7+Sun/8.12.9) with ESMTP id n4JHdf90023993; Tue, 19 May 2009 10:39:41 -0700 (PDT) Received: from conversion-daemon.fe-sfbay-10.sun.com by fe-sfbay-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJW00700IVNIA00@fe-sfbay-10.sun.com>; Tue, 19 May 2009 10:39:41 -0700 (PDT) Received: from [192.168.251.11] ([unknown] [76.93.15.33]) by fe-sfbay-10.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJW00K2YJPV8940@fe-sfbay-10.sun.com>; Tue, 19 May 2009 10:39:31 -0700 (PDT) Date: Tue, 19 May 2009 10:39:30 -0700 From: "Garrett D'Amore" Subject: Re: jar file man pages - was Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009] In-reply-to: <18962.59312.882172.463694@gargle.gargle.HOWL> Sender: Garrett.Damore@Sun.COM To: James Carlson Cc: "Mark A. Carlson" , Michael Kearney , Norm Jacobs , LSARC-ext@Sun.COM, Richard.Matthews@Sun.COM, PSARC-ext@Sun.COM Message-id: <4A12EED2.4070501@sun.com> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <4A09EB8D.6090800@sun.com> <4A09F80D.6080305@gmail.com> <10008ADD-B6FC-4D0F-85A1-5DD4393E4532@sun.com> <4A0AD25A.7070508@Sun.com> <4A0B11E3.90203@sun.com> <4A12CD90.5050603@Sun.COM> <4A12DD8D.9030802@sun.com> <4A12E07E.7020802@sun.com> <18962.59312.882172.463694@gargle.gargle.HOWL> User-Agent: Thunderbird 2.0.0.18 (X11/20081201) Status: RO Content-Length: 5908 James Carlson wrote: > Garrett D'Amore writes: > >> Mark A. Carlson wrote: >> >>> Let's keep in mind that we are trying to document (in an easily >>> accessible place) the >>> interface classification of the OpenSolaris instance (not the Java >>> interface across platforms). >>> Given that we need to do this without massive patches to the upstream >>> code, and that >>> Java projects should use whatever native mechanism exists to document >>> the classification >>> across platforms, the OpenSolaris man page seems to be the best place. >>> >> I remain unconvinced that we (OpenSolaris) should even be concerned >> about stability of Java APIs upon OpenSolaris. (With the possible >> exception of APIs that are designed specifically to *support* >> OpenSolaris itself.) >> >> Do other members see value in having another layer of commitment and >> review beyond whatever is already done as part of the Java community? >> > > It's not "another layer of review." > > It's architectural review as required by the process. No matter how > important a project team may be, we simply do not defer to project > teams to do all architectural review on our behalf. There's only one > ARC, and the system is designed that way on purpose. > This sounds like a self-serving statement to me. I've always believed (and maybe I've misunderstood) that ARC review is designed to ensure that the bits that we deliver are properly reviewed -- to prevent total anarchy, and to ensure that the right people are looking at the project. What I'm failing to understand is how PSARC (or LSARC) review of Java APIs is at all meaningful. The right parties to involve in those conversations are *not* (at least today) the members of the ARCs. In fact, I propose that the current ARCs are woefully inadequate to understanding the delivery concerns for software that it is intended to be used in environments that are not Unix-ish. Furthermore, what sense does it make to "deny" a Java API, or even issue TCRs against such an API, when the API comes from upstream (and the upstream might well be Sun itself!), and is concerned with portability and such. I'm opposed to the idea of process for its own sake -- the process needs to add something or its just a waste everyone's time. I think reviewing of Java APIs (and assigning "stability" levels to such) on any kind of fine grained scale qualifies as such a waste. What *does* make sense for review, IMO, is: 1) delivery of major new revisions or features, such as Java 1.6 or whatever. 2) location of deliverables (what directory are libraries and commands located in) 3) stability of *major* components. (I.e. Java 1.6 is assigned a Committed binding on Solaris or somesuch) Anything more than that, including trying to provide "man pages" for individual APIs, is utter nonsense, IMO. > So, JCP may do whatever reviews it desires in its own way (as may > other quasi-ARC-like bodies, such as CLARC and Sun Ray ARC), but to be > shipped as a Sun product -- including but not limited to being part of > the OpenSolaris distribution -- it's necessary that the engineering > work goes through architectural review. > I view Java as a bit special, because it has an entire runtime environment that is totally disconnected from the rest of the platform. Trying to review a whole different platform in that context makes little or no sense, except in the broadest terms of "Java is available, and the version number is X with Commitment Level Y. Here are the directories...') > In this case, I think we *are* concerned about advertising the right > stability level for these interfaces, because that's an inherent part > of software design, and not just some artifice that comes out of the > ARC. > But its totally redundant, except that in this case the folks reviewing the API are probably completely inadequate to the task of performing the review. For example, how many ARC members are familiar with the issues faced by software intended to be deployed on cell phones. Or Win32? Or even Linux, for that matter? What about the considerations for software deployed in the browser? Or the sandbox restrictions of Java? Like it or not, our specialty is Solaris. The further afield we get from that, the more inadequate our ability to meaningfully review it. At some point we either have to degenerate into a pointless rubber stamp, or (worse) a potentially harmful (because we lack adequate context) barrier to progress. > If there's some local definition of stability levels and reference > documentation, and these are well understood by users, then that's > great. It doesn't matter to me much that it's not identical to our > taxonomy or to man pages. We may as well use what's natural (and in > fact require its use in all reviewed projects) so that users will > understand it better. > > However, I do not agree that this means that we take a pass on it. If > that's what we're planning to do (or if it's what you're suggesting > here), then either (a) Java needs to create a SAC-sponsored process to > play nice with the rest of us or (b) we need a much bigger rule (from > the CTO's office) giving Java a get-out-of-ARC-free card. I don't > think we can or should do that on our own. > Okay, I'll agree that we need to figure out a solution. I believe the latter approach (a designation from the CTO) is probably appropriate -- although I'd probably still require some very high level review of how Java delivers on the platform (rather than the details of *what* it delivers) to be reviewed. And of course, an exception for software that is primarily intended to be used in platform specific (Solaris specific) contexts. (For example, a JKstat Solaris implementation would, IMO, merit review.) Maybe a Java ARC (JARC) is required. - Garrett From Mark.Carlson@sun.com Tue May 19 15:23:26 2009 Received: from newsunmail1brm.central.sun.com (newsunmail1brm.Central.Sun.COM [129.147.62.245]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4JMNPuu026461 for ; Tue, 19 May 2009 15:23:25 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by newsunmail1brm.central.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4JMNOdv062007 for <@sunmail2sca.sfbay.sun.com:LSARC-ext@sun.com>; Tue, 19 May 2009 16:23:25 -0600 (MDT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJW00C0DWV0KL00@brm-avmta-1.central.sun.com> for LSARC-ext@sun.com (ORCPT LSARC-ext@sun.com); Tue, 19 May 2009 16:23:24 -0600 (MDT) Received: from brmea-mail-1.sun.com ([192.18.98.31]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJW00NHFWUZ4H90@brm-avmta-1.central.sun.com> for LSARC-ext@sun.com (ORCPT LSARC-ext@sun.com); Tue, 19 May 2009 16:23:23 -0600 (MDT) Received: from fe-amer-10.sun.com ([192.18.109.80]) by brmea-mail-1.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n4JMNNpi000620 for ; Tue, 19 May 2009 22:23:23 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJW00H00UUIJX00@mail-amer.sun.com> for LSARC-ext@sun.com (ORCPT LSARC-ext@sun.com); Tue, 19 May 2009 16:23:23 -0600 (MDT) Received: from boulder-dhcp-223.Central.Sun.COM ([unknown] [172.20.24.223]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJW00F1CWUYWP60@mail-amer.sun.com> for LSARC-ext@sun.com (ORCPT LSARC-ext@sun.com); Tue, 19 May 2009 16:23:22 -0600 (MDT) Date: Tue, 19 May 2009 16:23:20 -0600 From: "Mark A. Carlson" Subject: Re: trove-2.0.4 [LSARC/2009/262] - Draft Minority Opinion In-reply-to: <200904281656.n3SGuEVj009039@sac.sfbay.sun.com> Sender: Mark.Carlson@sun.com To: LSARC-ext@sun.com Cc: Vivek.Titarmare@sun.com Message-id: <4A133158.4010500@sun.com> MIME-version: 1.0 Content-type: multipart/alternative; boundary="Boundary_(ID_u+kMEhVmUNIY1yEjiTYoRg)" X-PMX-Version: 5.4.1.325704 References: <200904281656.n3SGuEVj009039@sac.sfbay.sun.com> User-Agent: Thunderbird 2.0.0.21 (Macintosh/20090302) Status: RO Content-Length: 6152 This is a multi-part message in MIME format. --Boundary_(ID_u+kMEhVmUNIY1yEjiTYoRg) Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT During the case discussion today, I took the AI to help Michael Kearney draft a minority opinion. There may be other minority opinions, but if this looks close to something you would sign on to, I am open to small changes. -- mark 5. Minority Opinion Background It is not typical for programmers working with non C/C++/Assembler files, such as Java Jar files, to determine the Exported Interface stability level using the man command. Java programmers depend on Javadoc, Python programmers depend on pydoc and so forth to document interfaces and the stability would best be indicated there. Approval of OpenSolaris projects have been inconsistent in preferring man pages or native documentation. This opinion seeks to clarify the issue and define a policy for all such cases going forward. Best Practice Case A - Sun Developed Components 1) Sun project team developing a Jar file shall document the ARC interface classification in the native documentation. (i.e. Javadocs) Case B - Components imported from external OSS Communities 1) The OSS Community documents the interface classification in their native documentation a) OpenSolaris project team agrees with the classification and supports it - Javadoc or other native documentation required (unchanged) - No man page shall be allowed b) OpenSolaris project team disagrees with the classification - Javadoc or native documentation required, but project team must change the OSS documentation to match the project team's classification - No man page shall be allowed 2) OSS Community does not document interface classification in their native documentation a) OpenSolaris project team is strongly encouraged to update the native documentation to reflect the OpenSolaris project team classification. - Changed Javadoc or other native documentation required - No man page shall be allowed b) OpenSolaris project team cannot support deltas to the native documentation - Unchanged Javadoc or other native documentation required - A man page shall be provided --Boundary_(ID_u+kMEhVmUNIY1yEjiTYoRg) Content-type: text/html; CHARSET=US-ASCII Content-transfer-encoding: 7BIT During the case discussion today, I took the AI to help Michael Kearney draft
a minority opinion. There may be other minority opinions, but if this looks
close to something you would sign on to, I am open to small changes.

-- mark

5. Minority Opinion

    Background

    It is not typical for programmers working with non C/C++/Assembler files, such as Java Jar files, to determine the
    Exported Interface stability level using the man command.  Java programmers depend on Javadoc, Python programmers
    depend on pydoc and so forth to document interfaces and the stability would best be indicated there.  

    Approval of OpenSolaris projects have been inconsistent in preferring man pages or native documentation.  This opinion seeks to clarify the issue and define a policy for all such cases going forward.

    Best Practice

    Case A - Sun Developed Components

        1) Sun project team developing a Jar file shall document the ARC interface classification in the native documentation. (i.e. Javadocs)

    Case B - Components imported from external OSS Communities

        1) The OSS Community documents the interface classification in their native documentation

            a) OpenSolaris project team agrees with the classification and supports it
                - Javadoc or other native documentation required (unchanged)
                - No man page shall be allowed

            b) OpenSolaris project team disagrees with the classification
                - Javadoc or native documentation required, but project team must change the OSS documentation
                to match the project team's classification
                - No man page shall be allowed

       2) OSS Community does not document interface classification in their native documentation
            a) OpenSolaris project team is strongly encouraged to update the native documentation to reflect the OpenSolaris project team
            classification.
                - Changed Javadoc or other native documentation required
                - No man page shall be allowed
            b) OpenSolaris project team cannot support deltas to the native documentation
                - Unchanged Javadoc or other native documentation required
                - A man page shall be provided

--Boundary_(ID_u+kMEhVmUNIY1yEjiTYoRg)-- From margot.miller@sun.com Tue May 19 17:53:57 2009 Received: from newsunmail1brm.central.sun.com (newsunmail1brm.Central.Sun.COM [129.147.62.245]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4K0rvDC027622; Tue, 19 May 2009 17:53:57 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by newsunmail1brm.central.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4K0ru1M061171; Tue, 19 May 2009 18:53:56 -0600 (MDT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJX005053TUQP00@brm-avmta-1.central.sun.com>; Tue, 19 May 2009 18:53:54 -0600 (MDT) Received: from jurassic-x4600.sfbay.sun.com ([129.146.17.63]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJX00JAY3TTR440@brm-avmta-1.central.sun.com>; Tue, 19 May 2009 18:53:53 -0600 (MDT) Received: from [10.7.250.88] (punchin-client-10-7-250-88.SFBay.Sun.COM [10.7.250.88]) by jurassic-x4600.sfbay.sun.com (8.14.3+Sun/8.14.3) with ESMTP id n4K0rqnH282532; Tue, 19 May 2009 17:53:52 -0700 (PDT) Date: Tue, 19 May 2009 17:53:52 -0700 From: margot Subject: Draft of trove-2.0.4 LSARC/2009/262 To: LSARC-ext@sun.com, psarc-ext@sun.com Cc: margot.miller@sun.com Message-id: <4A1354A0.2070601@sun.com> MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1; format=flowed Content-transfer-encoding: 8BIT X-PMX-Version: 5.4.1.325704 User-Agent: Thunderbird 2.0.0.17 (X11/20081023) Status: RO Content-Length: 4547 Hey All, Here is the draft opinion. Please review/comment. Thanks Margot ****************** sun microsystems Systems Architecture Committee _________________________________________________________________ Subject: trove-2.0.4 Submitted by: Vivek Titamare File: LSARC/2009/262/opinion.txt Date: May, 2009 Committee: Margot Hackett Miller, Lloyd Chambers Minority: Mark Carlson Product Approval Committee: Solaris PAC solaris-pac-opinion@sun.com 1. Summary This project is one of the Linux familiarity cases; this one provides a library to do fast regular and primitive collections for Java. 2. Decision & Precedence Information The project is approved as specified in reference [1]. The project may be delivered in a minor release of Solaris. 3. Interfaces Exported Interfaces: __________________________________________________ | Interfaces Exported | |____________ ______ |____________ __ __|____________| |Interface | Classification | Comments| |_______________ __|_________________|_____________| | trove.jar | Uncommitted | | |SUNWtrove | Uncommitted | | |___________________|_________________|____________| Imported Interfaces: ______________________________________________________________ | Interfaces Exported | | |___________________|______________ __|________________________| |Interface | Classification | Comments | |_______________ __|_________________|________________________| | | SUNWj5dev | Committed | Java Development kit | | SUNWj5rt | Committed | Java Runtime library | | SUNWj6dev | Committed | Java Development kit | | SUNWj6rt | Committed | Java Runtime library | |___________________|_________________|________________________| 4. Opinion During review, the only real issue raised was whether this team should provide a man page in addition to the javadocs. The man page would basically give a brief description of the jar file, pointer to the javadocs, and state the interface stability of the jar file. Discussion ensued whether it makes sense to ship a man page with a jar file. Solaris developers expect man pages, but do Java developers? Is it worth the extra work to provide a man page and would Java developers even look for a man page. It was noted that this is not standard practice as most Java developers look for java documentation via javadocs, not via man. However, others stated that having a minimal man page for a java jar file would allow the interface classification to be visible to the end user and a few other ARC cases have already shipped man pages for jar files. There was discussion over the granularity of the jar file and does it make sense to have an interface stability for the overall jar. Currently, java has Public, Package, and Protected. Does that convey enough of the stability of the jar and its methods to the developer? With all the FOSS that is being delivered into Solaris, projects are delivering in their native, natural form. This includes man pages, texinfo, html, and javadoc. So the problem isn't just with javadocs and jar files. There is quite a bit of FOSS out there with no interface stability in the external Sun documentation. This is not a problem for Sun project teams as they can always look at the interface tables in the ARC tables to determine stability level. Asking all java project teams to ship a man page in addition to javadocs doesn´t seem like the right solution and having some teams ship a man page and others not, does not provide consistency. There needs to more discussion to determine if it is critical that the ARC stability level be communicated to the Solaris end user for all the FOSS software that is being delivered. If so, a comprehensive solution needs to be formulated, whether it is a CLI, a man page, annotation embedded in the Javadocs (which will work for Sun products but you cant force that upstream). Up until now, most projects have not shipped man pages with jar files. This doesn´t seem to have been written down anywhere. With this case, we would like to make it explicit to not deliver man pages with jar files. This is setting precedent. 5. Minority Opinion(s) Mark Carlson providing text 6. Advisory Information None. 7. Appendices 7.1. Appendix A: Technical Changes Required Do not ship man pages with Java jar files 7.2. Appendix B: Technical Changes Advised None. 7.3. Appendix C: Reference Material Unless stated otherwise, path names are relative to the case directory LSARC/2009/262 1) Project Proposal file: LSARC/2009/262 Copyright 2009 Sun Microsystems From margot.miller@sun.com Tue May 19 17:53:57 2009 Received: from newsunmail1brm.central.sun.com (newsunmail1brm.Central.Sun.COM [129.147.62.245]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4K0rvDC027622; Tue, 19 May 2009 17:53:57 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by newsunmail1brm.central.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4K0ru1M061171; Tue, 19 May 2009 18:53:56 -0600 (MDT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJX005053TUQP00@brm-avmta-1.central.sun.com>; Tue, 19 May 2009 18:53:54 -0600 (MDT) Received: from jurassic-x4600.sfbay.sun.com ([129.146.17.63]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJX00JAY3TTR440@brm-avmta-1.central.sun.com>; Tue, 19 May 2009 18:53:53 -0600 (MDT) Received: from [10.7.250.88] (punchin-client-10-7-250-88.SFBay.Sun.COM [10.7.250.88]) by jurassic-x4600.sfbay.sun.com (8.14.3+Sun/8.14.3) with ESMTP id n4K0rqnH282532; Tue, 19 May 2009 17:53:52 -0700 (PDT) Date: Tue, 19 May 2009 17:53:52 -0700 From: margot Subject: Draft of trove-2.0.4 LSARC/2009/262 To: LSARC-ext@sun.com, psarc-ext@sun.com Cc: margot.miller@sun.com Message-id: <4A1354A0.2070601@sun.com> MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1; format=flowed Content-transfer-encoding: 8BIT X-PMX-Version: 5.4.1.325704 User-Agent: Thunderbird 2.0.0.17 (X11/20081023) Status: RO Content-Length: 4547 Hey All, Here is the draft opinion. Please review/comment. Thanks Margot ****************** sun microsystems Systems Architecture Committee _________________________________________________________________ Subject: trove-2.0.4 Submitted by: Vivek Titamare File: LSARC/2009/262/opinion.txt Date: May, 2009 Committee: Margot Hackett Miller, Lloyd Chambers Minority: Mark Carlson Product Approval Committee: Solaris PAC solaris-pac-opinion@sun.com 1. Summary This project is one of the Linux familiarity cases; this one provides a library to do fast regular and primitive collections for Java. 2. Decision & Precedence Information The project is approved as specified in reference [1]. The project may be delivered in a minor release of Solaris. 3. Interfaces Exported Interfaces: __________________________________________________ | Interfaces Exported | |____________ ______ |____________ __ __|____________| |Interface | Classification | Comments| |_______________ __|_________________|_____________| | trove.jar | Uncommitted | | |SUNWtrove | Uncommitted | | |___________________|_________________|____________| Imported Interfaces: ______________________________________________________________ | Interfaces Exported | | |___________________|______________ __|________________________| |Interface | Classification | Comments | |_______________ __|_________________|________________________| | | SUNWj5dev | Committed | Java Development kit | | SUNWj5rt | Committed | Java Runtime library | | SUNWj6dev | Committed | Java Development kit | | SUNWj6rt | Committed | Java Runtime library | |___________________|_________________|________________________| 4. Opinion During review, the only real issue raised was whether this team should provide a man page in addition to the javadocs. The man page would basically give a brief description of the jar file, pointer to the javadocs, and state the interface stability of the jar file. Discussion ensued whether it makes sense to ship a man page with a jar file. Solaris developers expect man pages, but do Java developers? Is it worth the extra work to provide a man page and would Java developers even look for a man page. It was noted that this is not standard practice as most Java developers look for java documentation via javadocs, not via man. However, others stated that having a minimal man page for a java jar file would allow the interface classification to be visible to the end user and a few other ARC cases have already shipped man pages for jar files. There was discussion over the granularity of the jar file and does it make sense to have an interface stability for the overall jar. Currently, java has Public, Package, and Protected. Does that convey enough of the stability of the jar and its methods to the developer? With all the FOSS that is being delivered into Solaris, projects are delivering in their native, natural form. This includes man pages, texinfo, html, and javadoc. So the problem isn't just with javadocs and jar files. There is quite a bit of FOSS out there with no interface stability in the external Sun documentation. This is not a problem for Sun project teams as they can always look at the interface tables in the ARC tables to determine stability level. Asking all java project teams to ship a man page in addition to javadocs doesn´t seem like the right solution and having some teams ship a man page and others not, does not provide consistency. There needs to more discussion to determine if it is critical that the ARC stability level be communicated to the Solaris end user for all the FOSS software that is being delivered. If so, a comprehensive solution needs to be formulated, whether it is a CLI, a man page, annotation embedded in the Javadocs (which will work for Sun products but you cant force that upstream). Up until now, most projects have not shipped man pages with jar files. This doesn´t seem to have been written down anywhere. With this case, we would like to make it explicit to not deliver man pages with jar files. This is setting precedent. 5. Minority Opinion(s) Mark Carlson providing text 6. Advisory Information None. 7. Appendices 7.1. Appendix A: Technical Changes Required Do not ship man pages with Java jar files 7.2. Appendix B: Technical Changes Advised None. 7.3. Appendix C: Reference Material Unless stated otherwise, path names are relative to the case directory LSARC/2009/262 1) Project Proposal file: LSARC/2009/262 Copyright 2009 Sun Microsystems From Mark.Carlson@sun.com Tue May 19 19:20:28 2009 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4K2KSVE029216; Tue, 19 May 2009 19:20:28 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail5.uk.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n4K2KQda002699; Wed, 20 May 2009 03:20:27 +0100 (BST) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJX001057U26300@nwk-avmta-1.sfbay.Sun.COM>; Tue, 19 May 2009 19:20:26 -0700 (PDT) Received: from brmea-mail-4.sun.com ([192.18.98.36]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJX003FI7U1DHE0@nwk-avmta-1.sfbay.Sun.COM>; Tue, 19 May 2009 19:20:26 -0700 (PDT) Received: from fe-amer-09.sun.com ([192.18.109.79]) by brmea-mail-4.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n4K2KPmJ022262; Wed, 20 May 2009 02:20:25 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJX001007OI5400@mail-amer.sun.com>; Tue, 19 May 2009 20:20:25 -0600 (MDT) Received: from Macintosh-335.local ([unknown] [71.237.94.98]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJX00AB47U1J1E0@mail-amer.sun.com>; Tue, 19 May 2009 20:20:25 -0600 (MDT) Date: Tue, 19 May 2009 20:20:25 -0600 From: "Mark A. Carlson" Subject: Re: Draft of trove-2.0.4 LSARC/2009/262 In-reply-to: <4A1354A0.2070601@sun.com> Sender: Mark.Carlson@sun.com To: margot Cc: LSARC-ext@sun.com, PSARC-ext@sun.com Message-id: <4A1368E9.6080506@sun.com> MIME-version: 1.0 Content-type: text/plain; format=flowed; charset=ISO-8859-1 Content-transfer-encoding: 8BIT X-PMX-Version: 5.4.1.325704 References: <4A1354A0.2070601@sun.com> User-Agent: Thunderbird 2.0.0.21 (Macintosh/20090302) Status: RO Content-Length: 4460 See inline. margot wrote: > Hey All, > > Here is the draft opinion. > > Please review/comment. > Thanks > Margot > > ****************** > > > sun > microsystems Systems Architecture Committee > > _________________________________________________________________ > > Subject: trove-2.0.4 > > Submitted by: Vivek Titamare > > File: LSARC/2009/262/opinion.txt > > Date: May, 2009 > > Committee: Margot Hackett Miller, Lloyd Chambers > Minority: Mark Carlson > > > Product Approval Committee: > Solaris PAC > solaris-pac-opinion@sun.com > > 1. Summary > > This project is one of the Linux familiarity cases; this one provides > a library to do fast regular and primitive collections for > Java. > > 2. Decision & Precedence Information > > The project is approved as specified in reference [1]. > > The project may be delivered in a minor release of Solaris. > > 3. Interfaces > > Exported Interfaces: > > __________________________________________________ > | Interfaces Exported | > |____________ ______ |____________ __ __|____________| > |Interface | Classification | Comments| > |_______________ __|_________________|_____________| > | trove.jar | Uncommitted | | > |SUNWtrove | Uncommitted | | > |___________________|_________________|____________| > > > Imported Interfaces: > > ______________________________________________________________ > | Interfaces Exported | | > |___________________|______________ __|________________________| > |Interface | Classification | Comments | > |_______________ __|_________________|________________________| > | > | SUNWj5dev | Committed | Java Development kit | > | SUNWj5rt | Committed | Java Runtime library | > | SUNWj6dev | Committed | Java Development kit | > | SUNWj6rt | Committed | Java Runtime library | > |___________________|_________________|________________________| > > > > > 4. Opinion > > During review, the only real issue raised was whether this team > should provide a man page in addition to the javadocs. The man > page would basically give a brief description of the jar file, > pointer to the javadocs, and state the interface stability of the jar > file. > Discussion ensued whether it makes sense to ship a man page > with a jar file. Solaris developers expect man pages, but do > Java developers? Is it worth the extra work to provide a man page > and would Java developers even look for a man page. > > It was noted that this is not standard practice as most Java > developers look > for java documentation via javadocs, not via man. However, others > stated that > having a minimal man page for a java jar file would allow the interface > classification to be visible to the end user and a few other ARC cases > have > already shipped man pages for jar files. > > There was discussion over the granularity of the jar file and does > it make sense to have an interface stability for the overall jar. > Currently, > java has Public, Package, and Protected. Does that convey enough > of the stability of the jar and its methods to the developer? Open ended questions don't belong in the opinion, so please either take this out or state a position. > > With all the FOSS that is being delivered into Solaris, projects are > delivering in their native, natural form. This includes man pages, > texinfo, html, > and javadoc. So the problem isn't just with javadocs and jar files. > There is quite a bit of FOSS out there with no interface stability > in the external Sun documentation. This is not a problem for Sun > project teams as they can always look at the interface tables in > the ARC tables to determine stability level. > > Asking all java project teams to ship a man page in addition to > javadocs doesn´t > seem like the right solution and having some teams ship a man page > and others not, does not provide consistency. > > There needs to more discussion to determine if it is critical that the > ARC stability > level be communicated to the Solaris end user for all the FOSS software > that is being delivered. If so, a comprehensive solution needs to be > formulated, whether it is a CLI, a man page, annotation embedded in > the Javadocs > (which will work for Sun products but you cant force that upstream). Do you really want to state that LSARC has a question about this? Without a concrete proposal on what each project should use or even whether they need to state the interface classification other than in the ARC case, I predict that they won't. -- mark From Mark.Carlson@sun.com Tue May 19 19:20:28 2009 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4K2KSVE029216; Tue, 19 May 2009 19:20:28 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail5.uk.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n4K2KQda002699; Wed, 20 May 2009 03:20:27 +0100 (BST) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJX001057U26300@nwk-avmta-1.sfbay.Sun.COM>; Tue, 19 May 2009 19:20:26 -0700 (PDT) Received: from brmea-mail-4.sun.com ([192.18.98.36]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJX003FI7U1DHE0@nwk-avmta-1.sfbay.Sun.COM>; Tue, 19 May 2009 19:20:26 -0700 (PDT) Received: from fe-amer-09.sun.com ([192.18.109.79]) by brmea-mail-4.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n4K2KPmJ022262; Wed, 20 May 2009 02:20:25 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJX001007OI5400@mail-amer.sun.com>; Tue, 19 May 2009 20:20:25 -0600 (MDT) Received: from Macintosh-335.local ([unknown] [71.237.94.98]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJX00AB47U1J1E0@mail-amer.sun.com>; Tue, 19 May 2009 20:20:25 -0600 (MDT) Date: Tue, 19 May 2009 20:20:25 -0600 From: "Mark A. Carlson" Subject: Re: Draft of trove-2.0.4 LSARC/2009/262 In-reply-to: <4A1354A0.2070601@sun.com> Sender: Mark.Carlson@sun.com To: margot Cc: LSARC-ext@sun.com, PSARC-ext@sun.com Message-id: <4A1368E9.6080506@sun.com> MIME-version: 1.0 Content-type: text/plain; format=flowed; charset=ISO-8859-1 Content-transfer-encoding: 8BIT X-PMX-Version: 5.4.1.325704 References: <4A1354A0.2070601@sun.com> User-Agent: Thunderbird 2.0.0.21 (Macintosh/20090302) Status: RO Content-Length: 4460 See inline. margot wrote: > Hey All, > > Here is the draft opinion. > > Please review/comment. > Thanks > Margot > > ****************** > > > sun > microsystems Systems Architecture Committee > > _________________________________________________________________ > > Subject: trove-2.0.4 > > Submitted by: Vivek Titamare > > File: LSARC/2009/262/opinion.txt > > Date: May, 2009 > > Committee: Margot Hackett Miller, Lloyd Chambers > Minority: Mark Carlson > > > Product Approval Committee: > Solaris PAC > solaris-pac-opinion@sun.com > > 1. Summary > > This project is one of the Linux familiarity cases; this one provides > a library to do fast regular and primitive collections for > Java. > > 2. Decision & Precedence Information > > The project is approved as specified in reference [1]. > > The project may be delivered in a minor release of Solaris. > > 3. Interfaces > > Exported Interfaces: > > __________________________________________________ > | Interfaces Exported | > |____________ ______ |____________ __ __|____________| > |Interface | Classification | Comments| > |_______________ __|_________________|_____________| > | trove.jar | Uncommitted | | > |SUNWtrove | Uncommitted | | > |___________________|_________________|____________| > > > Imported Interfaces: > > ______________________________________________________________ > | Interfaces Exported | | > |___________________|______________ __|________________________| > |Interface | Classification | Comments | > |_______________ __|_________________|________________________| > | > | SUNWj5dev | Committed | Java Development kit | > | SUNWj5rt | Committed | Java Runtime library | > | SUNWj6dev | Committed | Java Development kit | > | SUNWj6rt | Committed | Java Runtime library | > |___________________|_________________|________________________| > > > > > 4. Opinion > > During review, the only real issue raised was whether this team > should provide a man page in addition to the javadocs. The man > page would basically give a brief description of the jar file, > pointer to the javadocs, and state the interface stability of the jar > file. > Discussion ensued whether it makes sense to ship a man page > with a jar file. Solaris developers expect man pages, but do > Java developers? Is it worth the extra work to provide a man page > and would Java developers even look for a man page. > > It was noted that this is not standard practice as most Java > developers look > for java documentation via javadocs, not via man. However, others > stated that > having a minimal man page for a java jar file would allow the interface > classification to be visible to the end user and a few other ARC cases > have > already shipped man pages for jar files. > > There was discussion over the granularity of the jar file and does > it make sense to have an interface stability for the overall jar. > Currently, > java has Public, Package, and Protected. Does that convey enough > of the stability of the jar and its methods to the developer? Open ended questions don't belong in the opinion, so please either take this out or state a position. > > With all the FOSS that is being delivered into Solaris, projects are > delivering in their native, natural form. This includes man pages, > texinfo, html, > and javadoc. So the problem isn't just with javadocs and jar files. > There is quite a bit of FOSS out there with no interface stability > in the external Sun documentation. This is not a problem for Sun > project teams as they can always look at the interface tables in > the ARC tables to determine stability level. > > Asking all java project teams to ship a man page in addition to > javadocs doesn´t > seem like the right solution and having some teams ship a man page > and others not, does not provide consistency. > > There needs to more discussion to determine if it is critical that the > ARC stability > level be communicated to the Solaris end user for all the FOSS software > that is being delivered. If so, a comprehensive solution needs to be > formulated, whether it is a CLI, a man page, annotation embedded in > the Javadocs > (which will work for Sun products but you cant force that upstream). Do you really want to state that LSARC has a question about this? Without a concrete proposal on what each project should use or even whether they need to state the interface classification other than in the ARC case, I predict that they won't. -- mark From Michael.Kearney@sun.com Wed May 20 07:18:48 2009 Received: from sunmail3mpk.sfbay.sun.com (sunmail3mpk.SFBay.Sun.COM [129.146.11.52]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4KEIm8P002830; Wed, 20 May 2009 07:18:48 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail3mpk.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4KEIk8i020079; Wed, 20 May 2009 07:18:48 -0700 (PDT) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJY00M3L53B9O00@nwk-avmta-1.sfbay.Sun.COM>; Wed, 20 May 2009 07:18:47 -0700 (PDT) Received: from brmea-mail-4.sun.com ([192.18.98.36]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJY0069O52FRAD0@nwk-avmta-1.sfbay.Sun.COM>; Wed, 20 May 2009 07:18:15 -0700 (PDT) Received: from fe-amer-10.sun.com ([192.18.109.80]) by brmea-mail-4.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n4KEIFMF006506; Wed, 20 May 2009 14:18:15 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJY00F005004300@mail-amer.sun.com>; Wed, 20 May 2009 08:18:15 -0600 (MDT) Received: from [129.147.49.125] ([unknown] [129.147.49.125]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJY00AWK52C8C10@mail-amer.sun.com>; Wed, 20 May 2009 08:18:12 -0600 (MDT) Date: Wed, 20 May 2009 08:18:12 -0600 From: Michael Kearney Subject: Re: Draft of trove-2.0.4 LSARC/2009/262 In-reply-to: <4A1354A0.2070601@sun.com> Sender: Michael.Kearney@sun.com To: margot Cc: LSARC-ext@sun.com, PSARC-ext@sun.com Message-id: <4A141124.5040206@Sun.com> MIME-version: 1.0 Content-type: multipart/mixed; boundary="Boundary_(ID_UcgbTjpbSzlNtvqbUPM+qw)" X-PMX-Version: 5.4.1.325704 References: <4A1354A0.2070601@sun.com> User-Agent: Thunderbird 2.0.0.17 (Windows/20080914) Status: RO Content-Length: 6019 This is a multi-part message in MIME format. --Boundary_(ID_UcgbTjpbSzlNtvqbUPM+qw) Content-type: text/plain; format=flowed; charset=ISO-8859-1 Content-transfer-encoding: 8BIT See comments inline: margot wrote: > Hey All, > > Here is the draft opinion. > > Please review/comment. > Thanks > Margot > > ****************** > > > sun > microsystems Systems Architecture Committee > > _________________________________________________________________ > > Subject: trove-2.0.4 > > Submitted by: Vivek Titamare > > File: LSARC/2009/262/opinion.txt > > Date: May, 2009 > > Committee: Margot Hackett Miller, Lloyd Chambers > Minority: Mark Carlson > > > Product Approval Committee: > Solaris PAC > solaris-pac-opinion@sun.com > > 1. Summary > > This project is one of the Linux familiarity cases; this one provides > a library to do fast regular and primitive collections for > Java. > > 2. Decision & Precedence Information > > The project is approved as specified in reference [1]. > > The project may be delivered in a minor release of Solaris. > > 3. Interfaces > > Exported Interfaces: > > __________________________________________________ > | Interfaces Exported | > |____________ ______ |____________ __ __|____________| > |Interface | Classification | Comments| > |_______________ __|_________________|_____________| > | trove.jar | Uncommitted | | > |SUNWtrove | Uncommitted | | > |___________________|_________________|____________| > > > Imported Interfaces: > > ______________________________________________________________ > | Interfaces Exported | | > |___________________|______________ __|________________________| > |Interface | Classification | Comments | > |_______________ __|_________________|________________________| > | > | SUNWj5dev | Committed | Java Development kit | > | SUNWj5rt | Committed | Java Runtime library | > | SUNWj6dev | Committed | Java Development kit | > | SUNWj6rt | Committed | Java Runtime library | > |___________________|_________________|________________________| > > > > > 4. Opinion > > During review, the only real issue raised was whether this team > should provide a man page in addition to the javadocs. The man > page would basically give a brief description of the jar file, > pointer to the javadocs, and state the interface stability of the jar > file. > Discussion ensued whether it makes sense to ship a man page > with a jar file. Solaris developers expect man pages, but do > Java developers? Is it worth the extra work to provide a man page > and would Java developers even look for a man page. > > It was noted that this is not standard practice as most Java > developers look > for java documentation via javadocs, not via man. However, others > stated that > having a minimal man page for a java jar file would allow the interface > classification to be visible to the end user and a few other ARC cases > have > already shipped man pages for jar files. > > There was discussion over the granularity of the jar file and does > it make sense to have an interface stability for the overall jar. > Currently, > java has Public, Package, and Protected. Does that convey enough > of the stability of the jar and its methods to the developer? > > With all the FOSS that is being delivered into Solaris, projects are > delivering in their native, natural form. This includes man pages, > texinfo, html, > and javadoc. So the problem isn't just with javadocs and jar files. > There is quite a bit of FOSS out there with no interface stability > in the external Sun documentation. This is not a problem for Sun > project teams as they can always look at the interface tables in > the ARC tables to determine stability level. > > Asking all java project teams to ship a man page in addition to > javadocs doesn´t > seem like the right solution and having some teams ship a man page > and others not, does not provide consistency. > > There needs to more discussion to determine if it is critical that the > ARC stability > level be communicated to the Solaris end user for all the FOSS software > that is being delivered. If so, a comprehensive solution needs to be > formulated, whether it is a CLI, a man page, annotation embedded in > the Javadocs > (which will work for Sun products but you cant force that upstream). Shouldn't the discussion take place before rendering an opinion and setting a precedence? > > Up until now, most projects have not shipped man pages with jar > files. This doesn´t seem to have been written down anywhere. With > this case, we would like to make it explicit to not deliver man pages > with jar files. This is setting precedent. So, for Java projects (and all other types of projects where the "natural" documentation doesn't include a man page), no documentation of the interface stability is allowed? We really should set the precedent for all types of projects, otherwise we'll just be back here next week to discuss Python, etc. > > 5. Minority Opinion(s) > > Mark Carlson providing text > > 6. Advisory Information > > None. > > 7. Appendices > > 7.1. Appendix A: Technical Changes Required > > Do not ship man pages with Java jar files > > 7.2. Appendix B: Technical Changes Advised > > None. > > 7.3. Appendix C: Reference Material > > Unless stated otherwise, path names are relative to the case > directory LSARC/2009/262 > > 1) Project Proposal file: > > > LSARC/2009/262 Copyright 2009 Sun Microsystems > --Boundary_(ID_UcgbTjpbSzlNtvqbUPM+qw) Content-type: text/x-vcard; CHARSET=US-ASCII; name=Michael_Kearney.vcf Content-transfer-encoding: 7BIT Content-disposition: attachment; filename=Michael_Kearney.vcf begin:vcard fn:Michael Kearney n:Kearney;Michael org:Sun Microsystems, Inc.;Archive Core Engineering adr:500 Eldorado Blvd.;;Mailstop UBRM05-390;Broomfield;CO;80021;US email;internet:Michael.Kearney@Sun.com title:Staff Software Engineer tel;work:303-272-2402 tel;fax:303-272-6554 x-mozilla-html:TRUE url:http://www.sun.com/ version:2.1 end:vcard --Boundary_(ID_UcgbTjpbSzlNtvqbUPM+qw)-- From Michael.Kearney@sun.com Wed May 20 07:18:48 2009 Received: from sunmail3mpk.sfbay.sun.com (sunmail3mpk.SFBay.Sun.COM [129.146.11.52]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4KEIm8P002830; Wed, 20 May 2009 07:18:48 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail3mpk.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4KEIk8i020079; Wed, 20 May 2009 07:18:48 -0700 (PDT) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJY00M3L53B9O00@nwk-avmta-1.sfbay.Sun.COM>; Wed, 20 May 2009 07:18:47 -0700 (PDT) Received: from brmea-mail-4.sun.com ([192.18.98.36]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJY0069O52FRAD0@nwk-avmta-1.sfbay.Sun.COM>; Wed, 20 May 2009 07:18:15 -0700 (PDT) Received: from fe-amer-10.sun.com ([192.18.109.80]) by brmea-mail-4.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n4KEIFMF006506; Wed, 20 May 2009 14:18:15 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJY00F005004300@mail-amer.sun.com>; Wed, 20 May 2009 08:18:15 -0600 (MDT) Received: from [129.147.49.125] ([unknown] [129.147.49.125]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJY00AWK52C8C10@mail-amer.sun.com>; Wed, 20 May 2009 08:18:12 -0600 (MDT) Date: Wed, 20 May 2009 08:18:12 -0600 From: Michael Kearney Subject: Re: Draft of trove-2.0.4 LSARC/2009/262 In-reply-to: <4A1354A0.2070601@sun.com> Sender: Michael.Kearney@sun.com To: margot Cc: LSARC-ext@sun.com, PSARC-ext@sun.com Message-id: <4A141124.5040206@Sun.com> MIME-version: 1.0 Content-type: multipart/mixed; boundary="Boundary_(ID_UcgbTjpbSzlNtvqbUPM+qw)" X-PMX-Version: 5.4.1.325704 References: <4A1354A0.2070601@sun.com> User-Agent: Thunderbird 2.0.0.17 (Windows/20080914) Status: RO Content-Length: 6019 This is a multi-part message in MIME format. --Boundary_(ID_UcgbTjpbSzlNtvqbUPM+qw) Content-type: text/plain; format=flowed; charset=ISO-8859-1 Content-transfer-encoding: 8BIT See comments inline: margot wrote: > Hey All, > > Here is the draft opinion. > > Please review/comment. > Thanks > Margot > > ****************** > > > sun > microsystems Systems Architecture Committee > > _________________________________________________________________ > > Subject: trove-2.0.4 > > Submitted by: Vivek Titamare > > File: LSARC/2009/262/opinion.txt > > Date: May, 2009 > > Committee: Margot Hackett Miller, Lloyd Chambers > Minority: Mark Carlson > > > Product Approval Committee: > Solaris PAC > solaris-pac-opinion@sun.com > > 1. Summary > > This project is one of the Linux familiarity cases; this one provides > a library to do fast regular and primitive collections for > Java. > > 2. Decision & Precedence Information > > The project is approved as specified in reference [1]. > > The project may be delivered in a minor release of Solaris. > > 3. Interfaces > > Exported Interfaces: > > __________________________________________________ > | Interfaces Exported | > |____________ ______ |____________ __ __|____________| > |Interface | Classification | Comments| > |_______________ __|_________________|_____________| > | trove.jar | Uncommitted | | > |SUNWtrove | Uncommitted | | > |___________________|_________________|____________| > > > Imported Interfaces: > > ______________________________________________________________ > | Interfaces Exported | | > |___________________|______________ __|________________________| > |Interface | Classification | Comments | > |_______________ __|_________________|________________________| > | > | SUNWj5dev | Committed | Java Development kit | > | SUNWj5rt | Committed | Java Runtime library | > | SUNWj6dev | Committed | Java Development kit | > | SUNWj6rt | Committed | Java Runtime library | > |___________________|_________________|________________________| > > > > > 4. Opinion > > During review, the only real issue raised was whether this team > should provide a man page in addition to the javadocs. The man > page would basically give a brief description of the jar file, > pointer to the javadocs, and state the interface stability of the jar > file. > Discussion ensued whether it makes sense to ship a man page > with a jar file. Solaris developers expect man pages, but do > Java developers? Is it worth the extra work to provide a man page > and would Java developers even look for a man page. > > It was noted that this is not standard practice as most Java > developers look > for java documentation via javadocs, not via man. However, others > stated that > having a minimal man page for a java jar file would allow the interface > classification to be visible to the end user and a few other ARC cases > have > already shipped man pages for jar files. > > There was discussion over the granularity of the jar file and does > it make sense to have an interface stability for the overall jar. > Currently, > java has Public, Package, and Protected. Does that convey enough > of the stability of the jar and its methods to the developer? > > With all the FOSS that is being delivered into Solaris, projects are > delivering in their native, natural form. This includes man pages, > texinfo, html, > and javadoc. So the problem isn't just with javadocs and jar files. > There is quite a bit of FOSS out there with no interface stability > in the external Sun documentation. This is not a problem for Sun > project teams as they can always look at the interface tables in > the ARC tables to determine stability level. > > Asking all java project teams to ship a man page in addition to > javadocs doesn´t > seem like the right solution and having some teams ship a man page > and others not, does not provide consistency. > > There needs to more discussion to determine if it is critical that the > ARC stability > level be communicated to the Solaris end user for all the FOSS software > that is being delivered. If so, a comprehensive solution needs to be > formulated, whether it is a CLI, a man page, annotation embedded in > the Javadocs > (which will work for Sun products but you cant force that upstream). Shouldn't the discussion take place before rendering an opinion and setting a precedence? > > Up until now, most projects have not shipped man pages with jar > files. This doesn´t seem to have been written down anywhere. With > this case, we would like to make it explicit to not deliver man pages > with jar files. This is setting precedent. So, for Java projects (and all other types of projects where the "natural" documentation doesn't include a man page), no documentation of the interface stability is allowed? We really should set the precedent for all types of projects, otherwise we'll just be back here next week to discuss Python, etc. > > 5. Minority Opinion(s) > > Mark Carlson providing text > > 6. Advisory Information > > None. > > 7. Appendices > > 7.1. Appendix A: Technical Changes Required > > Do not ship man pages with Java jar files > > 7.2. Appendix B: Technical Changes Advised > > None. > > 7.3. Appendix C: Reference Material > > Unless stated otherwise, path names are relative to the case > directory LSARC/2009/262 > > 1) Project Proposal file: > > > LSARC/2009/262 Copyright 2009 Sun Microsystems > --Boundary_(ID_UcgbTjpbSzlNtvqbUPM+qw) Content-type: text/x-vcard; CHARSET=US-ASCII; name=Michael_Kearney.vcf Content-transfer-encoding: 7BIT Content-disposition: attachment; filename=Michael_Kearney.vcf begin:vcard fn:Michael Kearney n:Kearney;Michael org:Sun Microsystems, Inc.;Archive Core Engineering adr:500 Eldorado Blvd.;;Mailstop UBRM05-390;Broomfield;CO;80021;US email;internet:Michael.Kearney@Sun.com title:Staff Software Engineer tel;work:303-272-2402 tel;fax:303-272-6554 x-mozilla-html:TRUE url:http://www.sun.com/ version:2.1 end:vcard --Boundary_(ID_UcgbTjpbSzlNtvqbUPM+qw)-- From margot.miller@sun.com Wed May 20 07:36:31 2009 Received: from sunmail3mpk.sfbay.sun.com (sunmail3mpk.SFBay.Sun.COM [129.146.11.52]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4KEaVHa003201; Wed, 20 May 2009 07:36:31 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail3mpk.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4KEaUXX001087; Wed, 20 May 2009 07:36:31 -0700 (PDT) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJY0020J5WT9C00@nwk-avmta-1.sfbay.Sun.COM>; Wed, 20 May 2009 07:36:29 -0700 (PDT) Received: from jurassic-x4600.sfbay.sun.com ([129.146.17.63]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJY006TZ5WRR5E0@nwk-avmta-1.sfbay.Sun.COM>; Wed, 20 May 2009 07:36:27 -0700 (PDT) Received: from [10.7.250.88] (punchin-client-10-7-250-88.SFBay.Sun.COM [10.7.250.88]) by jurassic-x4600.sfbay.sun.com (8.14.3+Sun/8.14.3) with ESMTP id n4KEaQDT393921; Wed, 20 May 2009 07:36:27 -0700 (PDT) Date: Wed, 20 May 2009 07:36:26 -0700 From: margot Subject: Re: Draft of trove-2.0.4 LSARC/2009/262 In-reply-to: <4A141124.5040206@Sun.com> To: Michael Kearney Cc: LSARC-ext@sun.com, psarc-ext@sun.com Message-id: <4A14156A.7020706@sun.com> MIME-version: 1.0 Content-type: text/plain; charset=UTF-8; format=flowed Content-transfer-encoding: 8BIT X-PMX-Version: 5.4.1.325704 References: <4A1354A0.2070601@sun.com> <4A141124.5040206@Sun.com> User-Agent: Thunderbird 2.0.0.17 (X11/20081023) Status: RO Content-Length: 6181 Please see comments embedded below. Michael Kearney wrote: > See comments inline: > > margot wrote: >> Hey All, >> >> Here is the draft opinion. >> >> Please review/comment. >> Thanks >> Margot >> >> ****************** >> >> >> sun >> microsystems Systems Architecture Committee >> >> _________________________________________________________________ >> >> Subject: trove-2.0.4 >> >> Submitted by: Vivek Titamare >> >> File: LSARC/2009/262/opinion.txt >> >> Date: May, 2009 >> >> Committee: Margot Hackett Miller, Lloyd Chambers >> Minority: Mark Carlson >> >> >> Product Approval Committee: >> Solaris PAC >> solaris-pac-opinion@sun.com >> >> 1. Summary >> >> This project is one of the Linux familiarity cases; this one provides >> a library to do fast regular and primitive collections for >> Java. >> >> 2. Decision & Precedence Information >> >> The project is approved as specified in reference [1]. >> >> The project may be delivered in a minor release of Solaris. >> >> 3. Interfaces >> >> Exported Interfaces: >> >> __________________________________________________ >> | Interfaces Exported | >> |____________ ______ |____________ __ __|____________| >> |Interface | Classification | Comments| >> |_______________ __|_________________|_____________| >> | trove.jar | Uncommitted | | >> |SUNWtrove | Uncommitted | | >> |___________________|_________________|____________| >> >> >> Imported Interfaces: >> >> ______________________________________________________________ >> | Interfaces Exported | | >> |___________________|______________ __|________________________| >> |Interface | Classification | Comments | >> |_______________ __|_________________|________________________| >> | >> | SUNWj5dev | Committed | Java Development kit | >> | SUNWj5rt | Committed | Java Runtime library | >> | SUNWj6dev | Committed | Java Development kit | >> | SUNWj6rt | Committed | Java Runtime library | >> |___________________|_________________|________________________| >> >> >> >> >> 4. Opinion >> >> During review, the only real issue raised was whether this team >> should provide a man page in addition to the javadocs. The man >> page would basically give a brief description of the jar file, >> pointer to the javadocs, and state the interface stability of the jar >> file. >> Discussion ensued whether it makes sense to ship a man page >> with a jar file. Solaris developers expect man pages, but do >> Java developers? Is it worth the extra work to provide a man page >> and would Java developers even look for a man page. >> >> It was noted that this is not standard practice as most Java >> developers look >> for java documentation via javadocs, not via man. However, others >> stated that >> having a minimal man page for a java jar file would allow the interface >> classification to be visible to the end user and a few other ARC >> cases have >> already shipped man pages for jar files. >> >> There was discussion over the granularity of the jar file and does >> it make sense to have an interface stability for the overall jar. >> Currently, >> java has Public, Package, and Protected. Does that convey enough >> of the stability of the jar and its methods to the developer? >> >> With all the FOSS that is being delivered into Solaris, projects are >> delivering in their native, natural form. This includes man pages, >> texinfo, html, >> and javadoc. So the problem isn't just with javadocs and jar files. >> There is quite a bit of FOSS out there with no interface stability >> in the external Sun documentation. This is not a problem for Sun >> project teams as they can always look at the interface tables in >> the ARC tables to determine stability level. >> >> Asking all java project teams to ship a man page in addition to >> javadocs doesn´t >> seem like the right solution and having some teams ship a man page >> and others not, does not provide consistency. >> >> There needs to more discussion to determine if it is critical that >> the ARC stability >> level be communicated to the Solaris end user for all the FOSS software >> that is being delivered. If so, a comprehensive solution needs to be >> formulated, whether it is a CLI, a man page, annotation embedded in >> the Javadocs >> (which will work for Sun products but you cant force that upstream). > Shouldn't the discussion take place before rendering an opinion and > setting a precedence? I think we identified the problem but this case can not solve that. For this case, the issue has to do with projects shipping man pages with jars. The precedence is do not ship man pages with jar files. We still need to figure out how to communicate stability level to customers on all FOSS. But thatĹ› not this case. >> >> Up until now, most projects have not shipped man pages with jar >> files. This doesn´t seem to have been written down anywhere. With >> this case, we would like to make it explicit to not deliver man pages >> with jar files. This is setting precedent. > So, for Java projects (and all other types of projects where the > "natural" documentation doesn't > include a man page), no documentation of the interface stability is > allowed? > We really should set the precedent for all types of projects, > otherwise we'll just be back here next > week to discuss Python, etc. I did not mean to imply that. The only thing here is- do not ship a man page. If the stability level is in the docs, like the AppServer is proposing with annotations, they can ship that. What we did say at the meeting is that project teams do not have to modify the ¨natural¨ docs to include stability level. I will add this clarification to the opinion. Thanks Margot >> >> 5. Minority Opinion(s) >> >> Mark Carlson providing text >> >> 6. Advisory Information >> >> None. >> >> 7. Appendices >> >> 7.1. Appendix A: Technical Changes Required >> >> Do not ship man pages with Java jar files >> >> 7.2. Appendix B: Technical Changes Advised >> >> None. >> >> 7.3. Appendix C: Reference Material >> >> Unless stated otherwise, path names are relative to the case >> directory LSARC/2009/262 >> >> 1) Project Proposal file: >> >> >> LSARC/2009/262 Copyright 2009 Sun Microsystems >> > From margot.miller@sun.com Wed May 20 07:36:31 2009 Received: from sunmail3mpk.sfbay.sun.com (sunmail3mpk.SFBay.Sun.COM [129.146.11.52]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4KEaVHa003201; Wed, 20 May 2009 07:36:31 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail3mpk.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4KEaUXX001087; Wed, 20 May 2009 07:36:31 -0700 (PDT) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJY0020J5WT9C00@nwk-avmta-1.sfbay.Sun.COM>; Wed, 20 May 2009 07:36:29 -0700 (PDT) Received: from jurassic-x4600.sfbay.sun.com ([129.146.17.63]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJY006TZ5WRR5E0@nwk-avmta-1.sfbay.Sun.COM>; Wed, 20 May 2009 07:36:27 -0700 (PDT) Received: from [10.7.250.88] (punchin-client-10-7-250-88.SFBay.Sun.COM [10.7.250.88]) by jurassic-x4600.sfbay.sun.com (8.14.3+Sun/8.14.3) with ESMTP id n4KEaQDT393921; Wed, 20 May 2009 07:36:27 -0700 (PDT) Date: Wed, 20 May 2009 07:36:26 -0700 From: margot Subject: Re: Draft of trove-2.0.4 LSARC/2009/262 In-reply-to: <4A141124.5040206@Sun.com> To: Michael Kearney Cc: LSARC-ext@sun.com, psarc-ext@sun.com Message-id: <4A14156A.7020706@sun.com> MIME-version: 1.0 Content-type: text/plain; charset=UTF-8; format=flowed Content-transfer-encoding: 8BIT X-PMX-Version: 5.4.1.325704 References: <4A1354A0.2070601@sun.com> <4A141124.5040206@Sun.com> User-Agent: Thunderbird 2.0.0.17 (X11/20081023) Status: RO Content-Length: 6181 Please see comments embedded below. Michael Kearney wrote: > See comments inline: > > margot wrote: >> Hey All, >> >> Here is the draft opinion. >> >> Please review/comment. >> Thanks >> Margot >> >> ****************** >> >> >> sun >> microsystems Systems Architecture Committee >> >> _________________________________________________________________ >> >> Subject: trove-2.0.4 >> >> Submitted by: Vivek Titamare >> >> File: LSARC/2009/262/opinion.txt >> >> Date: May, 2009 >> >> Committee: Margot Hackett Miller, Lloyd Chambers >> Minority: Mark Carlson >> >> >> Product Approval Committee: >> Solaris PAC >> solaris-pac-opinion@sun.com >> >> 1. Summary >> >> This project is one of the Linux familiarity cases; this one provides >> a library to do fast regular and primitive collections for >> Java. >> >> 2. Decision & Precedence Information >> >> The project is approved as specified in reference [1]. >> >> The project may be delivered in a minor release of Solaris. >> >> 3. Interfaces >> >> Exported Interfaces: >> >> __________________________________________________ >> | Interfaces Exported | >> |____________ ______ |____________ __ __|____________| >> |Interface | Classification | Comments| >> |_______________ __|_________________|_____________| >> | trove.jar | Uncommitted | | >> |SUNWtrove | Uncommitted | | >> |___________________|_________________|____________| >> >> >> Imported Interfaces: >> >> ______________________________________________________________ >> | Interfaces Exported | | >> |___________________|______________ __|________________________| >> |Interface | Classification | Comments | >> |_______________ __|_________________|________________________| >> | >> | SUNWj5dev | Committed | Java Development kit | >> | SUNWj5rt | Committed | Java Runtime library | >> | SUNWj6dev | Committed | Java Development kit | >> | SUNWj6rt | Committed | Java Runtime library | >> |___________________|_________________|________________________| >> >> >> >> >> 4. Opinion >> >> During review, the only real issue raised was whether this team >> should provide a man page in addition to the javadocs. The man >> page would basically give a brief description of the jar file, >> pointer to the javadocs, and state the interface stability of the jar >> file. >> Discussion ensued whether it makes sense to ship a man page >> with a jar file. Solaris developers expect man pages, but do >> Java developers? Is it worth the extra work to provide a man page >> and would Java developers even look for a man page. >> >> It was noted that this is not standard practice as most Java >> developers look >> for java documentation via javadocs, not via man. However, others >> stated that >> having a minimal man page for a java jar file would allow the interface >> classification to be visible to the end user and a few other ARC >> cases have >> already shipped man pages for jar files. >> >> There was discussion over the granularity of the jar file and does >> it make sense to have an interface stability for the overall jar. >> Currently, >> java has Public, Package, and Protected. Does that convey enough >> of the stability of the jar and its methods to the developer? >> >> With all the FOSS that is being delivered into Solaris, projects are >> delivering in their native, natural form. This includes man pages, >> texinfo, html, >> and javadoc. So the problem isn't just with javadocs and jar files. >> There is quite a bit of FOSS out there with no interface stability >> in the external Sun documentation. This is not a problem for Sun >> project teams as they can always look at the interface tables in >> the ARC tables to determine stability level. >> >> Asking all java project teams to ship a man page in addition to >> javadocs doesn´t >> seem like the right solution and having some teams ship a man page >> and others not, does not provide consistency. >> >> There needs to more discussion to determine if it is critical that >> the ARC stability >> level be communicated to the Solaris end user for all the FOSS software >> that is being delivered. If so, a comprehensive solution needs to be >> formulated, whether it is a CLI, a man page, annotation embedded in >> the Javadocs >> (which will work for Sun products but you cant force that upstream). > Shouldn't the discussion take place before rendering an opinion and > setting a precedence? I think we identified the problem but this case can not solve that. For this case, the issue has to do with projects shipping man pages with jars. The precedence is do not ship man pages with jar files. We still need to figure out how to communicate stability level to customers on all FOSS. But thatĹ› not this case. >> >> Up until now, most projects have not shipped man pages with jar >> files. This doesn´t seem to have been written down anywhere. With >> this case, we would like to make it explicit to not deliver man pages >> with jar files. This is setting precedent. > So, for Java projects (and all other types of projects where the > "natural" documentation doesn't > include a man page), no documentation of the interface stability is > allowed? > We really should set the precedent for all types of projects, > otherwise we'll just be back here next > week to discuss Python, etc. I did not mean to imply that. The only thing here is- do not ship a man page. If the stability level is in the docs, like the AppServer is proposing with annotations, they can ship that. What we did say at the meeting is that project teams do not have to modify the ¨natural¨ docs to include stability level. I will add this clarification to the opinion. Thanks Margot >> >> 5. Minority Opinion(s) >> >> Mark Carlson providing text >> >> 6. Advisory Information >> >> None. >> >> 7. Appendices >> >> 7.1. Appendix A: Technical Changes Required >> >> Do not ship man pages with Java jar files >> >> 7.2. Appendix B: Technical Changes Advised >> >> None. >> >> 7.3. Appendix C: Reference Material >> >> Unless stated otherwise, path names are relative to the case >> directory LSARC/2009/262 >> >> 1) Project Proposal file: >> >> >> LSARC/2009/262 Copyright 2009 Sun Microsystems >> > From carlsonj@phorcys.east.sun.com Wed May 20 07:44:49 2009 Received: from sunmail3mpk.sfbay.sun.com (sunmail3mpk.SFBay.Sun.COM [129.146.11.52]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4KEimIq003440; Wed, 20 May 2009 07:44:48 -0700 (PDT) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by sunmail3mpk.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4KEimjY004746; Wed, 20 May 2009 07:44:48 -0700 (PDT) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJY00K1Z6AO6V00@nwk-avmta-2.sfbay.sun.com>; Wed, 20 May 2009 07:44:48 -0700 (PDT) Received: from dm-east-02.east.sun.com ([129.148.13.5]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJY00CAV6AMU9B0@nwk-avmta-2.sfbay.sun.com>; Wed, 20 May 2009 07:44:47 -0700 (PDT) Received: from phorcys.east.sun.com (phorcys.East.Sun.COM [129.148.174.143]) by dm-east-02.east.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n4KEii4s059839; Wed, 20 May 2009 10:44:44 -0400 (EDT) Received: from phorcys.east.sun.com (phorcys.local [127.0.0.1]) by phorcys.east.sun.com (8.14.3+Sun/8.14.3) with ESMTP id n4KEhm19002251; Wed, 20 May 2009 10:43:48 -0400 (EDT) Received: (from carlsonj@localhost) by phorcys.east.sun.com (8.14.3+Sun/8.14.3/Submit) id n4KEhmZ8002248; Wed, 20 May 2009 10:43:48 -0400 (EDT) Date: Wed, 20 May 2009 10:43:48 -0400 From: James Carlson Subject: Re: Draft of trove-2.0.4 LSARC/2009/262 In-reply-to: <4A141124.5040206@Sun.com> To: Michael Kearney Cc: margot , LSARC-ext@sun.com, PSARC-ext@sun.com Message-id: <18964.5924.330247.409291@gargle.gargle.HOWL> MIME-version: 1.0 X-Mailer: VM 7.01 under Emacs 21.3.1 Content-type: text/plain; charset=iso-8859-1 X-PMX-Version: 5.4.1.325704 References: <4A1354A0.2070601@sun.com> <4A141124.5040206@Sun.com> Content-Transfer-Encoding: 8bit X-MIME-Autoconverted: from quoted-printable to 8bit by sac.sfbay.sun.com id n4KEimIq003440 Status: RO Content-Length: 2839 Michael Kearney writes: > > There needs to more discussion to determine if it is critical that the > > ARC stability > > level be communicated to the Solaris end user for all the FOSS software > > that is being delivered. If so, a comprehensive solution needs to be > > formulated, whether it is a CLI, a man page, annotation embedded in > > the Javadocs > > (which will work for Sun products but you cant force that upstream). > Shouldn't the discussion take place before rendering an opinion and > setting a precedence? Yep; agreed. For what it's worth, I would vote for using native documentation and native stability indications where feasible, and adding our own notations only when the community lacks sufficient information. I don't think it makes sense to force communities that have their own stability traditions to conform to our mold, provided that the "communities" include those Sun customers who would also receive this software. One of the high level goals of this architecture process is to make sure that dependencies are documented, and expectations are understood both by suppliers and consumers. As long as that goal is reached in a consistent and unsurprising way, I don't really care whether it's done by way of 'man', 'pydoc', 'javadoc', or 'whatsupdoc.' The only time it matters is when crossing worlds. If users can depend on both Java and Python supplied interfaces (for instance), then they would need a decoder ring to understand what each one provides, and that might well lead to mistakes. Thus, the boundaries for these native stability interfaces need to be crystal clear. (That is to say: external protocols, file formats, command lines, and visible-to-those-outside-the-domain programming interfaces are likely all things that cannot be documented properly using native stability levels.) > > Up until now, most projects have not shipped man pages with jar > > files. This doesn´t seem to have been written down anywhere. With > > this case, we would like to make it explicit to not deliver man pages > > with jar files. This is setting precedent. > So, for Java projects (and all other types of projects where the > "natural" documentation doesn't > include a man page), no documentation of the interface stability is allowed? > We really should set the precedent for all types of projects, otherwise > we'll just be back here next > week to discuss Python, etc. I had thought that the actual vote in LSARC was 2-to-1 to allow man pages as an option. But I agree that it does need to be consistent so that we don't have to have this debate every few months. -- James Carlson, Solaris Networking Sun Microsystems / 35 Network Drive 71.232W Vox +1 781 442 2084 MS UBUR02-212 / Burlington MA 01803-2757 42.496N Fax +1 781 442 1677 From carlsonj@phorcys.east.sun.com Wed May 20 07:44:49 2009 Received: from sunmail3mpk.sfbay.sun.com (sunmail3mpk.SFBay.Sun.COM [129.146.11.52]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4KEimIq003440; Wed, 20 May 2009 07:44:48 -0700 (PDT) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by sunmail3mpk.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4KEimjY004746; Wed, 20 May 2009 07:44:48 -0700 (PDT) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJY00K1Z6AO6V00@nwk-avmta-2.sfbay.sun.com>; Wed, 20 May 2009 07:44:48 -0700 (PDT) Received: from dm-east-02.east.sun.com ([129.148.13.5]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJY00CAV6AMU9B0@nwk-avmta-2.sfbay.sun.com>; Wed, 20 May 2009 07:44:47 -0700 (PDT) Received: from phorcys.east.sun.com (phorcys.East.Sun.COM [129.148.174.143]) by dm-east-02.east.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n4KEii4s059839; Wed, 20 May 2009 10:44:44 -0400 (EDT) Received: from phorcys.east.sun.com (phorcys.local [127.0.0.1]) by phorcys.east.sun.com (8.14.3+Sun/8.14.3) with ESMTP id n4KEhm19002251; Wed, 20 May 2009 10:43:48 -0400 (EDT) Received: (from carlsonj@localhost) by phorcys.east.sun.com (8.14.3+Sun/8.14.3/Submit) id n4KEhmZ8002248; Wed, 20 May 2009 10:43:48 -0400 (EDT) Date: Wed, 20 May 2009 10:43:48 -0400 From: James Carlson Subject: Re: Draft of trove-2.0.4 LSARC/2009/262 In-reply-to: <4A141124.5040206@Sun.com> To: Michael Kearney Cc: margot , LSARC-ext@sun.com, PSARC-ext@sun.com Message-id: <18964.5924.330247.409291@gargle.gargle.HOWL> MIME-version: 1.0 X-Mailer: VM 7.01 under Emacs 21.3.1 Content-type: text/plain; charset=iso-8859-1 X-PMX-Version: 5.4.1.325704 References: <4A1354A0.2070601@sun.com> <4A141124.5040206@Sun.com> Content-Transfer-Encoding: 8bit X-MIME-Autoconverted: from quoted-printable to 8bit by sac.sfbay.sun.com id n4KEimIq003440 Status: RO Content-Length: 2839 Michael Kearney writes: > > There needs to more discussion to determine if it is critical that the > > ARC stability > > level be communicated to the Solaris end user for all the FOSS software > > that is being delivered. If so, a comprehensive solution needs to be > > formulated, whether it is a CLI, a man page, annotation embedded in > > the Javadocs > > (which will work for Sun products but you cant force that upstream). > Shouldn't the discussion take place before rendering an opinion and > setting a precedence? Yep; agreed. For what it's worth, I would vote for using native documentation and native stability indications where feasible, and adding our own notations only when the community lacks sufficient information. I don't think it makes sense to force communities that have their own stability traditions to conform to our mold, provided that the "communities" include those Sun customers who would also receive this software. One of the high level goals of this architecture process is to make sure that dependencies are documented, and expectations are understood both by suppliers and consumers. As long as that goal is reached in a consistent and unsurprising way, I don't really care whether it's done by way of 'man', 'pydoc', 'javadoc', or 'whatsupdoc.' The only time it matters is when crossing worlds. If users can depend on both Java and Python supplied interfaces (for instance), then they would need a decoder ring to understand what each one provides, and that might well lead to mistakes. Thus, the boundaries for these native stability interfaces need to be crystal clear. (That is to say: external protocols, file formats, command lines, and visible-to-those-outside-the-domain programming interfaces are likely all things that cannot be documented properly using native stability levels.) > > Up until now, most projects have not shipped man pages with jar > > files. This doesn´t seem to have been written down anywhere. With > > this case, we would like to make it explicit to not deliver man pages > > with jar files. This is setting precedent. > So, for Java projects (and all other types of projects where the > "natural" documentation doesn't > include a man page), no documentation of the interface stability is allowed? > We really should set the precedent for all types of projects, otherwise > we'll just be back here next > week to discuss Python, etc. I had thought that the actual vote in LSARC was 2-to-1 to allow man pages as an option. But I agree that it does need to be consistent so that we don't have to have this debate every few months. -- James Carlson, Solaris Networking Sun Microsystems / 35 Network Drive 71.232W Vox +1 781 442 2084 MS UBUR02-212 / Burlington MA 01803-2757 42.496N Fax +1 781 442 1677 From tdc@computer.org Wed May 20 11:29:37 2009 Received: from sunmail2sca.sfbay.sun.com (sunmail2sca.SFBay.Sun.COM [129.145.155.234]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4KITb4a008568 for ; Wed, 20 May 2009 11:29:37 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail2sca.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4KITa99011485; Wed, 20 May 2009 11:29:37 -0700 (PDT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJY00K13GPCM000@brm-avmta-1.central.sun.com>; Wed, 20 May 2009 12:29:36 -0600 (MDT) Received: from sca-ea-mail-3.sun.com ([192.18.43.21]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJY00FEDGPCH640@brm-avmta-1.central.sun.com>; Wed, 20 May 2009 12:29:36 -0600 (MDT) Received: from relay11i.sun.com (ip121.net129179-4.block1.us.syntegra.com [129.179.4.121]) by sca-ea-mail-3.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n4KIR8Ba018847; Wed, 20 May 2009 18:29:35 +0000 (GMT) Received: from mmp11es.mmp.us.syntegra.com ([160.41.208.11] [160.41.208.11]) by relay11i.sun.com with ESMTP id BT-MMP-2852254; Wed, 20 May 2009 18:29:35 +0000 (Z) Received: from relay13i.sun.com (relay13i.sun.com [129.179.4.123]) by mmp11es.mmp.us.syntegra.com with ESMTP id BT-MMP-26308562; Wed, 20 May 2009 18:29:28 +0000 (Z) Received: from a.mail.sonic.net ([64.142.16.245] [64.142.16.245]) by relay1i.sun.com with ESMTP id BT-MMP-4859303; Wed, 20 May 2009 18:29:28 +0000 (Z) Received: from [10.0.1.5] (c-98-210-99-213.hsd1.ca.comcast.net [98.210.99.213]) (authenticated bits=0) by a.mail.sonic.net (8.13.8.Beta0-Sonic/8.13.7) with ESMTP id n4KITR7r005412 (version=TLSv1/SSLv3 cipher=AES128-SHA bits=128 verify=NO); Wed, 20 May 2009 11:29:27 -0700 Date: Wed, 20 May 2009 11:29:27 -0700 From: Tom Childers Subject: Re: trove-2.0.4 [LSARC/2009/262] - Draft Minority Opinion In-reply-to: <4A133158.4010500@sun.com> To: "Mark A. Carlson" Cc: LSARC-ext@sun.com Message-id: MIME-version: 1.0 X-Mailer: Apple Mail (2.935.3) Content-type: text/plain; charset=US-ASCII; format=flowed; delsp=yes Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 X-Brightmail-Tracker: AAAAAA== X-Antispam: No, score=-1.1/5.0, scanned in 4.443sec at (localhost [127.0.0.1]) by smf-spamd v1.3.1 - http://smfs.sf.net/ References: <200904281656.n3SGuEVj009039@sac.sfbay.sun.com> <4A133158.4010500@sun.com> Status: RO Content-Length: 3680 Mark, This is really good. The bottom line seems to be: - if we build it, we will use our own interface stability classifications, and deliver them via language-specific documentation facilities - if someone else built it, and there is IF stability info, we'll support it via the language-specific documentation facilities - if someone else built it, but IF stability info is inadequate, we can add a man page, and urge the team to add IF stability info to the language- specific doc. Since man pages are the de facto language-specific IF doc for C/C++, can we simplify the third option to state: - if someone else built it, but there is inadequate IF stability info, we urge the team to add IF stability info to the language-specific doc. In other words, add a TCA to the opinion. I don't think we add value by requiring a man page in one specific situation. If man pages are not consistently generally available for Java/Python/etc., I don't think an occasional page will help anything. -tdc On May 19, 2009, at 3:23 PM, Mark A. Carlson wrote: > During the case discussion today, I took the AI to help Michael > Kearney draft > a minority opinion. There may be other minority opinions, but if > this looks > close to something you would sign on to, I am open to small changes. > > -- mark > > > 5. Minority Opinion > > Background > > It is not typical for programmers working with non C/C++/Assembler > files, such as Java Jar files, to determine the > Exported Interface stability level using the man command. Java > programmers depend on Javadoc, Python programmers > depend on pydoc and so forth to document interfaces and the > stability would best be indicated there. > Approval of OpenSolaris projects have been inconsistent in > preferring man pages or native documentation. This opinion seeks > to clarify the issue and define a policy for all such cases going > forward. > > Best Practice > > Case A - Sun Developed Components > > 1) Sun project team developing a Jar file shall document the > ARC interface classification in the native documentation. (i.e. > Javadocs) > > Case B - Components imported from external OSS Communities > > 1) The OSS Community documents the interface classification in > their native documentation > > a) OpenSolaris project team agrees with the classification > and supports it > - Javadoc or other native documentation required > (unchanged) > - No man page shall be allowed > > b) OpenSolaris project team disagrees with the > classification > - Javadoc or native documentation required, but > project team must change the OSS documentation > to match the project team's classification > - No man page shall be allowed > > 2) OSS Community does not document interface classification in > their native documentation > a) OpenSolaris project team is strongly encouraged to > update the native documentation to reflect the OpenSolaris project > team > classification. > - Changed Javadoc or other native documentation > required > - No man page shall be allowed > b) OpenSolaris project team cannot support deltas to the > native documentation > - Unchanged Javadoc or other native documentation > required > - A man page shall be provided > > _______________________________________________ > opensolaris-arc mailing list > opensolaris-arc@opensolaris.org > From margot.miller@sun.com Wed May 20 11:33:08 2009 Received: from sunmail4.singapore.sun.com (sunmail4.Singapore.Sun.COM [129.158.71.19]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4KIX6sE008635 for ; Wed, 20 May 2009 11:33:07 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail4.singapore.sun.com (8.13.4+Sun/8.13.3/ENSMAIL,v2.2) with ESMTP id n4KIWvEc005751 for <@sunmail2sca.sfbay.sun.com:LSARC-ext@sun.com>; Thu, 21 May 2009 02:33:05 +0800 (SGT) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJY00K0XGV4II00@nwk-avmta-1.sfbay.Sun.COM> for LSARC-ext@sun.com (ORCPT LSARC-ext@sun.com); Wed, 20 May 2009 11:33:04 -0700 (PDT) Received: from jurassic-x4600.sfbay.sun.com ([129.146.17.63]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJY0026CGV34U60@nwk-avmta-1.sfbay.Sun.COM> for LSARC-ext@sun.com (ORCPT LSARC-ext@sun.com); Wed, 20 May 2009 11:33:04 -0700 (PDT) Received: from [10.7.250.88] (punchin-client-10-7-250-88.SFBay.Sun.COM [10.7.250.88]) by jurassic-x4600.sfbay.sun.com (8.14.3+Sun/8.14.3) with ESMTP id n4KIX2PP438226; Wed, 20 May 2009 11:33:03 -0700 (PDT) Date: Wed, 20 May 2009 11:33:02 -0700 From: Margot Miller Subject: trove-2.0.4 LSARC/2009/262 To: LSARC-ext@sun.com, psarc-ext@sun.comom Message-id: <4A144CDE.1030101@sun.com> MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1; format=flowed Content-transfer-encoding: 8BIT X-PMX-Version: 5.4.1.325704 User-Agent: Thunderbird 2.0.0.17 (X11/20081023) Status: RO Content-Length: 5775 Hey All, Below is the updated opinion with feedback from James, Mark, and Mike. We only had three members vote on this during the meeting. There was an issue of quorum; we did not have quorum as one member was not formally declared on sabbatical. So I would like to conduct an email vote on this. If you are a LSARC please vote. This case is only addresses whether a man page should be shipped with a java jar file. It does not change the current process of project teams supplying native documentation. Nor does it set any additional requirements on native documentation. If a team decides to add some type of stability taxonomy to their native documentation (like the appserver) this case does not preclude that. On this last point- about not precluding stability levels in native documentation, we could state with this case that it is allowed. I have it below in the opinion as I thought there was consensus on that. Are others comfortable with having that in the opinion? Thanks Margot ****************** sun microsystems Systems Architecture Committee _________________________________________________________________ Subject: trove-2.0.4 Submitted by: Vivek Titamare File: LSARC/2009/262/opinion.txt Date: May, 2009 Committee: Margot Hackett Miller, Lloyd Chambers Minority: Mark Carlson Product Approval Committee: Solaris PAC solaris-pac-opinion@sun.com 1. Summary This project is one of the Linux familiarity cases; this one provides a library to do fast regular and primitive collections for Java. 2. Decision & Precedence Information The project is approved as specified in reference [1]. The project may be delivered in a minor release of Solaris. 3. Interfaces Exported Interfaces: __________________________________________________ | Interfaces Exported | |____________ ______ |____________ __ __|____________| |Interface | Classification | Comments| |_______________ __|_________________|_____________| | trove.jar | Uncommitted | | |SUNWtrove | Uncommitted | | |___________________|_________________|____________| Imported Interfaces: ______________________________________________________________ | Interfaces Exported | | |___________________|______________ __|________________________| |Interface | Classification | Comments | |_______________ __|_________________|________________________| | | SUNWj5dev | Committed | Java Development kit | | SUNWj5rt | Committed | Java Runtime library | | SUNWj6dev | Committed | Java Development kit | | SUNWj6rt | Committed | Java Runtime library | |___________________|_________________|________________________| 4. Opinion During review, the only real issue raised was whether this team should provide a man page in addition to the javadocs. The man page would basically give a brief description of the jar file, pointer to the javadocs, and state the interface stability of the jar file. Discussion ensued whether it makes sense to ship a man page with a jar file. Solaris developers expect man pages, but do Java developers? Is it worth the extra work to provide a man page and would Java developers even look for a man page. It was noted that this is not standard practice as most Java developers look for java documentation via javadocs, not via man. However, others stated that having a minimal man page for a java jar file would allow the interface classification to be visible to the end user and a few other ARC cases have already shipped man pages for jar files. There was discussion over the granularity of the jar file and does it make sense to have an interface stability for the overall jar. Currently, java has Public, Package, and Protected. There was debate as to whether that conveys enough of the stability of the jar and its methods to the developer. With all the FOSS that is being delivered into Solaris, projects are delivering in their native, natural form. This includes man pages, texinfo, html, and javadoc. So the problem isn't just with javadocs and jar files. There is quite a bit of FOSS out there with no interface stability in the external Sun documentation. This is not a problem for Sun project teams as they can always look at the interface tables in the ARC tables to determine stability level. Asking all java project teams to ship a man page in addition to javadocs doesn´t seem like the right solution and having some teams ship a man page and others not, does not provide consistency. There needs to more discussion to determine if it is critical that the ARC stability level be communicated to the Solaris end user for all the FOSS software that is being delivered. If so, a comprehensive solution needs to be formulated, whether it is a CLI, a man page, annotation embedded in the Javadocs (which will work for Sun products but you cant force that upstream). This is not being addressed in this case. Project teams can continue to ship documentation in their ¨natural¨form and if there is some stability suggested in that documentation that is fine. Up until now, most projects have not shipped man pages with jar files. This doesn´t seem to have been written down anywhere. With this case, we would like to make it explicit to not deliver man pages with jar files. This is setting precedent of ¨do not ship man pages with jar files.¨ This resulted in the below TCR. 5. Minority Opinion(s) Mark Carlson providing text 6. Advisory Information None. 7. Appendices 7.1. Appendix A: Technical Changes Required Do not ship man pages with Java jar files 7.2. Appendix B: Technical Changes Advised None. 7.3. Appendix C: Reference Material Unless stated otherwise, path names are relative to the case directory LSARC/2009/262 1) Project Proposal file: LSARC/2009/262 Copyright 2009 Sun Microsystems From margot.miller@sun.com Wed May 20 11:34:55 2009 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4KIYsaW008657; Wed, 20 May 2009 11:34:55 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail5.uk.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n4KIYnqv019655; Wed, 20 May 2009 19:34:54 +0100 (BST) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJY00L0LGY53N00@brm-avmta-1.central.sun.com>; Wed, 20 May 2009 12:34:53 -0600 (MDT) Received: from jurassic-x4600.sfbay.sun.com ([129.146.17.63]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJY00F1VGY2GY50@brm-avmta-1.central.sun.com>; Wed, 20 May 2009 12:34:51 -0600 (MDT) Received: from [10.7.250.88] (punchin-client-10-7-250-88.SFBay.Sun.COM [10.7.250.88]) by jurassic-x4600.sfbay.sun.com (8.14.3+Sun/8.14.3) with ESMTP id n4KIYopJ438674; Wed, 20 May 2009 11:34:50 -0700 (PDT) Date: Wed, 20 May 2009 11:34:49 -0700 From: Margot Miller Subject: trove-2.0.4 LSARC/2009/262 To: LSARC-ext@sun.com, psarc-ext@sun.com Message-id: <4A144D49.20702@sun.com> MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1; format=flowed Content-transfer-encoding: 8BIT X-PMX-Version: 5.4.1.325704 User-Agent: Thunderbird 2.0.0.17 (X11/20081023) Status: RO Content-Length: 5809 resending it- got psarc address wrong. Hey All, Below is the updated opinion with feedback from James, Mark, and Mike. We only had three members vote on this during the meeting. There was an issue of quorum; we did not have quorum as one member was not formally declared on sabbatical. So I would like to conduct an email vote on this. If you are a LSARC please vote. This case is only addresses whether a man page should be shipped with a java jar file. It does not change the current process of project teams supplying native documentation. Nor does it set any additional requirements on native documentation. If a team decides to add some type of stability taxonomy to their native documentation (like the appserver) this case does not preclude that. On this last point- about not precluding stability levels in native documentation, we could state with this case that it is allowed. I have it below in the opinion as I thought there was consensus on that. Are others comfortable with having that in the opinion? Thanks Margot ****************** sun microsystems Systems Architecture Committee _________________________________________________________________ Subject: trove-2.0.4 Submitted by: Vivek Titamare File: LSARC/2009/262/opinion.txt Date: May, 2009 Committee: Margot Hackett Miller, Lloyd Chambers Minority: Mark Carlson Product Approval Committee: Solaris PAC solaris-pac-opinion@sun.com 1. Summary This project is one of the Linux familiarity cases; this one provides a library to do fast regular and primitive collections for Java. 2. Decision & Precedence Information The project is approved as specified in reference [1]. The project may be delivered in a minor release of Solaris. 3. Interfaces Exported Interfaces: __________________________________________________ | Interfaces Exported | |____________ ______ |____________ __ __|____________| |Interface | Classification | Comments| |_______________ __|_________________|_____________| | trove.jar | Uncommitted | | |SUNWtrove | Uncommitted | | |___________________|_________________|____________| Imported Interfaces: ______________________________________________________________ | Interfaces Exported | | |___________________|______________ __|________________________| |Interface | Classification | Comments | |_______________ __|_________________|________________________| | | SUNWj5dev | Committed | Java Development kit | | SUNWj5rt | Committed | Java Runtime library | | SUNWj6dev | Committed | Java Development kit | | SUNWj6rt | Committed | Java Runtime library | |___________________|_________________|________________________| 4. Opinion During review, the only real issue raised was whether this team should provide a man page in addition to the javadocs. The man page would basically give a brief description of the jar file, pointer to the javadocs, and state the interface stability of the jar file. Discussion ensued whether it makes sense to ship a man page with a jar file. Solaris developers expect man pages, but do Java developers? Is it worth the extra work to provide a man page and would Java developers even look for a man page. It was noted that this is not standard practice as most Java developers look for java documentation via javadocs, not via man. However, others stated that having a minimal man page for a java jar file would allow the interface classification to be visible to the end user and a few other ARC cases have already shipped man pages for jar files. There was discussion over the granularity of the jar file and does it make sense to have an interface stability for the overall jar. Currently, java has Public, Package, and Protected. There was debate as to whether that conveys enough of the stability of the jar and its methods to the developer. With all the FOSS that is being delivered into Solaris, projects are delivering in their native, natural form. This includes man pages, texinfo, html, and javadoc. So the problem isn't just with javadocs and jar files. There is quite a bit of FOSS out there with no interface stability in the external Sun documentation. This is not a problem for Sun project teams as they can always look at the interface tables in the ARC tables to determine stability level. Asking all java project teams to ship a man page in addition to javadocs doesn´t seem like the right solution and having some teams ship a man page and others not, does not provide consistency. There needs to more discussion to determine if it is critical that the ARC stability level be communicated to the Solaris end user for all the FOSS software that is being delivered. If so, a comprehensive solution needs to be formulated, whether it is a CLI, a man page, annotation embedded in the Javadocs (which will work for Sun products but you cant force that upstream). This is not being addressed in this case. Project teams can continue to ship documentation in their ¨natural¨form and if there is some stability suggested in that documentation that is fine. Up until now, most projects have not shipped man pages with jar files. This doesn´t seem to have been written down anywhere. With this case, we would like to make it explicit to not deliver man pages with jar files. This is setting precedent of ¨do not ship man pages with jar files.¨ This resulted in the below TCR. 5. Minority Opinion(s) Mark Carlson providing text 6. Advisory Information None. 7. Appendices 7.1. Appendix A: Technical Changes Required Do not ship man pages with Java jar files 7.2. Appendix B: Technical Changes Advised None. 7.3. Appendix C: Reference Material Unless stated otherwise, path names are relative to the case directory LSARC/2009/262 1) Project Proposal file: LSARC/2009/262 Copyright 2009 Sun Microsystems From margot.miller@sun.com Wed May 20 11:34:55 2009 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4KIYsaW008657; Wed, 20 May 2009 11:34:55 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail5.uk.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n4KIYnqv019655; Wed, 20 May 2009 19:34:54 +0100 (BST) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJY00L0LGY53N00@brm-avmta-1.central.sun.com>; Wed, 20 May 2009 12:34:53 -0600 (MDT) Received: from jurassic-x4600.sfbay.sun.com ([129.146.17.63]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJY00F1VGY2GY50@brm-avmta-1.central.sun.com>; Wed, 20 May 2009 12:34:51 -0600 (MDT) Received: from [10.7.250.88] (punchin-client-10-7-250-88.SFBay.Sun.COM [10.7.250.88]) by jurassic-x4600.sfbay.sun.com (8.14.3+Sun/8.14.3) with ESMTP id n4KIYopJ438674; Wed, 20 May 2009 11:34:50 -0700 (PDT) Date: Wed, 20 May 2009 11:34:49 -0700 From: Margot Miller Subject: trove-2.0.4 LSARC/2009/262 To: LSARC-ext@sun.com, psarc-ext@sun.com Message-id: <4A144D49.20702@sun.com> MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1; format=flowed Content-transfer-encoding: 8BIT X-PMX-Version: 5.4.1.325704 User-Agent: Thunderbird 2.0.0.17 (X11/20081023) Status: RO Content-Length: 5809 resending it- got psarc address wrong. Hey All, Below is the updated opinion with feedback from James, Mark, and Mike. We only had three members vote on this during the meeting. There was an issue of quorum; we did not have quorum as one member was not formally declared on sabbatical. So I would like to conduct an email vote on this. If you are a LSARC please vote. This case is only addresses whether a man page should be shipped with a java jar file. It does not change the current process of project teams supplying native documentation. Nor does it set any additional requirements on native documentation. If a team decides to add some type of stability taxonomy to their native documentation (like the appserver) this case does not preclude that. On this last point- about not precluding stability levels in native documentation, we could state with this case that it is allowed. I have it below in the opinion as I thought there was consensus on that. Are others comfortable with having that in the opinion? Thanks Margot ****************** sun microsystems Systems Architecture Committee _________________________________________________________________ Subject: trove-2.0.4 Submitted by: Vivek Titamare File: LSARC/2009/262/opinion.txt Date: May, 2009 Committee: Margot Hackett Miller, Lloyd Chambers Minority: Mark Carlson Product Approval Committee: Solaris PAC solaris-pac-opinion@sun.com 1. Summary This project is one of the Linux familiarity cases; this one provides a library to do fast regular and primitive collections for Java. 2. Decision & Precedence Information The project is approved as specified in reference [1]. The project may be delivered in a minor release of Solaris. 3. Interfaces Exported Interfaces: __________________________________________________ | Interfaces Exported | |____________ ______ |____________ __ __|____________| |Interface | Classification | Comments| |_______________ __|_________________|_____________| | trove.jar | Uncommitted | | |SUNWtrove | Uncommitted | | |___________________|_________________|____________| Imported Interfaces: ______________________________________________________________ | Interfaces Exported | | |___________________|______________ __|________________________| |Interface | Classification | Comments | |_______________ __|_________________|________________________| | | SUNWj5dev | Committed | Java Development kit | | SUNWj5rt | Committed | Java Runtime library | | SUNWj6dev | Committed | Java Development kit | | SUNWj6rt | Committed | Java Runtime library | |___________________|_________________|________________________| 4. Opinion During review, the only real issue raised was whether this team should provide a man page in addition to the javadocs. The man page would basically give a brief description of the jar file, pointer to the javadocs, and state the interface stability of the jar file. Discussion ensued whether it makes sense to ship a man page with a jar file. Solaris developers expect man pages, but do Java developers? Is it worth the extra work to provide a man page and would Java developers even look for a man page. It was noted that this is not standard practice as most Java developers look for java documentation via javadocs, not via man. However, others stated that having a minimal man page for a java jar file would allow the interface classification to be visible to the end user and a few other ARC cases have already shipped man pages for jar files. There was discussion over the granularity of the jar file and does it make sense to have an interface stability for the overall jar. Currently, java has Public, Package, and Protected. There was debate as to whether that conveys enough of the stability of the jar and its methods to the developer. With all the FOSS that is being delivered into Solaris, projects are delivering in their native, natural form. This includes man pages, texinfo, html, and javadoc. So the problem isn't just with javadocs and jar files. There is quite a bit of FOSS out there with no interface stability in the external Sun documentation. This is not a problem for Sun project teams as they can always look at the interface tables in the ARC tables to determine stability level. Asking all java project teams to ship a man page in addition to javadocs doesn´t seem like the right solution and having some teams ship a man page and others not, does not provide consistency. There needs to more discussion to determine if it is critical that the ARC stability level be communicated to the Solaris end user for all the FOSS software that is being delivered. If so, a comprehensive solution needs to be formulated, whether it is a CLI, a man page, annotation embedded in the Javadocs (which will work for Sun products but you cant force that upstream). This is not being addressed in this case. Project teams can continue to ship documentation in their ¨natural¨form and if there is some stability suggested in that documentation that is fine. Up until now, most projects have not shipped man pages with jar files. This doesn´t seem to have been written down anywhere. With this case, we would like to make it explicit to not deliver man pages with jar files. This is setting precedent of ¨do not ship man pages with jar files.¨ This resulted in the below TCR. 5. Minority Opinion(s) Mark Carlson providing text 6. Advisory Information None. 7. Appendices 7.1. Appendix A: Technical Changes Required Do not ship man pages with Java jar files 7.2. Appendix B: Technical Changes Advised None. 7.3. Appendix C: Reference Material Unless stated otherwise, path names are relative to the case directory LSARC/2009/262 1) Project Proposal file: LSARC/2009/262 Copyright 2009 Sun Microsystems From carlsonj@phorcys.east.sun.com Wed May 20 11:54:49 2009 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4KIsmNZ009137 for ; Wed, 20 May 2009 11:54:49 -0700 (PDT) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by sunmail5.uk.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n4KIsgp5002402 for <@sunmail2sca.sfbay.sun.com:LSARC-ext@Sun.COM>; Wed, 20 May 2009 19:54:48 +0100 (BST) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJY00A07HVALF00@nwk-avmta-2.sfbay.sun.com> for LSARC-ext@Sun.COM (ORCPT LSARC-ext@Sun.COM); Wed, 20 May 2009 11:54:46 -0700 (PDT) Received: from dm-east-01.east.sun.com ([129.148.9.192]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJY008BGHV9Z540@nwk-avmta-2.sfbay.sun.com> for LSARC-ext@Sun.COM (ORCPT LSARC-ext@Sun.COM); Wed, 20 May 2009 11:54:45 -0700 (PDT) Received: from phorcys.east.sun.com (phorcys.East.Sun.COM [129.148.174.143]) by dm-east-01.east.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n4KIshwl051895; Wed, 20 May 2009 14:54:43 -0400 (EDT) Received: from phorcys.east.sun.com (phorcys.local [127.0.0.1]) by phorcys.east.sun.com (8.14.3+Sun/8.14.3) with ESMTP id n4KIrj92003606; Wed, 20 May 2009 14:53:45 -0400 (EDT) Received: (from carlsonj@localhost) by phorcys.east.sun.com (8.14.3+Sun/8.14.3/Submit) id n4KIrjTv003603; Wed, 20 May 2009 14:53:45 -0400 (EDT) Date: Wed, 20 May 2009 14:53:45 -0400 From: James Carlson Subject: Re: trove-2.0.4 LSARC/2009/262 In-reply-to: <4A144CDE.1030101@sun.com> To: Margot Miller Cc: LSARC-ext@sun.com, psarc-ext@sun.comom Message-id: <18964.20921.714323.132582@gargle.gargle.HOWL> MIME-version: 1.0 X-Mailer: VM 7.01 under Emacs 21.3.1 Content-type: text/plain; charset=us-ascii Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <4A144CDE.1030101@sun.com> Status: RO Content-Length: 1372 [I know you're looking for a vote here and not more discussion, but I don't think the text matches up yet.] Margot Miller writes: > There is quite a bit of FOSS out there with no interface stability > in the external Sun documentation. This is not a problem for Sun > project teams as they can always look at the interface tables in > the ARC tables to determine stability level. It's a problem for Sun project teams as well. "Public" stability levels require that the interface and its stability are properly documented. That reference documentation is part of the definition of "Public." The ARC materials help us review things to make sure that all is as expected, but I think the idea that we might _force_ project teams to dumpster dive through /shared/sac for basic interface documentation due to inadequacies in the delivered material is wrong on several counts. As with many things, this is not a peculiar problem with FOSS. It's a problem with differing kinds of documentation, regardless of who is the author and whether or not that author is a Sun employee. Jim "getting tired of FOSS claiming itself to be special" Carlson ;-} -- James Carlson, Solaris Networking Sun Microsystems / 35 Network Drive 71.232W Vox +1 781 442 2084 MS UBUR02-212 / Burlington MA 01803-2757 42.496N Fax +1 781 442 1677 From margot.miller@Sun.COM Wed May 20 12:16:06 2009 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4KJG5dt006742 for ; Wed, 20 May 2009 12:16:06 -0700 (PDT) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by sunmail5.uk.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n4KJFiIr015538; Wed, 20 May 2009 20:16:04 +0100 (BST) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJY00B03IUPTC00@nwk-avmta-2.sfbay.sun.com>; Wed, 20 May 2009 12:16:01 -0700 (PDT) Received: from jurassic-x4600.sfbay.sun.com ([129.146.17.63]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJY008CZIUPZ570@nwk-avmta-2.sfbay.sun.com>; Wed, 20 May 2009 12:16:01 -0700 (PDT) Received: from [10.7.250.88] (punchin-client-10-7-250-88.SFBay.Sun.COM [10.7.250.88]) by jurassic-x4600.sfbay.sun.com (8.14.3+Sun/8.14.3) with ESMTP id n4KJG0jS461805; Wed, 20 May 2009 12:16:01 -0700 (PDT) Date: Wed, 20 May 2009 12:16:00 -0700 From: Margot Miller Subject: Re: trove-2.0.4 LSARC/2009/262 In-reply-to: <18964.20921.714323.132582@gargle.gargle.HOWL> To: James Carlson Cc: LSARC-ext@Sun.COM, psarc-ext@sun.comom Message-id: <4A1456F0.7080602@sun.com> MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <4A144CDE.1030101@sun.com> <18964.20921.714323.132582@gargle.gargle.HOWL> User-Agent: Thunderbird 2.0.0.17 (X11/20081023) Status: RO Content-Length: 1292 Good point. Will omit that second line. Thanks Margot James Carlson wrote: > [I know you're looking for a vote here and not more discussion, but I > don't think the text matches up yet.] > > Margot Miller writes: > >> There is quite a bit of FOSS out there with no interface stability >> in the external Sun documentation. This is not a problem for Sun >> project teams as they can always look at the interface tables in >> the ARC tables to determine stability level. >> > > It's a problem for Sun project teams as well. "Public" stability > levels require that the interface and its stability are properly > documented. That reference documentation is part of the definition of > "Public." > > The ARC materials help us review things to make sure that all is as > expected, but I think the idea that we might _force_ project teams to > dumpster dive through /shared/sac for basic interface documentation > due to inadequacies in the delivered material is wrong on several > counts. > > As with many things, this is not a peculiar problem with FOSS. It's a > problem with differing kinds of documentation, regardless of who is > the author and whether or not that author is a Sun employee. > > Jim "getting tired of FOSS claiming itself to be special" Carlson ;-} > > From Mark.Carlson@sun.com Wed May 20 12:16:33 2009 Received: from newsunmail1brm.central.sun.com (newsunmail1brm.Central.Sun.COM [129.147.62.245]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4KJGW2L006761; Wed, 20 May 2009 12:16:32 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by newsunmail1brm.central.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4KJGVw9063995; Wed, 20 May 2009 13:16:32 -0600 (MDT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJY0020RIVJ5N00@brm-avmta-1.central.sun.com>; Wed, 20 May 2009 13:16:31 -0600 (MDT) Received: from brmea-mail-2.sun.com ([192.18.98.43]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJY00F6EIVJH070@brm-avmta-1.central.sun.com>; Wed, 20 May 2009 13:16:31 -0600 (MDT) Received: from fe-amer-10.sun.com ([192.18.109.80]) by brmea-mail-2.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n4KJGVLg004508; Wed, 20 May 2009 19:16:31 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJY00C00IC52A00@mail-amer.sun.com>; Wed, 20 May 2009 13:16:31 -0600 (MDT) Received: from Macintosh-335.local ([unknown] [129.150.33.177]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJY00ESZIV4EQB0@mail-amer.sun.com>; Wed, 20 May 2009 13:16:17 -0600 (MDT) Date: Wed, 20 May 2009 13:16:16 -0600 From: "Mark A. Carlson" Subject: Re: trove-2.0.4 LSARC/2009/262 In-reply-to: <4A144D49.20702@sun.com> Sender: Mark.Carlson@sun.com To: Margot Miller Cc: LSARC-ext@sun.com, PSARC-ext@sun.com Message-id: <4A145700.8060703@sun.com> MIME-version: 1.0 Content-type: text/plain; format=flowed; charset=ISO-8859-1 Content-transfer-encoding: 8BIT X-PMX-Version: 5.4.1.325704 References: <4A144D49.20702@sun.com> User-Agent: Thunderbird 2.0.0.21 (Macintosh/20090302) Status: RO Content-Length: 6592 Can you include the minority opinion in this? I sent it out yesterday. It's not clear what you are asking a vote for: 1) approve the project with this opinion or 2) vote for one: a) this opinion b) the minority opinion I would vote: 1) approve the project, but 2) b - the minority opinion over this one -- mark Margot Miller wrote: > resending it- got psarc address wrong. > > Hey All, > > Below is the updated opinion with feedback from James, Mark, and > Mike. > > We only had three members vote on this during the meeting. There > was an issue of quorum; we did not have quorum as one member > was not formally declared on sabbatical. > > So I would like to conduct an email vote on this. If you are > a LSARC please vote. > > This case is only addresses whether a man page should > be shipped with a java jar file. > > It does not change the current process of project teams > supplying native documentation. Nor does it set any > additional requirements on native documentation. If a team decides to > add some type of stability taxonomy > to their native documentation (like the appserver) this > case does not preclude that. > On this last point- about not precluding stability levels in native > documentation, we could state with this case that it is allowed. I have > it below in the opinion as I thought there was consensus > on that. Are others comfortable with having that > in the opinion? > > > Thanks > Margot > > ****************** > > > sun > microsystems Systems Architecture Committee > > _________________________________________________________________ > > Subject: trove-2.0.4 > > Submitted by: Vivek Titamare > > File: LSARC/2009/262/opinion.txt > > Date: May, 2009 > > Committee: Margot Hackett Miller, Lloyd Chambers > Minority: Mark Carlson > > > Product Approval Committee: > Solaris PAC > solaris-pac-opinion@sun.com > > 1. Summary > > This project is one of the Linux familiarity cases; this one provides > a library to do fast regular and primitive collections for > Java. > > 2. Decision & Precedence Information > > The project is approved as specified in reference [1]. > > The project may be delivered in a minor release of Solaris. > > 3. Interfaces > > Exported Interfaces: > > __________________________________________________ > | Interfaces Exported | > |____________ ______ |____________ __ __|____________| > |Interface | Classification | Comments| > |_______________ __|_________________|_____________| > | trove.jar | Uncommitted | | > |SUNWtrove | Uncommitted | | > |___________________|_________________|____________| > > > Imported Interfaces: > > ______________________________________________________________ > | Interfaces Exported | | > |___________________|______________ __|________________________| > |Interface | Classification | Comments | > |_______________ __|_________________|________________________| > | > | SUNWj5dev | Committed | Java Development kit | > | SUNWj5rt | Committed | Java Runtime library | > | SUNWj6dev | Committed | Java Development kit | > | SUNWj6rt | Committed | Java Runtime library | > |___________________|_________________|________________________| > > > > > 4. Opinion > > During review, the only real issue raised was whether this team > should provide a man page in addition to the javadocs. The man > page would basically give a brief description of the jar file, > pointer to the javadocs, and state the interface stability of the jar > file. > Discussion ensued whether it makes sense to ship a man page > with a jar file. Solaris developers expect man pages, but do > Java developers? Is it worth the extra work to provide a man page > and would Java developers even look for a man page. > > It was noted that this is not standard practice as most Java > developers look > for java documentation via javadocs, not via man. However, others > stated that > having a minimal man page for a java jar file would allow the interface > classification to be visible to the end user and a few other ARC cases > have > already shipped man pages for jar files. > > There was discussion over the granularity of the jar file and does > it make sense to have an interface stability for the overall jar. > Currently, > java has Public, Package, and Protected. There was debate as to > whether that conveys enough of the stability of the jar and its > methods to the > developer. > > With all the FOSS that is being delivered into Solaris, projects are > delivering in their native, natural form. This includes man pages, > texinfo, > html, and javadoc. So the problem isn't just with javadocs and jar files. > There is quite a bit of FOSS out there with no interface stability > in the external Sun documentation. This is not a problem for Sun > project teams as they can always look at the interface tables in > the ARC tables to determine stability level. > > Asking all java project teams to ship a man page in addition to > javadocs doesn´t > seem like the right solution and having some teams ship a man page > and others not, does not provide consistency. > > There needs to more discussion to determine if it is critical that the > ARC stability > level be communicated to the Solaris end user for all the FOSS software > that is being delivered. If so, a comprehensive solution needs to be > formulated, whether it is a CLI, a man page, annotation embedded in > the Javadocs > (which will work for Sun products but you cant force that upstream). > This is not being addressed in this case. Project teams can continue > to ship documentation in their ¨natural¨form and if there is some > stability suggested in that documentation that is fine. > Up until now, most projects have not shipped man pages with jar > files. This doesn´t seem to have been written down anywhere. With > this case, we would like to make it explicit to not deliver man pages > with jar files. This is setting precedent of ¨do not ship man pages > with jar files.¨ This resulted in the below TCR. > > 5. Minority Opinion(s) > > Mark Carlson providing text > > 6. Advisory Information > > None. > > 7. Appendices > > 7.1. Appendix A: Technical Changes Required > > Do not ship man pages with Java jar files > > 7.2. Appendix B: Technical Changes Advised > > None. > > 7.3. Appendix C: Reference Material > > Unless stated otherwise, path names are relative to the case > directory LSARC/2009/262 > > 1) Project Proposal file: > > > LSARC/2009/262 Copyright 2009 Sun Microsystems > _______________________________________________ > opensolaris-arc mailing list > opensolaris-arc@opensolaris.org From Mark.Carlson@sun.com Wed May 20 12:16:33 2009 Received: from newsunmail1brm.central.sun.com (newsunmail1brm.Central.Sun.COM [129.147.62.245]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4KJGW2L006761; Wed, 20 May 2009 12:16:32 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by newsunmail1brm.central.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4KJGVw9063995; Wed, 20 May 2009 13:16:32 -0600 (MDT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJY0020RIVJ5N00@brm-avmta-1.central.sun.com>; Wed, 20 May 2009 13:16:31 -0600 (MDT) Received: from brmea-mail-2.sun.com ([192.18.98.43]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJY00F6EIVJH070@brm-avmta-1.central.sun.com>; Wed, 20 May 2009 13:16:31 -0600 (MDT) Received: from fe-amer-10.sun.com ([192.18.109.80]) by brmea-mail-2.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n4KJGVLg004508; Wed, 20 May 2009 19:16:31 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJY00C00IC52A00@mail-amer.sun.com>; Wed, 20 May 2009 13:16:31 -0600 (MDT) Received: from Macintosh-335.local ([unknown] [129.150.33.177]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJY00ESZIV4EQB0@mail-amer.sun.com>; Wed, 20 May 2009 13:16:17 -0600 (MDT) Date: Wed, 20 May 2009 13:16:16 -0600 From: "Mark A. Carlson" Subject: Re: trove-2.0.4 LSARC/2009/262 In-reply-to: <4A144D49.20702@sun.com> Sender: Mark.Carlson@sun.com To: Margot Miller Cc: LSARC-ext@sun.com, PSARC-ext@sun.com Message-id: <4A145700.8060703@sun.com> MIME-version: 1.0 Content-type: text/plain; format=flowed; charset=ISO-8859-1 Content-transfer-encoding: 8BIT X-PMX-Version: 5.4.1.325704 References: <4A144D49.20702@sun.com> User-Agent: Thunderbird 2.0.0.21 (Macintosh/20090302) Status: RO Content-Length: 6592 Can you include the minority opinion in this? I sent it out yesterday. It's not clear what you are asking a vote for: 1) approve the project with this opinion or 2) vote for one: a) this opinion b) the minority opinion I would vote: 1) approve the project, but 2) b - the minority opinion over this one -- mark Margot Miller wrote: > resending it- got psarc address wrong. > > Hey All, > > Below is the updated opinion with feedback from James, Mark, and > Mike. > > We only had three members vote on this during the meeting. There > was an issue of quorum; we did not have quorum as one member > was not formally declared on sabbatical. > > So I would like to conduct an email vote on this. If you are > a LSARC please vote. > > This case is only addresses whether a man page should > be shipped with a java jar file. > > It does not change the current process of project teams > supplying native documentation. Nor does it set any > additional requirements on native documentation. If a team decides to > add some type of stability taxonomy > to their native documentation (like the appserver) this > case does not preclude that. > On this last point- about not precluding stability levels in native > documentation, we could state with this case that it is allowed. I have > it below in the opinion as I thought there was consensus > on that. Are others comfortable with having that > in the opinion? > > > Thanks > Margot > > ****************** > > > sun > microsystems Systems Architecture Committee > > _________________________________________________________________ > > Subject: trove-2.0.4 > > Submitted by: Vivek Titamare > > File: LSARC/2009/262/opinion.txt > > Date: May, 2009 > > Committee: Margot Hackett Miller, Lloyd Chambers > Minority: Mark Carlson > > > Product Approval Committee: > Solaris PAC > solaris-pac-opinion@sun.com > > 1. Summary > > This project is one of the Linux familiarity cases; this one provides > a library to do fast regular and primitive collections for > Java. > > 2. Decision & Precedence Information > > The project is approved as specified in reference [1]. > > The project may be delivered in a minor release of Solaris. > > 3. Interfaces > > Exported Interfaces: > > __________________________________________________ > | Interfaces Exported | > |____________ ______ |____________ __ __|____________| > |Interface | Classification | Comments| > |_______________ __|_________________|_____________| > | trove.jar | Uncommitted | | > |SUNWtrove | Uncommitted | | > |___________________|_________________|____________| > > > Imported Interfaces: > > ______________________________________________________________ > | Interfaces Exported | | > |___________________|______________ __|________________________| > |Interface | Classification | Comments | > |_______________ __|_________________|________________________| > | > | SUNWj5dev | Committed | Java Development kit | > | SUNWj5rt | Committed | Java Runtime library | > | SUNWj6dev | Committed | Java Development kit | > | SUNWj6rt | Committed | Java Runtime library | > |___________________|_________________|________________________| > > > > > 4. Opinion > > During review, the only real issue raised was whether this team > should provide a man page in addition to the javadocs. The man > page would basically give a brief description of the jar file, > pointer to the javadocs, and state the interface stability of the jar > file. > Discussion ensued whether it makes sense to ship a man page > with a jar file. Solaris developers expect man pages, but do > Java developers? Is it worth the extra work to provide a man page > and would Java developers even look for a man page. > > It was noted that this is not standard practice as most Java > developers look > for java documentation via javadocs, not via man. However, others > stated that > having a minimal man page for a java jar file would allow the interface > classification to be visible to the end user and a few other ARC cases > have > already shipped man pages for jar files. > > There was discussion over the granularity of the jar file and does > it make sense to have an interface stability for the overall jar. > Currently, > java has Public, Package, and Protected. There was debate as to > whether that conveys enough of the stability of the jar and its > methods to the > developer. > > With all the FOSS that is being delivered into Solaris, projects are > delivering in their native, natural form. This includes man pages, > texinfo, > html, and javadoc. So the problem isn't just with javadocs and jar files. > There is quite a bit of FOSS out there with no interface stability > in the external Sun documentation. This is not a problem for Sun > project teams as they can always look at the interface tables in > the ARC tables to determine stability level. > > Asking all java project teams to ship a man page in addition to > javadocs doesn´t > seem like the right solution and having some teams ship a man page > and others not, does not provide consistency. > > There needs to more discussion to determine if it is critical that the > ARC stability > level be communicated to the Solaris end user for all the FOSS software > that is being delivered. If so, a comprehensive solution needs to be > formulated, whether it is a CLI, a man page, annotation embedded in > the Javadocs > (which will work for Sun products but you cant force that upstream). > This is not being addressed in this case. Project teams can continue > to ship documentation in their ¨natural¨form and if there is some > stability suggested in that documentation that is fine. > Up until now, most projects have not shipped man pages with jar > files. This doesn´t seem to have been written down anywhere. With > this case, we would like to make it explicit to not deliver man pages > with jar files. This is setting precedent of ¨do not ship man pages > with jar files.¨ This resulted in the below TCR. > > 5. Minority Opinion(s) > > Mark Carlson providing text > > 6. Advisory Information > > None. > > 7. Appendices > > 7.1. Appendix A: Technical Changes Required > > Do not ship man pages with Java jar files > > 7.2. Appendix B: Technical Changes Advised > > None. > > 7.3. Appendix C: Reference Material > > Unless stated otherwise, path names are relative to the case > directory LSARC/2009/262 > > 1) Project Proposal file: > > > LSARC/2009/262 Copyright 2009 Sun Microsystems > _______________________________________________ > opensolaris-arc mailing list > opensolaris-arc@opensolaris.org From margot.miller@sun.com Wed May 20 12:42:04 2009 Received: from newsunmail1brm.central.sun.com (newsunmail1brm.Central.Sun.COM [129.147.62.245]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4KJg3ZJ007679 for ; Wed, 20 May 2009 12:42:03 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by newsunmail1brm.central.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4KJg17a011066; Wed, 20 May 2009 13:42:03 -0600 (MDT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJY0041BK22RU00@brm-avmta-1.central.sun.com>; Wed, 20 May 2009 13:42:02 -0600 (MDT) Received: from jurassic-x4600.sfbay.sun.com ([129.146.17.59]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJY00FOUK21H780@brm-avmta-1.central.sun.com>; Wed, 20 May 2009 13:42:01 -0600 (MDT) Received: from [10.7.250.88] (punchin-client-10-7-250-88.SFBay.Sun.COM [10.7.250.88]) by jurassic-x4600.sfbay.sun.com (8.14.3+Sun/8.14.3) with ESMTP id n4KJg0be502498; Wed, 20 May 2009 12:42:00 -0700 (PDT) Date: Wed, 20 May 2009 12:42:00 -0700 From: Margot Miller Subject: Re: trove-2.0.4 [LSARC/2009/262] - Draft Minority Opinion In-reply-to: <4A133158.4010500@sun.com> To: "Mark A. Carlson" Cc: LSARC-ext@sun.com, psarc-ext@sun.comom Message-id: <4A145D08.3040707@sun.com> MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <200904281656.n3SGuEVj009039@sac.sfbay.sun.com> <4A133158.4010500@sun.com> User-Agent: Thunderbird 2.0.0.17 (X11/20081023) Status: RO Content-Length: 3435 Mark, In this below scenario 2b, does it mean that if a project team is not willing to change the native docs, then they must supply a man page? 2) OSS Community does not document interface classification in their native documentation a) OpenSolaris project team is strongly encouraged to update the native documentation to reflect the OpenSolaris project team classification. - Changed Javadoc or other native documentation required - No man page shall be allowed b) OpenSolaris project team cannot support deltas to the native documentation - Unchanged Javadoc or other native documentation required - A man page shall be provided Thanks Margot Mark A. Carlson wrote: > During the case discussion today, I took the AI to help Michael > Kearney draft > a minority opinion. There may be other minority opinions, but if this > looks > close to something you would sign on to, I am open to small changes. > > -- mark > > > 5. Minority Opinion > > Background > > It is not typical for programmers working with non C/C++/Assembler > files, such as Java Jar files, to determine the > Exported Interface stability level using the man command. Java > programmers depend on Javadoc, Python programmers > depend on pydoc and so forth to document interfaces and the > stability would best be indicated there. > Approval of OpenSolaris projects have been inconsistent in > preferring man pages or native documentation. This opinion seeks > to clarify the issue and define a policy for all such cases going > forward. > > Best Practice > > Case A - Sun Developed Components > > 1) Sun project team developing a Jar file shall document the > ARC interface classification in the native documentation. (i.e. > Javadocs) > > Case B - Components imported from external OSS Communities > > 1) The OSS Community documents the interface classification in > their native documentation > > a) OpenSolaris project team agrees with the classification > and supports it > - Javadoc or other native documentation required > (unchanged) > - No man page shall be allowed > > b) OpenSolaris project team disagrees with the > classification > - Javadoc or native documentation required, but > project team must change the OSS documentation > to match the project team's classification > - No man page shall be allowed > > 2) OSS Community does not document interface classification in > their native documentation > a) OpenSolaris project team is strongly encouraged to > update the native documentation to reflect the OpenSolaris project > team > classification. > - Changed Javadoc or other native documentation required > - No man page shall be allowed > b) OpenSolaris project team cannot support deltas to the > native documentation > - Unchanged Javadoc or other native documentation > required > - A man page shall be provided > > _______________________________________________ > opensolaris-arc mailing list > opensolaris-arc@opensolaris.org From Mark.Carlson@sun.com Wed May 20 12:56:37 2009 Received: from newsunmail1brm.central.sun.com (newsunmail1brm.Central.Sun.COM [129.147.62.245]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4KJubOs008461; Wed, 20 May 2009 12:56:37 -0700 (PDT) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by newsunmail1brm.central.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4KJuaql018556; Wed, 20 May 2009 13:56:36 -0600 (MDT) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJY00E01KQB9P00@nwk-avmta-2.sfbay.sun.com>; Wed, 20 May 2009 12:56:35 -0700 (PDT) Received: from brmea-mail-1.sun.com ([192.18.98.31]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJY008TFKQBZ2A0@nwk-avmta-2.sfbay.sun.com>; Wed, 20 May 2009 12:56:35 -0700 (PDT) Received: from fe-amer-09.sun.com ([192.18.109.79]) by brmea-mail-1.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n4KJuYWs029223; Wed, 20 May 2009 19:56:34 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJY00800KG39300@mail-amer.sun.com>; Wed, 20 May 2009 13:56:34 -0600 (MDT) Received: from Macintosh-335.local ([unknown] [129.150.33.177]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJY009WEKQ8AQ90@mail-amer.sun.com>; Wed, 20 May 2009 13:56:33 -0600 (MDT) Date: Wed, 20 May 2009 13:56:32 -0600 From: "Mark A. Carlson" Subject: Re: trove-2.0.4 [LSARC/2009/262] - Draft Minority Opinion In-reply-to: <4A145D08.3040707@sun.com> Sender: Mark.Carlson@sun.com To: Margot Miller Cc: LSARC-ext@sun.com, PSARC-ext@sun.com Message-id: <4A146070.8060004@sun.com> MIME-version: 1.0 Content-type: multipart/alternative; boundary="Boundary_(ID_BNIsI49VmSk+aUX852mSCQ)" X-PMX-Version: 5.4.1.325704 References: <200904281656.n3SGuEVj009039@sac.sfbay.sun.com> <4A133158.4010500@sun.com> <4A145D08.3040707@sun.com> User-Agent: Thunderbird 2.0.0.21 (Macintosh/20090302) Status: RO Content-Length: 12387 This is a multi-part message in MIME format. --Boundary_(ID_BNIsI49VmSk+aUX852mSCQ) Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT Margot Miller wrote: > Mark, > > In this below scenario 2b, does it mean that if a project team > is not willing to change the native docs, then they must supply > a man page? Yes. Otherwise this case will set the very bad precedent (in my mind) that projects are not required to publicly document their OpenSolaris ARC interface classifications. I am not necessarily wedded to man pages but making them grep through ARC materials for this information is not acceptable as Jim Carlson states. -- mark > > > 2) OSS Community does not document interface classification in > their native documentation > a) OpenSolaris project team is strongly encouraged to > update the native documentation to reflect the OpenSolaris project > team > classification. > - Changed Javadoc or other native documentation required > - No man page shall be allowed > b) OpenSolaris project team cannot support deltas to the > native documentation > - Unchanged Javadoc or other native documentation > required > - A man page shall be provided > > Thanks > Margot > > > Mark A. Carlson wrote: >> During the case discussion today, I took the AI to help Michael >> Kearney draft >> a minority opinion. There may be other minority opinions, but if this >> looks >> close to something you would sign on to, I am open to small changes. >> >> -- mark >> >> >> 5. Minority Opinion >> >> Background >> >> It is not typical for programmers working with non C/C++/Assembler >> files, such as Java Jar files, to determine the >> Exported Interface stability level using the man command. Java >> programmers depend on Javadoc, Python programmers >> depend on pydoc and so forth to document interfaces and the >> stability would best be indicated there. Approval of >> OpenSolaris projects have been inconsistent in >> preferring man pages or native documentation. This opinion seeks >> to clarify the issue and define a policy for all such cases going >> forward. >> >> Best Practice >> >> Case A - Sun Developed Components >> >> 1) Sun project team developing a Jar file shall document the >> ARC interface classification in the native documentation. (i.e. >> Javadocs) >> >> Case B - Components imported from external OSS Communities >> >> 1) The OSS Community documents the interface classification in >> their native documentation >> >> a) OpenSolaris project team agrees with the classification >> and supports it >> - Javadoc or other native documentation required >> (unchanged) >> - No man page shall be allowed >> >> b) OpenSolaris project team disagrees with the >> classification >> - Javadoc or native documentation required, but >> project team must change the OSS documentation >> to match the project team's classification >> - No man page shall be allowed >> >> 2) OSS Community does not document interface classification in >> their native documentation >> a) OpenSolaris project team is strongly encouraged to >> update the native documentation to reflect the OpenSolaris project >> team >> classification. >> - Changed Javadoc or other native documentation >> required >> - No man page shall be allowed >> b) OpenSolaris project team cannot support deltas to the >> native documentation >> - Unchanged Javadoc or other native documentation >> required >> - A man page shall be provided >> >> _______________________________________________ >> opensolaris-arc mailing list >> opensolaris-arc@opensolaris.org > -- * Mark A. Carlson * Sr. Architect *Systems Group* Phone x69559 / 303-223-6139 Email Mark.Carlson@Sun.COM --Boundary_(ID_BNIsI49VmSk+aUX852mSCQ) Content-type: text/html; CHARSET=US-ASCII Content-transfer-encoding: 7BIT Margot Miller wrote:
Mark,

In this below scenario 2b, does it mean that if a project team
is not willing to change the native docs, then they must supply
a man page?
Yes. Otherwise this case will set the very bad precedent (in my mind)
that projects are not required to publicly document their OpenSolaris
ARC interface classifications.

I am not necessarily wedded to man pages but making them grep
through ARC materials for this information is not acceptable as
Jim Carlson states.

-- mark


       2) OSS Community does not document interface classification in
    their native documentation
            a) OpenSolaris project team is strongly encouraged to
    update the native documentation to reflect the OpenSolaris project
    team
            classification.
                - Changed Javadoc or other native documentation required
                - No man page shall be allowed
            b) OpenSolaris project team cannot support deltas to the
    native documentation
                - Unchanged Javadoc or other native documentation required
                - A man page shall be provided

Thanks
Margot


Mark A. Carlson wrote:
During the case discussion today, I took the AI to help Michael Kearney draft
a minority opinion. There may be other minority opinions, but if this looks
close to something you would sign on to, I am open to small changes.

-- mark


 5. Minority Opinion

     Background

     It is not typical for programmers working with non C/C++/Assembler
     files, such as Java Jar files, to determine the
     Exported Interface stability level using the man command.  Java
     programmers depend on Javadoc, Python programmers
     depend on pydoc and so forth to document interfaces and the
     stability would best be indicated there.      Approval of OpenSolaris projects have been inconsistent in
     preferring man pages or native documentation.  This opinion seeks
     to clarify the issue and define a policy for all such cases going
     forward.

     Best Practice

     Case A - Sun Developed Components

         1) Sun project team developing a Jar file shall document the
     ARC interface classification in the native documentation. (i.e.
     Javadocs)

     Case B - Components imported from external OSS Communities

         1) The OSS Community documents the interface classification in
     their native documentation

             a) OpenSolaris project team agrees with the classification
     and supports it
                 - Javadoc or other native documentation required
     (unchanged)
                 - No man page shall be allowed

             b) OpenSolaris project team disagrees with the classification
                 - Javadoc or native documentation required, but
     project team must change the OSS documentation
                 to match the project team's classification
                 - No man page shall be allowed

        2) OSS Community does not document interface classification in
     their native documentation
             a) OpenSolaris project team is strongly encouraged to
     update the native documentation to reflect the OpenSolaris project
     team
             classification.
                 - Changed Javadoc or other native documentation required
                 - No man page shall be allowed
             b) OpenSolaris project team cannot support deltas to the
     native documentation
                 - Unchanged Javadoc or other native documentation required
                 - A man page shall be provided

_______________________________________________
opensolaris-arc mailing list
opensolaris-arc@opensolaris.org


--
Mark A. Carlson
Sr. Architect

Systems Group
Phone x69559 / 303-223-6139
Email Mark.Carlson@Sun.COM

--Boundary_(ID_BNIsI49VmSk+aUX852mSCQ)-- From Mark.Carlson@sun.com Wed May 20 12:56:37 2009 Received: from newsunmail1brm.central.sun.com (newsunmail1brm.Central.Sun.COM [129.147.62.245]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4KJubOs008461; Wed, 20 May 2009 12:56:37 -0700 (PDT) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by newsunmail1brm.central.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4KJuaql018556; Wed, 20 May 2009 13:56:36 -0600 (MDT) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJY00E01KQB9P00@nwk-avmta-2.sfbay.sun.com>; Wed, 20 May 2009 12:56:35 -0700 (PDT) Received: from brmea-mail-1.sun.com ([192.18.98.31]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJY008TFKQBZ2A0@nwk-avmta-2.sfbay.sun.com>; Wed, 20 May 2009 12:56:35 -0700 (PDT) Received: from fe-amer-09.sun.com ([192.18.109.79]) by brmea-mail-1.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n4KJuYWs029223; Wed, 20 May 2009 19:56:34 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJY00800KG39300@mail-amer.sun.com>; Wed, 20 May 2009 13:56:34 -0600 (MDT) Received: from Macintosh-335.local ([unknown] [129.150.33.177]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJY009WEKQ8AQ90@mail-amer.sun.com>; Wed, 20 May 2009 13:56:33 -0600 (MDT) Date: Wed, 20 May 2009 13:56:32 -0600 From: "Mark A. Carlson" Subject: Re: trove-2.0.4 [LSARC/2009/262] - Draft Minority Opinion In-reply-to: <4A145D08.3040707@sun.com> Sender: Mark.Carlson@sun.com To: Margot Miller Cc: LSARC-ext@sun.com, PSARC-ext@sun.com Message-id: <4A146070.8060004@sun.com> MIME-version: 1.0 Content-type: multipart/alternative; boundary="Boundary_(ID_BNIsI49VmSk+aUX852mSCQ)" X-PMX-Version: 5.4.1.325704 References: <200904281656.n3SGuEVj009039@sac.sfbay.sun.com> <4A133158.4010500@sun.com> <4A145D08.3040707@sun.com> User-Agent: Thunderbird 2.0.0.21 (Macintosh/20090302) Status: RO Content-Length: 12387 This is a multi-part message in MIME format. --Boundary_(ID_BNIsI49VmSk+aUX852mSCQ) Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT Margot Miller wrote: > Mark, > > In this below scenario 2b, does it mean that if a project team > is not willing to change the native docs, then they must supply > a man page? Yes. Otherwise this case will set the very bad precedent (in my mind) that projects are not required to publicly document their OpenSolaris ARC interface classifications. I am not necessarily wedded to man pages but making them grep through ARC materials for this information is not acceptable as Jim Carlson states. -- mark > > > 2) OSS Community does not document interface classification in > their native documentation > a) OpenSolaris project team is strongly encouraged to > update the native documentation to reflect the OpenSolaris project > team > classification. > - Changed Javadoc or other native documentation required > - No man page shall be allowed > b) OpenSolaris project team cannot support deltas to the > native documentation > - Unchanged Javadoc or other native documentation > required > - A man page shall be provided > > Thanks > Margot > > > Mark A. Carlson wrote: >> During the case discussion today, I took the AI to help Michael >> Kearney draft >> a minority opinion. There may be other minority opinions, but if this >> looks >> close to something you would sign on to, I am open to small changes. >> >> -- mark >> >> >> 5. Minority Opinion >> >> Background >> >> It is not typical for programmers working with non C/C++/Assembler >> files, such as Java Jar files, to determine the >> Exported Interface stability level using the man command. Java >> programmers depend on Javadoc, Python programmers >> depend on pydoc and so forth to document interfaces and the >> stability would best be indicated there. Approval of >> OpenSolaris projects have been inconsistent in >> preferring man pages or native documentation. This opinion seeks >> to clarify the issue and define a policy for all such cases going >> forward. >> >> Best Practice >> >> Case A - Sun Developed Components >> >> 1) Sun project team developing a Jar file shall document the >> ARC interface classification in the native documentation. (i.e. >> Javadocs) >> >> Case B - Components imported from external OSS Communities >> >> 1) The OSS Community documents the interface classification in >> their native documentation >> >> a) OpenSolaris project team agrees with the classification >> and supports it >> - Javadoc or other native documentation required >> (unchanged) >> - No man page shall be allowed >> >> b) OpenSolaris project team disagrees with the >> classification >> - Javadoc or native documentation required, but >> project team must change the OSS documentation >> to match the project team's classification >> - No man page shall be allowed >> >> 2) OSS Community does not document interface classification in >> their native documentation >> a) OpenSolaris project team is strongly encouraged to >> update the native documentation to reflect the OpenSolaris project >> team >> classification. >> - Changed Javadoc or other native documentation >> required >> - No man page shall be allowed >> b) OpenSolaris project team cannot support deltas to the >> native documentation >> - Unchanged Javadoc or other native documentation >> required >> - A man page shall be provided >> >> _______________________________________________ >> opensolaris-arc mailing list >> opensolaris-arc@opensolaris.org > -- * Mark A. Carlson * Sr. Architect *Systems Group* Phone x69559 / 303-223-6139 Email Mark.Carlson@Sun.COM --Boundary_(ID_BNIsI49VmSk+aUX852mSCQ) Content-type: text/html; CHARSET=US-ASCII Content-transfer-encoding: 7BIT Margot Miller wrote:
Mark,

In this below scenario 2b, does it mean that if a project team
is not willing to change the native docs, then they must supply
a man page?
Yes. Otherwise this case will set the very bad precedent (in my mind)
that projects are not required to publicly document their OpenSolaris
ARC interface classifications.

I am not necessarily wedded to man pages but making them grep
through ARC materials for this information is not acceptable as
Jim Carlson states.

-- mark


       2) OSS Community does not document interface classification in
    their native documentation
            a) OpenSolaris project team is strongly encouraged to
    update the native documentation to reflect the OpenSolaris project
    team
            classification.
                - Changed Javadoc or other native documentation required
                - No man page shall be allowed
            b) OpenSolaris project team cannot support deltas to the
    native documentation
                - Unchanged Javadoc or other native documentation required
                - A man page shall be provided

Thanks
Margot


Mark A. Carlson wrote:
During the case discussion today, I took the AI to help Michael Kearney draft
a minority opinion. There may be other minority opinions, but if this looks
close to something you would sign on to, I am open to small changes.

-- mark


 5. Minority Opinion

     Background

     It is not typical for programmers working with non C/C++/Assembler
     files, such as Java Jar files, to determine the
     Exported Interface stability level using the man command.  Java
     programmers depend on Javadoc, Python programmers
     depend on pydoc and so forth to document interfaces and the
     stability would best be indicated there.      Approval of OpenSolaris projects have been inconsistent in
     preferring man pages or native documentation.  This opinion seeks
     to clarify the issue and define a policy for all such cases going
     forward.

     Best Practice

     Case A - Sun Developed Components

         1) Sun project team developing a Jar file shall document the
     ARC interface classification in the native documentation. (i.e.
     Javadocs)

     Case B - Components imported from external OSS Communities

         1) The OSS Community documents the interface classification in
     their native documentation

             a) OpenSolaris project team agrees with the classification
     and supports it
                 - Javadoc or other native documentation required
     (unchanged)
                 - No man page shall be allowed

             b) OpenSolaris project team disagrees with the classification
                 - Javadoc or native documentation required, but
     project team must change the OSS documentation
                 to match the project team's classification
                 - No man page shall be allowed

        2) OSS Community does not document interface classification in
     their native documentation
             a) OpenSolaris project team is strongly encouraged to
     update the native documentation to reflect the OpenSolaris project
     team
             classification.
                 - Changed Javadoc or other native documentation required
                 - No man page shall be allowed
             b) OpenSolaris project team cannot support deltas to the
     native documentation
                 - Unchanged Javadoc or other native documentation required
                 - A man page shall be provided

_______________________________________________
opensolaris-arc mailing list
opensolaris-arc@opensolaris.org


--
Mark A. Carlson
Sr. Architect

Systems Group
Phone x69559 / 303-223-6139
Email Mark.Carlson@Sun.COM

--Boundary_(ID_BNIsI49VmSk+aUX852mSCQ)-- From Mark.Carlson@sun.com Wed May 20 13:00:11 2009 Received: from sunmail4.singapore.sun.com (sunmail4.Singapore.Sun.COM [129.158.71.19]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4KK0AMQ008669 for ; Wed, 20 May 2009 13:00:10 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail4.singapore.sun.com (8.13.4+Sun/8.13.3/ENSMAIL,v2.2) with ESMTP id n4KJxN9A017987 for <@sunmail2sca.sfbay.sun.com:LSARC-ext@sun.com>; Thu, 21 May 2009 04:00:09 +0800 (SGT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJY0061HKW4HL00@brm-avmta-1.central.sun.com> for LSARC-ext@sun.com (ORCPT LSARC-ext@sun.com); Wed, 20 May 2009 14:00:04 -0600 (MDT) Received: from brmea-mail-2.sun.com ([192.18.98.43]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJY00FW0KW4H790@brm-avmta-1.central.sun.com> for LSARC-ext@sun.com (ORCPT LSARC-ext@sun.com); Wed, 20 May 2009 14:00:04 -0600 (MDT) Received: from fe-amer-10.sun.com ([192.18.109.80]) by brmea-mail-2.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n4KK04pw024531 for ; Wed, 20 May 2009 20:00:04 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJY00A00JF7Q800@mail-amer.sun.com> for LSARC-ext@sun.com (ORCPT LSARC-ext@sun.com); Wed, 20 May 2009 14:00:04 -0600 (MDT) Received: from Macintosh-335.local ([unknown] [129.150.33.177]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJY0084VKUYMNH0@mail-amer.sun.com> for LSARC-ext@sun.com (ORCPT LSARC-ext@sun.com); Wed, 20 May 2009 13:59:23 -0600 (MDT) Date: Wed, 20 May 2009 13:59:22 -0600 From: "Mark A. Carlson" Subject: Re: trove-2.0.4 [LSARC/2009/262] - Draft Minority Opinion In-reply-to: Sender: Mark.Carlson@sun.com To: Tom Childers Cc: LSARC-ext@sun.com Message-id: <4A14611A.4000409@sun.com> MIME-version: 1.0 Content-type: multipart/alternative; boundary="Boundary_(ID_AtnPQqsb0rmauEOCf5o2yQ)" X-PMX-Version: 5.4.1.325704 References: <200904281656.n3SGuEVj009039@sac.sfbay.sun.com> <4A133158.4010500@sun.com> User-Agent: Thunderbird 2.0.0.21 (Macintosh/20090302) Status: RO Content-Length: 12392 This is a multi-part message in MIME format. --Boundary_(ID_AtnPQqsb0rmauEOCf5o2yQ) Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT Tom Childers wrote: > Mark, > > This is really good. The bottom line seems to be: > > - if we build it, we will use our own interface stability > classifications, and > deliver them via language-specific documentation facilities Yes. > > - if someone else built it, and there is IF stability info, we'll > support it via > the language-specific documentation facilities Right. > > - if someone else built it, but IF stability info is inadequate, > we can add a man > page, and urge the team to add IF stability info to the > language-specific doc. Yes. > > Since man pages are the de facto language-specific IF doc for C/C++, > can we simplify the third option to state: > > - if someone else built it, but there is inadequate IF stability > info, we urge the team > to add IF stability info to the language-specific doc. That's what the "strongly urge" language meant to imply. > > In other words, add a TCA to the opinion. I don't think we add value > by requiring a man page in one specific situation. If man pages are > not consistently generally available for Java/Python/etc., I don't > think an occasional page will help anything. A TCA would certainly be in the spirit of "strongly urge" -- mark > > On May 19, 2009, at 3:23 PM, Mark A. Carlson wrote: > >> During the case discussion today, I took the AI to help Michael >> Kearney draft >> a minority opinion. There may be other minority opinions, but if this >> looks >> close to something you would sign on to, I am open to small changes. >> >> -- mark >> >> >> 5. Minority Opinion >> >> Background >> >> It is not typical for programmers working with non C/C++/Assembler >> files, such as Java Jar files, to determine the >> Exported Interface stability level using the man command. Java >> programmers depend on Javadoc, Python programmers >> depend on pydoc and so forth to document interfaces and the >> stability would best be indicated there. >> Approval of OpenSolaris projects have been inconsistent in >> preferring man pages or native documentation. This opinion seeks >> to clarify the issue and define a policy for all such cases going >> forward. >> >> Best Practice >> >> Case A - Sun Developed Components >> >> 1) Sun project team developing a Jar file shall document the >> ARC interface classification in the native documentation. (i.e. >> Javadocs) >> >> Case B - Components imported from external OSS Communities >> >> 1) The OSS Community documents the interface classification in >> their native documentation >> >> a) OpenSolaris project team agrees with the classification >> and supports it >> - Javadoc or other native documentation required >> (unchanged) >> - No man page shall be allowed >> >> b) OpenSolaris project team disagrees with the >> classification >> - Javadoc or native documentation required, but >> project team must change the OSS documentation >> to match the project team's classification >> - No man page shall be allowed >> >> 2) OSS Community does not document interface classification in >> their native documentation >> a) OpenSolaris project team is strongly encouraged to >> update the native documentation to reflect the OpenSolaris project >> team >> classification. >> - Changed Javadoc or other native documentation required >> - No man page shall be allowed >> b) OpenSolaris project team cannot support deltas to the >> native documentation >> - Unchanged Javadoc or other native documentation >> required >> - A man page shall be provided >> >> _______________________________________________ >> opensolaris-arc mailing list >> opensolaris-arc@opensolaris.org >> > -- * Mark A. Carlson * Sr. Architect *Systems Group* Phone x69559 / 303-223-6139 Email Mark.Carlson@Sun.COM --Boundary_(ID_AtnPQqsb0rmauEOCf5o2yQ) Content-type: text/html; CHARSET=US-ASCII Content-transfer-encoding: 7BIT Tom Childers wrote:
Mark,

This is really good. The bottom line seems to be:

    - if we build it, we will use our own interface stability classifications, and
      deliver them via language-specific documentation facilities
Yes.

    - if someone else built it, and there is IF stability info, we'll support it via
      the language-specific documentation facilities
Right.

    - if someone else built it, but IF stability info is inadequate, we can add a man
      page, and urge the team to add IF stability info to the language-specific doc.
Yes.

Since man pages are the de facto language-specific IF doc for C/C++, can we simplify the third option to state:

    - if someone else built it, but there is inadequate IF stability info, we urge the team
      to add IF stability info to the language-specific doc.
That's what the "strongly urge" language meant to imply.

In other words, add a TCA to the opinion. I don't think we add value by requiring a man page in one specific situation.  If man pages are not consistently generally available for Java/Python/etc., I don't think an occasional page will help anything.
A TCA would certainly be in the spirit of "strongly urge"

-- mark

On May 19, 2009, at 3:23 PM, Mark A. Carlson wrote:

During the case discussion today, I took the AI to help Michael Kearney draft
a minority opinion. There may be other minority opinions, but if this looks
close to something you would sign on to, I am open to small changes.

-- mark


5. Minority Opinion

    Background

    It is not typical for programmers working with non C/C++/Assembler
    files, such as Java Jar files, to determine the
    Exported Interface stability level using the man command.  Java
    programmers depend on Javadoc, Python programmers
    depend on pydoc and so forth to document interfaces and the
    stability would best be indicated there.
    Approval of OpenSolaris projects have been inconsistent in
    preferring man pages or native documentation.  This opinion seeks
    to clarify the issue and define a policy for all such cases going
    forward.

    Best Practice

    Case A - Sun Developed Components

        1) Sun project team developing a Jar file shall document the
    ARC interface classification in the native documentation. (i.e.
    Javadocs)

    Case B - Components imported from external OSS Communities

        1) The OSS Community documents the interface classification in
    their native documentation

            a) OpenSolaris project team agrees with the classification
    and supports it
                - Javadoc or other native documentation required
    (unchanged)
                - No man page shall be allowed

            b) OpenSolaris project team disagrees with the classification
                - Javadoc or native documentation required, but
    project team must change the OSS documentation
                to match the project team's classification
                - No man page shall be allowed

       2) OSS Community does not document interface classification in
    their native documentation
            a) OpenSolaris project team is strongly encouraged to
    update the native documentation to reflect the OpenSolaris project
    team
            classification.
                - Changed Javadoc or other native documentation required
                - No man page shall be allowed
            b) OpenSolaris project team cannot support deltas to the
    native documentation
                - Unchanged Javadoc or other native documentation required
                - A man page shall be provided

_______________________________________________
opensolaris-arc mailing list
opensolaris-arc@opensolaris.org



--
Mark A. Carlson
Sr. Architect

Systems Group
Phone x69559 / 303-223-6139
Email Mark.Carlson@Sun.COM

--Boundary_(ID_AtnPQqsb0rmauEOCf5o2yQ)-- From margot.miller@sun.com Wed May 20 14:58:40 2009 Received: from sunmail3mpk.sfbay.sun.com (sunmail3mpk.SFBay.Sun.COM [129.146.11.52]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4KLwepb012382; Wed, 20 May 2009 14:58:40 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail3mpk.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4KLwe1o020614; Wed, 20 May 2009 14:58:40 -0700 (PDT) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJY00D01QDSG800@nwk-avmta-1.sfbay.Sun.COM>; Wed, 20 May 2009 14:58:40 -0700 (PDT) Received: from jurassic-x4600.sfbay.sun.com ([129.146.17.63]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJY00MNDQDR8J60@nwk-avmta-1.sfbay.Sun.COM>; Wed, 20 May 2009 14:58:39 -0700 (PDT) Received: from [10.7.250.88] (punchin-client-10-7-250-88.SFBay.Sun.COM [10.7.250.88]) by jurassic-x4600.sfbay.sun.com (8.14.3+Sun/8.14.3) with ESMTP id n4KLwcCW629914; Wed, 20 May 2009 14:58:39 -0700 (PDT) Date: Wed, 20 May 2009 14:58:38 -0700 From: Margot Miller Subject: trove-2.0.4 LSARC/2009/262 To: LSARC-ext@sun.com, psarc-ext@sun.com, margot.miller@sun.com Message-id: <4A147D0E.2030701@sun.com> MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1; format=flowed Content-transfer-encoding: 8BIT X-PMX-Version: 5.4.1.325704 User-Agent: Thunderbird 2.0.0.17 (X11/20081023) Status: RO Content-Length: 7357 All, I have included the minority opinion written by Mark Carlson. We did in fact have quorum yesterday; our external member was not listed as a full member. In any case, due to the lack of perceived quorum yesterday, please vote on this case. Vote to approve the case as written (with the TCR) Vote to deny If we find we now have a majority denying the case because they don´t agree with the TCR, then the TCR camp will become the minority. Thanks Margot microsystems Systems Architecture Committee _________________________________________________________________ Subject: trove-2.0.4 Submitted by: Vivek Titamare File: LSARC/2009/262/opinion.txt Date: May, 2009 Committee: Margot Hackett Miller, Lloyd Chambers Minority: Mark Carlson Product Approval Committee: Solaris PAC solaris-pac-opinion@sun.com 1. Summary This project is one of the Linux familiarity cases; this one provides a library to do fast regular and primitive collections for Java. 2. Decision & Precedence Information The project is approved as specified in reference [1]. The project may be delivered in a minor release of Solaris. 3. Interfaces Exported Interfaces: __________________________________________________ | Interfaces Exported | |____________ ______ |____________ __ __|____________| |Interface | Classification | Comments| |_______________ __|_________________|_____________| | trove.jar | Uncommitted | | |SUNWtrove | Uncommitted | | |___________________|_________________|____________| Imported Interfaces: ______________________________________________________________ | Interfaces Exported | | |___________________|______________ __|________________________| |Interface | Classification | Comments | |_______________ __|_________________|________________________| | | SUNWj5dev | Committed | Java Development kit | | SUNWj5rt | Committed | Java Runtime library | | SUNWj6dev | Committed | Java Development kit | | SUNWj6rt | Committed | Java Runtime library | |___________________|_________________|________________________| 4. Opinion During review, the only real issue raised was whether this team should provide a man page in addition to the javadocs. The man page would basically give a brief description of the jar file, pointer to the javadocs, and state the interface stability of the jar file. Discussion ensued whether it makes sense to ship a man page with a jar file. Solaris developers expect man pages, but do Java developers? Is it worth the extra work to provide a man page and would Java developers even look for a man page. It was noted that this is not standard practice as most Java developers look for java documentation via javadocs, not via man. However, others stated that having a minimal man page for a java jar file would allow the interface classification to be visible to the end user and a few other ARC cases have already shipped man pages for jar files. There was discussion over the granularity of the jar file and does it make sense to have an interface stability for the overall jar. Currently, java has Public, Package, and Protected. There was debate as to whether that conveys enough of the stability of the jar and its methods to the developer. With all the FOSS that is being delivered into Solaris, projects are delivering in their native, natural form. This includes man pages, texinfo, html, and javadoc. So the problem isn't just with javadocs and jar files. There is quite a bit of FOSS out there with no interface stability in the external Sun documentation. This is not a problem for Sun project teams as they can always look at the interface tables in the ARC tables to determine stability level. Asking all java project teams to ship a man page in addition to javadocs doesn´t seem like the right solution and having some teams ship a man page and others not, does not provide consistency. There needs to more discussion to determine if it is critical that the ARC stability level be communicated to the Solaris end user for all the FOSS software that is being delivered. If so, a comprehensive solution needs to be formulated, whether it is a CLI, a man page, annotation embedded in the Javadocs (which will work for Sun products but you cant force that upstream). This is not being addressed in this case. Project teams can continue to ship documentation in their ¨natural¨form and if there is some stability suggested in that documentation that is fine. Up until now, most projects have not shipped man pages with jar files. This doesn´t seem to have been written down anywhere. With this case, we would like to make it explicit to not deliver man pages with jar files. This is setting precedent of ¨do not ship man pages with jar files.¨ This resulted in the below TCR. 5. Minority Opinion(s) Background It is not typical for programmers working with non C/C++/Assembler files, such as Java Jar files, to determine the Exported Interface stability level using the man command. Java programmers depend on Javadoc, Python programmers depend on pydoc and so forth to document interfaces and the stability would best be indicated there. Approval of OpenSolaris projects have been inconsistent in preferring man pages or native documentation. This opinion seeks to clarify the issue and define a policy for all such cases going forward. Best Practice Case A - Sun Developed Components 1) Sun project team developing a Jar file shall document the ARC interface classification in the native documentation. (i.e. Javadocs) Case B - Components imported from external OSS Communities 1) The OSS Community documents the interface classification in their native documentation a) OpenSolaris project team agrees with the classification and supports it - Javadoc or other native documentation required (unchanged) - No man page shall be allowed b) OpenSolaris project team disagrees with the classification - Javadoc or native documentation required, but project team must change the OSS documentation to match the project team's classification - No man page shall be allowed 2) OSS Community does not document interface classification in their native documentation a) OpenSolaris project team is strongly encouraged to update the native documentation to reflect the OpenSolaris project team classification. - Changed Javadoc or other native documentation required - No man page shall be allowed b) OpenSolaris project team cannot support deltas to the native documentation - Unchanged Javadoc or other native documentation required - A man page shall be provided 6. Advisory Information None. 7. Appendices 7.1. Appendix A: Technical Changes Required Do not ship man pages with Java jar files 7.2. Appendix B: Technical Changes Advised None. 7.3. Appendix C: Reference Material Unless stated otherwise, path names are relative to the case directory LSARC/2009/262 1) Project Proposal file: LSARC/2009/262 Copyright 2009 Sun Microsystems From margot.miller@sun.com Wed May 20 14:58:40 2009 Received: from sunmail3mpk.sfbay.sun.com (sunmail3mpk.SFBay.Sun.COM [129.146.11.52]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4KLwepb012382; Wed, 20 May 2009 14:58:40 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail3mpk.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4KLwe1o020614; Wed, 20 May 2009 14:58:40 -0700 (PDT) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJY00D01QDSG800@nwk-avmta-1.sfbay.Sun.COM>; Wed, 20 May 2009 14:58:40 -0700 (PDT) Received: from jurassic-x4600.sfbay.sun.com ([129.146.17.63]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJY00MNDQDR8J60@nwk-avmta-1.sfbay.Sun.COM>; Wed, 20 May 2009 14:58:39 -0700 (PDT) Received: from [10.7.250.88] (punchin-client-10-7-250-88.SFBay.Sun.COM [10.7.250.88]) by jurassic-x4600.sfbay.sun.com (8.14.3+Sun/8.14.3) with ESMTP id n4KLwcCW629914; Wed, 20 May 2009 14:58:39 -0700 (PDT) Date: Wed, 20 May 2009 14:58:38 -0700 From: Margot Miller Subject: trove-2.0.4 LSARC/2009/262 To: LSARC-ext@sun.com, psarc-ext@sun.com, margot.miller@sun.com Message-id: <4A147D0E.2030701@sun.com> MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1; format=flowed Content-transfer-encoding: 8BIT X-PMX-Version: 5.4.1.325704 User-Agent: Thunderbird 2.0.0.17 (X11/20081023) Status: RO Content-Length: 7357 All, I have included the minority opinion written by Mark Carlson. We did in fact have quorum yesterday; our external member was not listed as a full member. In any case, due to the lack of perceived quorum yesterday, please vote on this case. Vote to approve the case as written (with the TCR) Vote to deny If we find we now have a majority denying the case because they don´t agree with the TCR, then the TCR camp will become the minority. Thanks Margot microsystems Systems Architecture Committee _________________________________________________________________ Subject: trove-2.0.4 Submitted by: Vivek Titamare File: LSARC/2009/262/opinion.txt Date: May, 2009 Committee: Margot Hackett Miller, Lloyd Chambers Minority: Mark Carlson Product Approval Committee: Solaris PAC solaris-pac-opinion@sun.com 1. Summary This project is one of the Linux familiarity cases; this one provides a library to do fast regular and primitive collections for Java. 2. Decision & Precedence Information The project is approved as specified in reference [1]. The project may be delivered in a minor release of Solaris. 3. Interfaces Exported Interfaces: __________________________________________________ | Interfaces Exported | |____________ ______ |____________ __ __|____________| |Interface | Classification | Comments| |_______________ __|_________________|_____________| | trove.jar | Uncommitted | | |SUNWtrove | Uncommitted | | |___________________|_________________|____________| Imported Interfaces: ______________________________________________________________ | Interfaces Exported | | |___________________|______________ __|________________________| |Interface | Classification | Comments | |_______________ __|_________________|________________________| | | SUNWj5dev | Committed | Java Development kit | | SUNWj5rt | Committed | Java Runtime library | | SUNWj6dev | Committed | Java Development kit | | SUNWj6rt | Committed | Java Runtime library | |___________________|_________________|________________________| 4. Opinion During review, the only real issue raised was whether this team should provide a man page in addition to the javadocs. The man page would basically give a brief description of the jar file, pointer to the javadocs, and state the interface stability of the jar file. Discussion ensued whether it makes sense to ship a man page with a jar file. Solaris developers expect man pages, but do Java developers? Is it worth the extra work to provide a man page and would Java developers even look for a man page. It was noted that this is not standard practice as most Java developers look for java documentation via javadocs, not via man. However, others stated that having a minimal man page for a java jar file would allow the interface classification to be visible to the end user and a few other ARC cases have already shipped man pages for jar files. There was discussion over the granularity of the jar file and does it make sense to have an interface stability for the overall jar. Currently, java has Public, Package, and Protected. There was debate as to whether that conveys enough of the stability of the jar and its methods to the developer. With all the FOSS that is being delivered into Solaris, projects are delivering in their native, natural form. This includes man pages, texinfo, html, and javadoc. So the problem isn't just with javadocs and jar files. There is quite a bit of FOSS out there with no interface stability in the external Sun documentation. This is not a problem for Sun project teams as they can always look at the interface tables in the ARC tables to determine stability level. Asking all java project teams to ship a man page in addition to javadocs doesn´t seem like the right solution and having some teams ship a man page and others not, does not provide consistency. There needs to more discussion to determine if it is critical that the ARC stability level be communicated to the Solaris end user for all the FOSS software that is being delivered. If so, a comprehensive solution needs to be formulated, whether it is a CLI, a man page, annotation embedded in the Javadocs (which will work for Sun products but you cant force that upstream). This is not being addressed in this case. Project teams can continue to ship documentation in their ¨natural¨form and if there is some stability suggested in that documentation that is fine. Up until now, most projects have not shipped man pages with jar files. This doesn´t seem to have been written down anywhere. With this case, we would like to make it explicit to not deliver man pages with jar files. This is setting precedent of ¨do not ship man pages with jar files.¨ This resulted in the below TCR. 5. Minority Opinion(s) Background It is not typical for programmers working with non C/C++/Assembler files, such as Java Jar files, to determine the Exported Interface stability level using the man command. Java programmers depend on Javadoc, Python programmers depend on pydoc and so forth to document interfaces and the stability would best be indicated there. Approval of OpenSolaris projects have been inconsistent in preferring man pages or native documentation. This opinion seeks to clarify the issue and define a policy for all such cases going forward. Best Practice Case A - Sun Developed Components 1) Sun project team developing a Jar file shall document the ARC interface classification in the native documentation. (i.e. Javadocs) Case B - Components imported from external OSS Communities 1) The OSS Community documents the interface classification in their native documentation a) OpenSolaris project team agrees with the classification and supports it - Javadoc or other native documentation required (unchanged) - No man page shall be allowed b) OpenSolaris project team disagrees with the classification - Javadoc or native documentation required, but project team must change the OSS documentation to match the project team's classification - No man page shall be allowed 2) OSS Community does not document interface classification in their native documentation a) OpenSolaris project team is strongly encouraged to update the native documentation to reflect the OpenSolaris project team classification. - Changed Javadoc or other native documentation required - No man page shall be allowed b) OpenSolaris project team cannot support deltas to the native documentation - Unchanged Javadoc or other native documentation required - A man page shall be provided 6. Advisory Information None. 7. Appendices 7.1. Appendix A: Technical Changes Required Do not ship man pages with Java jar files 7.2. Appendix B: Technical Changes Advised None. 7.3. Appendix C: Reference Material Unless stated otherwise, path names are relative to the case directory LSARC/2009/262 1) Project Proposal file: LSARC/2009/262 Copyright 2009 Sun Microsystems From Mark.Carlson@sun.com Wed May 20 15:38:24 2009 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4KMcNJe013005; Wed, 20 May 2009 15:38:23 -0700 (PDT) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by sunmail5.uk.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n4KMcCH6020970; Wed, 20 May 2009 23:38:22 +0100 (BST) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJY00001S7XWW00@nwk-avmta-2.sfbay.sun.com>; Wed, 20 May 2009 15:38:21 -0700 (PDT) Received: from brmea-mail-2.sun.com ([192.18.98.43]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJY00H6XS7XH860@nwk-avmta-2.sfbay.sun.com>; Wed, 20 May 2009 15:38:21 -0700 (PDT) Received: from fe-amer-10.sun.com ([192.18.109.80]) by brmea-mail-2.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n4KMcLh2028542; Wed, 20 May 2009 22:38:21 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJY00M00RWJ9Y00@mail-amer.sun.com>; Wed, 20 May 2009 16:38:21 -0600 (MDT) Received: from Macintosh-335.local ([unknown] [129.150.33.177]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJY00J6NS7WC030@mail-amer.sun.com>; Wed, 20 May 2009 16:38:20 -0600 (MDT) Date: Wed, 20 May 2009 16:38:19 -0600 From: "Mark A. Carlson" Subject: Re: trove-2.0.4 LSARC/2009/262 In-reply-to: <4A147D0E.2030701@sun.com> Sender: Mark.Carlson@sun.com To: Margot Miller Cc: LSARC-ext@sun.com, PSARC-ext@sun.com Message-id: <4A14865B.9060307@sun.com> MIME-version: 1.0 Content-type: multipart/alternative; boundary="Boundary_(ID_hP9SrNtXuzRtF1HZEAt+kQ)" X-PMX-Version: 5.4.1.325704 References: <4A147D0E.2030701@sun.com> User-Agent: Thunderbird 2.0.0.21 (Macintosh/20090302) Status: RO Content-Length: 20628 This is a multi-part message in MIME format. --Boundary_(ID_hP9SrNtXuzRtF1HZEAt+kQ) Content-type: text/plain; format=flowed; charset=ISO-8859-1 Content-transfer-encoding: 8BIT Deny - I'd change it to a TCA to "document the interface classification in the native documentation" (follow the outline in the minority opinion). -- mark Margot Miller wrote: > All, > > I have included the minority opinion written by Mark Carlson. > > We did in fact have quorum yesterday; our external member > was not listed as a full member. > > In any case, due to the lack of perceived quorum yesterday, > please vote on this case. > > Vote to approve the case as written (with the TCR) > Vote to deny > > If we find we now have a majority denying the case because > they don´t agree with the TCR, then the TCR camp will > become the minority. > > Thanks > Margot > > > microsystems Systems Architecture Committee > > _________________________________________________________________ > > Subject: trove-2.0.4 > > Submitted by: Vivek Titamare > > File: LSARC/2009/262/opinion.txt > > Date: May, 2009 > > Committee: Margot Hackett Miller, Lloyd Chambers > Minority: Mark Carlson > > > Product Approval Committee: > Solaris PAC > solaris-pac-opinion@sun.com > > 1. Summary > > This project is one of the Linux familiarity cases; this one provides > a library to do fast regular and primitive collections for > Java. > > 2. Decision & Precedence Information > > The project is approved as specified in reference [1]. > > The project may be delivered in a minor release of Solaris. > > 3. Interfaces > > Exported Interfaces: > > __________________________________________________ > | Interfaces Exported | > |____________ ______ |____________ __ __|____________| > |Interface | Classification | Comments| > |_______________ __|_________________|_____________| > | trove.jar | Uncommitted | | > |SUNWtrove | Uncommitted | | > |___________________|_________________|____________| > > > Imported Interfaces: > > ______________________________________________________________ > | Interfaces Exported | | > |___________________|______________ __|________________________| > |Interface | Classification | Comments | > |_______________ __|_________________|________________________| > | > | SUNWj5dev | Committed | Java Development kit | > | SUNWj5rt | Committed | Java Runtime library | > | SUNWj6dev | Committed | Java Development kit | > | SUNWj6rt | Committed | Java Runtime library | > |___________________|_________________|________________________| > > > > > 4. Opinion > > During review, the only real issue raised was whether this team > should provide a man page in addition to the javadocs. The man > page would basically give a brief description of the jar file, > pointer to the javadocs, and state the interface stability of the jar > file. > Discussion ensued whether it makes sense to ship a man page > with a jar file. Solaris developers expect man pages, but do > Java developers? Is it worth the extra work to provide a man page > and would Java developers even look for a man page. > > It was noted that this is not standard practice as most Java > developers look > for java documentation via javadocs, not via man. However, others > stated that > having a minimal man page for a java jar file would allow the interface > classification to be visible to the end user and a few other ARC cases > have > already shipped man pages for jar files. > > There was discussion over the granularity of the jar file and does > it make sense to have an interface stability for the overall jar. > Currently, > java has Public, Package, and Protected. There was debate as to > whether that conveys enough of the stability of the jar and its > methods to the > developer. > > With all the FOSS that is being delivered into Solaris, projects are > delivering in their native, natural form. This includes man pages, > texinfo, > html, and javadoc. So the problem isn't just with javadocs and jar files. > There is quite a bit of FOSS out there with no interface stability > in the external Sun documentation. This is not a problem for Sun > project teams as they can always look at the interface tables in > the ARC tables to determine stability level. > > Asking all java project teams to ship a man page in addition to > javadocs doesn´t > seem like the right solution and having some teams ship a man page > and others not, does not provide consistency. > > There needs to more discussion to determine if it is critical that the > ARC stability > level be communicated to the Solaris end user for all the FOSS software > that is being delivered. If so, a comprehensive solution needs to be > formulated, whether it is a CLI, a man page, annotation embedded in > the Javadocs > (which will work for Sun products but you cant force that upstream). > This is not being addressed in this case. Project teams can continue > to ship documentation in their ¨natural¨form and if there is some > stability suggested in that documentation that is fine. > Up until now, most projects have not shipped man pages with jar > files. This doesn´t seem to have been written down anywhere. With > this case, we would like to make it explicit to not deliver man pages > with jar files. This is setting precedent of ¨do not ship man pages > with jar files.¨ This resulted in the below TCR. > > 5. Minority Opinion(s) > > Background > > It is not typical for programmers working with non C/C++/Assembler > files, such as Java Jar files, to determine the > Exported Interface stability level using the man command. Java > programmers depend on Javadoc, Python programmers > depend on pydoc and so forth to document interfaces and the > stability would best be indicated there. > Approval of OpenSolaris projects have been inconsistent in > preferring man pages or native documentation. This opinion seeks > to clarify the issue and define a policy for all such cases going > forward. > > Best Practice > > Case A - Sun Developed Components > > 1) Sun project team developing a Jar file shall document the > ARC interface classification in the native documentation. (i.e. > Javadocs) > > Case B - Components imported from external OSS Communities > > 1) The OSS Community documents the interface classification in > their native documentation > > a) OpenSolaris project team agrees with the classification > and supports it > - Javadoc or other native documentation required > (unchanged) > - No man page shall be allowed > > b) OpenSolaris project team disagrees with the > classification > - Javadoc or native documentation required, but > project team must change the OSS documentation > to match the project team's classification > - No man page shall be allowed > > 2) OSS Community does not document interface classification in > their native documentation > a) OpenSolaris project team is strongly encouraged to > update the native documentation to reflect the OpenSolaris project > team > classification. > - Changed Javadoc or other native documentation required > - No man page shall be allowed > b) OpenSolaris project team cannot support deltas to the > native documentation > - Unchanged Javadoc or other native documentation > required > - A man page shall be provided > > > > 6. Advisory Information > > None. > > 7. Appendices > > 7.1. Appendix A: Technical Changes Required > > Do not ship man pages with Java jar files > > 7.2. Appendix B: Technical Changes Advised > > None. > > 7.3. Appendix C: Reference Material > > Unless stated otherwise, path names are relative to the case > directory LSARC/2009/262 > > 1) Project Proposal file: > > > LSARC/2009/262 Copyright 2009 Sun Microsystems > _______________________________________________ > opensolaris-arc mailing list > opensolaris-arc@opensolaris.org -- * Mark A. Carlson * Sr. Architect *Systems Group* Phone x69559 / 303-223-6139 Email Mark.Carlson@Sun.COM --Boundary_(ID_hP9SrNtXuzRtF1HZEAt+kQ) Content-type: text/html; CHARSET=US-ASCII Content-transfer-encoding: 7BIT Deny - I'd change it to a TCA to "document the interface classification
in the native documentation" (follow the outline in the minority opinion).

-- mark

Margot Miller wrote:
All,

I have included the minority opinion written by Mark Carlson.

We did in fact have quorum yesterday; our external member
was not listed as a full member.

In any case, due to the lack of perceived quorum yesterday,
please vote on this case.

 Vote to approve the case as written (with the TCR)
 Vote to deny

If we find we now have a majority denying the case because
they don´t agree with the TCR, then the TCR camp will
become the minority.

Thanks
Margot


microsystems Systems Architecture Committee

_________________________________________________________________

Subject: trove-2.0.4

Submitted by: Vivek Titamare

File: LSARC/2009/262/opinion.txt

Date: May, 2009

Committee: Margot Hackett Miller, Lloyd Chambers
Minority: Mark Carlson


Product Approval Committee:
Solaris PAC
solaris-pac-opinion@sun.com

1. Summary

This project is one of the Linux familiarity cases; this one provides
a library to do fast regular and primitive collections for
Java.

2. Decision & Precedence Information

The project is approved as specified in reference [1].

The project may be delivered in a minor release of Solaris.

3. Interfaces

Exported Interfaces:

__________________________________________________
| Interfaces Exported |
|____________ ______ |____________ __ __|____________|
|Interface | Classification | Comments|
|_______________ __|_________________|_____________|
| trove.jar | Uncommitted | |
|SUNWtrove | Uncommitted | |
|___________________|_________________|____________|


Imported Interfaces:

______________________________________________________________
| Interfaces Exported | |
|___________________|______________ __|________________________|
|Interface | Classification | Comments |
|_______________ __|_________________|________________________|
|
| SUNWj5dev | Committed | Java Development kit |
| SUNWj5rt | Committed | Java Runtime library |
| SUNWj6dev | Committed | Java Development kit |
| SUNWj6rt | Committed | Java Runtime library |
|___________________|_________________|________________________|




4. Opinion

During review, the only real issue raised was whether this team
should provide a man page in addition to the javadocs. The man
page would basically give a brief description of the jar file,
pointer to the javadocs, and state the interface stability of the jar file.
Discussion ensued whether it makes sense to ship a man page
with a jar file. Solaris developers expect man pages, but do
Java developers? Is it worth the extra work to provide a man page
and would Java developers even look for a man page.

It was noted that this is not standard practice as most Java developers look
for java documentation via javadocs, not via man. However, others stated that
having a minimal man page for a java jar file would allow the interface
classification to be visible to the end user and a few other ARC cases have
already shipped man pages for jar files.

There was discussion over the granularity of the jar file and does
it make sense to have an interface stability for the overall jar. Currently,
java has Public, Package, and Protected.   There was debate as to
whether that conveys enough of the stability of the jar and its methods to the
developer.

With all the FOSS that is being delivered into Solaris, projects are
delivering in their native, natural form. This includes man pages, texinfo,
html, and javadoc. So the problem isn't just with javadocs and jar files.
There is quite a bit of FOSS out there with no interface stability
in the external Sun documentation.  This is not a problem for Sun
project teams as they can always look at the interface tables in
the ARC tables to determine stability level.

Asking all java project teams to ship a man page in addition to javadocs doesn´t
seem like the right solution and having some teams ship a man page
and others not, does not provide consistency.

There needs to more discussion to determine if it is critical that the ARC stability
level be communicated to the Solaris end user for all the FOSS software
that is being delivered. If so, a comprehensive solution needs to be
formulated, whether it is a CLI, a man page, annotation embedded in the Javadocs
(which will work for Sun products but you cant force that upstream).
This is not being addressed in this case.  Project teams can continue
to ship documentation in their ¨natural¨form and if there is some
stability suggested in that documentation that is fine.
Up until now, most projects have not shipped man pages with jar
files.  This doesn´t seem to have been written down anywhere.  With
this case, we would like to make it explicit to not deliver man pages
with jar files.  This is setting precedent of ¨do not ship man pages
with jar files.¨ This resulted in the below TCR.

5. Minority Opinion(s)

     Background

     It is not typical for programmers working with non C/C++/Assembler
     files, such as Java Jar files, to determine the
     Exported Interface stability level using the man command.  Java
     programmers depend on Javadoc, Python programmers
     depend on pydoc and so forth to document interfaces and the
     stability would best be indicated there. 
     Approval of OpenSolaris projects have been inconsistent in
     preferring man pages or native documentation.  This opinion seeks
     to clarify the issue and define a policy for all such cases going
     forward.

     Best Practice

     Case A - Sun Developed Components

         1) Sun project team developing a Jar file shall document the
     ARC interface classification in the native documentation. (i.e.
     Javadocs)

     Case B - Components imported from external OSS Communities

         1) The OSS Community documents the interface classification in
     their native documentation

             a) OpenSolaris project team agrees with the classification
     and supports it
                 - Javadoc or other native documentation required
     (unchanged)
                 - No man page shall be allowed

             b) OpenSolaris project team disagrees with the classification
                 - Javadoc or native documentation required, but
     project team must change the OSS documentation
                 to match the project team's classification
                 - No man page shall be allowed

        2) OSS Community does not document interface classification in
     their native documentation
             a) OpenSolaris project team is strongly encouraged to
     update the native documentation to reflect the OpenSolaris project
     team
             classification.
                 - Changed Javadoc or other native documentation required
                 - No man page shall be allowed
             b) OpenSolaris project team cannot support deltas to the
     native documentation
                 - Unchanged Javadoc or other native documentation required
                 - A man page shall be provided



6. Advisory Information

None.

7. Appendices

7.1. Appendix A: Technical Changes Required

Do not ship man pages with Java jar files

7.2. Appendix B: Technical Changes Advised

None.

7.3. Appendix C: Reference Material

Unless stated otherwise, path names are relative to the case
directory LSARC/2009/262

1) Project Proposal file:


LSARC/2009/262 Copyright 2009 Sun Microsystems
_______________________________________________
opensolaris-arc mailing list
opensolaris-arc@opensolaris.org

--
Mark A. Carlson
Sr. Architect

Systems Group
Phone x69559 / 303-223-6139
Email Mark.Carlson@Sun.COM

--Boundary_(ID_hP9SrNtXuzRtF1HZEAt+kQ)-- From Mark.Carlson@sun.com Wed May 20 15:38:24 2009 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4KMcNJe013005; Wed, 20 May 2009 15:38:23 -0700 (PDT) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by sunmail5.uk.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n4KMcCH6020970; Wed, 20 May 2009 23:38:22 +0100 (BST) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJY00001S7XWW00@nwk-avmta-2.sfbay.sun.com>; Wed, 20 May 2009 15:38:21 -0700 (PDT) Received: from brmea-mail-2.sun.com ([192.18.98.43]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJY00H6XS7XH860@nwk-avmta-2.sfbay.sun.com>; Wed, 20 May 2009 15:38:21 -0700 (PDT) Received: from fe-amer-10.sun.com ([192.18.109.80]) by brmea-mail-2.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n4KMcLh2028542; Wed, 20 May 2009 22:38:21 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJY00M00RWJ9Y00@mail-amer.sun.com>; Wed, 20 May 2009 16:38:21 -0600 (MDT) Received: from Macintosh-335.local ([unknown] [129.150.33.177]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJY00J6NS7WC030@mail-amer.sun.com>; Wed, 20 May 2009 16:38:20 -0600 (MDT) Date: Wed, 20 May 2009 16:38:19 -0600 From: "Mark A. Carlson" Subject: Re: trove-2.0.4 LSARC/2009/262 In-reply-to: <4A147D0E.2030701@sun.com> Sender: Mark.Carlson@sun.com To: Margot Miller Cc: LSARC-ext@sun.com, PSARC-ext@sun.com Message-id: <4A14865B.9060307@sun.com> MIME-version: 1.0 Content-type: multipart/alternative; boundary="Boundary_(ID_hP9SrNtXuzRtF1HZEAt+kQ)" X-PMX-Version: 5.4.1.325704 References: <4A147D0E.2030701@sun.com> User-Agent: Thunderbird 2.0.0.21 (Macintosh/20090302) Status: RO Content-Length: 20628 This is a multi-part message in MIME format. --Boundary_(ID_hP9SrNtXuzRtF1HZEAt+kQ) Content-type: text/plain; format=flowed; charset=ISO-8859-1 Content-transfer-encoding: 8BIT Deny - I'd change it to a TCA to "document the interface classification in the native documentation" (follow the outline in the minority opinion). -- mark Margot Miller wrote: > All, > > I have included the minority opinion written by Mark Carlson. > > We did in fact have quorum yesterday; our external member > was not listed as a full member. > > In any case, due to the lack of perceived quorum yesterday, > please vote on this case. > > Vote to approve the case as written (with the TCR) > Vote to deny > > If we find we now have a majority denying the case because > they don´t agree with the TCR, then the TCR camp will > become the minority. > > Thanks > Margot > > > microsystems Systems Architecture Committee > > _________________________________________________________________ > > Subject: trove-2.0.4 > > Submitted by: Vivek Titamare > > File: LSARC/2009/262/opinion.txt > > Date: May, 2009 > > Committee: Margot Hackett Miller, Lloyd Chambers > Minority: Mark Carlson > > > Product Approval Committee: > Solaris PAC > solaris-pac-opinion@sun.com > > 1. Summary > > This project is one of the Linux familiarity cases; this one provides > a library to do fast regular and primitive collections for > Java. > > 2. Decision & Precedence Information > > The project is approved as specified in reference [1]. > > The project may be delivered in a minor release of Solaris. > > 3. Interfaces > > Exported Interfaces: > > __________________________________________________ > | Interfaces Exported | > |____________ ______ |____________ __ __|____________| > |Interface | Classification | Comments| > |_______________ __|_________________|_____________| > | trove.jar | Uncommitted | | > |SUNWtrove | Uncommitted | | > |___________________|_________________|____________| > > > Imported Interfaces: > > ______________________________________________________________ > | Interfaces Exported | | > |___________________|______________ __|________________________| > |Interface | Classification | Comments | > |_______________ __|_________________|________________________| > | > | SUNWj5dev | Committed | Java Development kit | > | SUNWj5rt | Committed | Java Runtime library | > | SUNWj6dev | Committed | Java Development kit | > | SUNWj6rt | Committed | Java Runtime library | > |___________________|_________________|________________________| > > > > > 4. Opinion > > During review, the only real issue raised was whether this team > should provide a man page in addition to the javadocs. The man > page would basically give a brief description of the jar file, > pointer to the javadocs, and state the interface stability of the jar > file. > Discussion ensued whether it makes sense to ship a man page > with a jar file. Solaris developers expect man pages, but do > Java developers? Is it worth the extra work to provide a man page > and would Java developers even look for a man page. > > It was noted that this is not standard practice as most Java > developers look > for java documentation via javadocs, not via man. However, others > stated that > having a minimal man page for a java jar file would allow the interface > classification to be visible to the end user and a few other ARC cases > have > already shipped man pages for jar files. > > There was discussion over the granularity of the jar file and does > it make sense to have an interface stability for the overall jar. > Currently, > java has Public, Package, and Protected. There was debate as to > whether that conveys enough of the stability of the jar and its > methods to the > developer. > > With all the FOSS that is being delivered into Solaris, projects are > delivering in their native, natural form. This includes man pages, > texinfo, > html, and javadoc. So the problem isn't just with javadocs and jar files. > There is quite a bit of FOSS out there with no interface stability > in the external Sun documentation. This is not a problem for Sun > project teams as they can always look at the interface tables in > the ARC tables to determine stability level. > > Asking all java project teams to ship a man page in addition to > javadocs doesn´t > seem like the right solution and having some teams ship a man page > and others not, does not provide consistency. > > There needs to more discussion to determine if it is critical that the > ARC stability > level be communicated to the Solaris end user for all the FOSS software > that is being delivered. If so, a comprehensive solution needs to be > formulated, whether it is a CLI, a man page, annotation embedded in > the Javadocs > (which will work for Sun products but you cant force that upstream). > This is not being addressed in this case. Project teams can continue > to ship documentation in their ¨natural¨form and if there is some > stability suggested in that documentation that is fine. > Up until now, most projects have not shipped man pages with jar > files. This doesn´t seem to have been written down anywhere. With > this case, we would like to make it explicit to not deliver man pages > with jar files. This is setting precedent of ¨do not ship man pages > with jar files.¨ This resulted in the below TCR. > > 5. Minority Opinion(s) > > Background > > It is not typical for programmers working with non C/C++/Assembler > files, such as Java Jar files, to determine the > Exported Interface stability level using the man command. Java > programmers depend on Javadoc, Python programmers > depend on pydoc and so forth to document interfaces and the > stability would best be indicated there. > Approval of OpenSolaris projects have been inconsistent in > preferring man pages or native documentation. This opinion seeks > to clarify the issue and define a policy for all such cases going > forward. > > Best Practice > > Case A - Sun Developed Components > > 1) Sun project team developing a Jar file shall document the > ARC interface classification in the native documentation. (i.e. > Javadocs) > > Case B - Components imported from external OSS Communities > > 1) The OSS Community documents the interface classification in > their native documentation > > a) OpenSolaris project team agrees with the classification > and supports it > - Javadoc or other native documentation required > (unchanged) > - No man page shall be allowed > > b) OpenSolaris project team disagrees with the > classification > - Javadoc or native documentation required, but > project team must change the OSS documentation > to match the project team's classification > - No man page shall be allowed > > 2) OSS Community does not document interface classification in > their native documentation > a) OpenSolaris project team is strongly encouraged to > update the native documentation to reflect the OpenSolaris project > team > classification. > - Changed Javadoc or other native documentation required > - No man page shall be allowed > b) OpenSolaris project team cannot support deltas to the > native documentation > - Unchanged Javadoc or other native documentation > required > - A man page shall be provided > > > > 6. Advisory Information > > None. > > 7. Appendices > > 7.1. Appendix A: Technical Changes Required > > Do not ship man pages with Java jar files > > 7.2. Appendix B: Technical Changes Advised > > None. > > 7.3. Appendix C: Reference Material > > Unless stated otherwise, path names are relative to the case > directory LSARC/2009/262 > > 1) Project Proposal file: > > > LSARC/2009/262 Copyright 2009 Sun Microsystems > _______________________________________________ > opensolaris-arc mailing list > opensolaris-arc@opensolaris.org -- * Mark A. Carlson * Sr. Architect *Systems Group* Phone x69559 / 303-223-6139 Email Mark.Carlson@Sun.COM --Boundary_(ID_hP9SrNtXuzRtF1HZEAt+kQ) Content-type: text/html; CHARSET=US-ASCII Content-transfer-encoding: 7BIT Deny - I'd change it to a TCA to "document the interface classification
in the native documentation" (follow the outline in the minority opinion).

-- mark

Margot Miller wrote:
All,

I have included the minority opinion written by Mark Carlson.

We did in fact have quorum yesterday; our external member
was not listed as a full member.

In any case, due to the lack of perceived quorum yesterday,
please vote on this case.

 Vote to approve the case as written (with the TCR)
 Vote to deny

If we find we now have a majority denying the case because
they don´t agree with the TCR, then the TCR camp will
become the minority.

Thanks
Margot


microsystems Systems Architecture Committee

_________________________________________________________________

Subject: trove-2.0.4

Submitted by: Vivek Titamare

File: LSARC/2009/262/opinion.txt

Date: May, 2009

Committee: Margot Hackett Miller, Lloyd Chambers
Minority: Mark Carlson


Product Approval Committee:
Solaris PAC
solaris-pac-opinion@sun.com

1. Summary

This project is one of the Linux familiarity cases; this one provides
a library to do fast regular and primitive collections for
Java.

2. Decision & Precedence Information

The project is approved as specified in reference [1].

The project may be delivered in a minor release of Solaris.

3. Interfaces

Exported Interfaces:

__________________________________________________
| Interfaces Exported |
|____________ ______ |____________ __ __|____________|
|Interface | Classification | Comments|
|_______________ __|_________________|_____________|
| trove.jar | Uncommitted | |
|SUNWtrove | Uncommitted | |
|___________________|_________________|____________|


Imported Interfaces:

______________________________________________________________
| Interfaces Exported | |
|___________________|______________ __|________________________|
|Interface | Classification | Comments |
|_______________ __|_________________|________________________|
|
| SUNWj5dev | Committed | Java Development kit |
| SUNWj5rt | Committed | Java Runtime library |
| SUNWj6dev | Committed | Java Development kit |
| SUNWj6rt | Committed | Java Runtime library |
|___________________|_________________|________________________|




4. Opinion

During review, the only real issue raised was whether this team
should provide a man page in addition to the javadocs. The man
page would basically give a brief description of the jar file,
pointer to the javadocs, and state the interface stability of the jar file.
Discussion ensued whether it makes sense to ship a man page
with a jar file. Solaris developers expect man pages, but do
Java developers? Is it worth the extra work to provide a man page
and would Java developers even look for a man page.

It was noted that this is not standard practice as most Java developers look
for java documentation via javadocs, not via man. However, others stated that
having a minimal man page for a java jar file would allow the interface
classification to be visible to the end user and a few other ARC cases have
already shipped man pages for jar files.

There was discussion over the granularity of the jar file and does
it make sense to have an interface stability for the overall jar. Currently,
java has Public, Package, and Protected.   There was debate as to
whether that conveys enough of the stability of the jar and its methods to the
developer.

With all the FOSS that is being delivered into Solaris, projects are
delivering in their native, natural form. This includes man pages, texinfo,
html, and javadoc. So the problem isn't just with javadocs and jar files.
There is quite a bit of FOSS out there with no interface stability
in the external Sun documentation.  This is not a problem for Sun
project teams as they can always look at the interface tables in
the ARC tables to determine stability level.

Asking all java project teams to ship a man page in addition to javadocs doesn´t
seem like the right solution and having some teams ship a man page
and others not, does not provide consistency.

There needs to more discussion to determine if it is critical that the ARC stability
level be communicated to the Solaris end user for all the FOSS software
that is being delivered. If so, a comprehensive solution needs to be
formulated, whether it is a CLI, a man page, annotation embedded in the Javadocs
(which will work for Sun products but you cant force that upstream).
This is not being addressed in this case.  Project teams can continue
to ship documentation in their ¨natural¨form and if there is some
stability suggested in that documentation that is fine.
Up until now, most projects have not shipped man pages with jar
files.  This doesn´t seem to have been written down anywhere.  With
this case, we would like to make it explicit to not deliver man pages
with jar files.  This is setting precedent of ¨do not ship man pages
with jar files.¨ This resulted in the below TCR.

5. Minority Opinion(s)

     Background

     It is not typical for programmers working with non C/C++/Assembler
     files, such as Java Jar files, to determine the
     Exported Interface stability level using the man command.  Java
     programmers depend on Javadoc, Python programmers
     depend on pydoc and so forth to document interfaces and the
     stability would best be indicated there. 
     Approval of OpenSolaris projects have been inconsistent in
     preferring man pages or native documentation.  This opinion seeks
     to clarify the issue and define a policy for all such cases going
     forward.

     Best Practice

     Case A - Sun Developed Components

         1) Sun project team developing a Jar file shall document the
     ARC interface classification in the native documentation. (i.e.
     Javadocs)

     Case B - Components imported from external OSS Communities

         1) The OSS Community documents the interface classification in
     their native documentation

             a) OpenSolaris project team agrees with the classification
     and supports it
                 - Javadoc or other native documentation required
     (unchanged)
                 - No man page shall be allowed

             b) OpenSolaris project team disagrees with the classification
                 - Javadoc or native documentation required, but
     project team must change the OSS documentation
                 to match the project team's classification
                 - No man page shall be allowed

        2) OSS Community does not document interface classification in
     their native documentation
             a) OpenSolaris project team is strongly encouraged to
     update the native documentation to reflect the OpenSolaris project
     team
             classification.
                 - Changed Javadoc or other native documentation required
                 - No man page shall be allowed
             b) OpenSolaris project team cannot support deltas to the
     native documentation
                 - Unchanged Javadoc or other native documentation required
                 - A man page shall be provided



6. Advisory Information

None.

7. Appendices

7.1. Appendix A: Technical Changes Required

Do not ship man pages with Java jar files

7.2. Appendix B: Technical Changes Advised

None.

7.3. Appendix C: Reference Material

Unless stated otherwise, path names are relative to the case
directory LSARC/2009/262

1) Project Proposal file:


LSARC/2009/262 Copyright 2009 Sun Microsystems
_______________________________________________
opensolaris-arc mailing list
opensolaris-arc@opensolaris.org

--
Mark A. Carlson
Sr. Architect

Systems Group
Phone x69559 / 303-223-6139
Email Mark.Carlson@Sun.COM

--Boundary_(ID_hP9SrNtXuzRtF1HZEAt+kQ)-- From margot.miller@sun.com Wed May 20 15:53:32 2009 Received: from sunmail4.singapore.sun.com (sunmail4.Singapore.Sun.COM [129.158.71.19]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4KMrUO2013147; Wed, 20 May 2009 15:53:30 -0700 (PDT) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by sunmail4.singapore.sun.com (8.13.4+Sun/8.13.3/ENSMAIL,v2.2) with ESMTP id n4KMrNsb015816; Thu, 21 May 2009 06:53:27 +0800 (SGT) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJY00101SX2WL00@nwk-avmta-2.sfbay.sun.com>; Wed, 20 May 2009 15:53:26 -0700 (PDT) Received: from jurassic-x4600.sfbay.sun.com ([129.146.17.59]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJY00HV3SX2H860@nwk-avmta-2.sfbay.sun.com>; Wed, 20 May 2009 15:53:26 -0700 (PDT) Received: from [10.7.250.88] (punchin-client-10-7-250-88.SFBay.Sun.COM [10.7.250.88]) by jurassic-x4600.sfbay.sun.com (8.14.3+Sun/8.14.3) with ESMTP id n4KMrP7s707156; Wed, 20 May 2009 15:53:25 -0700 (PDT) Date: Wed, 20 May 2009 15:53:25 -0700 From: Margot Miller Subject: Re: trove-2.0.4 LSARC/2009/262 In-reply-to: <4A14865B.9060307@sun.com> To: "Mark A. Carlson" Cc: LSARC-ext@sun.com, PSARC-ext@sun.com Message-id: <4A1489E5.5050601@sun.com> MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1; format=flowed Content-transfer-encoding: 8BIT X-PMX-Version: 5.4.1.325704 References: <4A147D0E.2030701@sun.com> <4A14865B.9060307@sun.com> User-Agent: Thunderbird 2.0.0.17 (X11/20081023) Status: RO Content-Length: 8694 I wouldn´t mind having a TCA to have teams document the interface classification in their native documentation. The only thing I disagree with is forcing teams to provide a man page if they don´t have the interface classification in their native documentation. Thanks Margot Mark A. Carlson wrote: > Deny - I'd change it to a TCA to "document the interface classification > in the native documentation" (follow the outline in the minority opinion). > > -- mark > > Margot Miller wrote: >> All, >> >> I have included the minority opinion written by Mark Carlson. >> >> We did in fact have quorum yesterday; our external member >> was not listed as a full member. >> >> In any case, due to the lack of perceived quorum yesterday, >> please vote on this case. >> >> Vote to approve the case as written (with the TCR) >> Vote to deny >> >> If we find we now have a majority denying the case because >> they don´t agree with the TCR, then the TCR camp will >> become the minority. >> >> Thanks >> Margot >> >> >> microsystems Systems Architecture Committee >> >> _________________________________________________________________ >> >> Subject: trove-2.0.4 >> >> Submitted by: Vivek Titamare >> >> File: LSARC/2009/262/opinion.txt >> >> Date: May, 2009 >> >> Committee: Margot Hackett Miller, Lloyd Chambers >> Minority: Mark Carlson >> >> >> Product Approval Committee: >> Solaris PAC >> solaris-pac-opinion@sun.com >> >> 1. Summary >> >> This project is one of the Linux familiarity cases; this one provides >> a library to do fast regular and primitive collections for >> Java. >> >> 2. Decision & Precedence Information >> >> The project is approved as specified in reference [1]. >> >> The project may be delivered in a minor release of Solaris. >> >> 3. Interfaces >> >> Exported Interfaces: >> >> __________________________________________________ >> | Interfaces Exported | >> |____________ ______ |____________ __ __|____________| >> |Interface | Classification | Comments| >> |_______________ __|_________________|_____________| >> | trove.jar | Uncommitted | | >> |SUNWtrove | Uncommitted | | >> |___________________|_________________|____________| >> >> >> Imported Interfaces: >> >> ______________________________________________________________ >> | Interfaces Exported | | >> |___________________|______________ __|________________________| >> |Interface | Classification | Comments | >> |_______________ __|_________________|________________________| >> | >> | SUNWj5dev | Committed | Java Development kit | >> | SUNWj5rt | Committed | Java Runtime library | >> | SUNWj6dev | Committed | Java Development kit | >> | SUNWj6rt | Committed | Java Runtime library | >> |___________________|_________________|________________________| >> >> >> >> >> 4. Opinion >> >> During review, the only real issue raised was whether this team >> should provide a man page in addition to the javadocs. The man >> page would basically give a brief description of the jar file, >> pointer to the javadocs, and state the interface stability of the jar >> file. >> Discussion ensued whether it makes sense to ship a man page >> with a jar file. Solaris developers expect man pages, but do >> Java developers? Is it worth the extra work to provide a man page >> and would Java developers even look for a man page. >> >> It was noted that this is not standard practice as most Java >> developers look >> for java documentation via javadocs, not via man. However, others >> stated that >> having a minimal man page for a java jar file would allow the interface >> classification to be visible to the end user and a few other ARC >> cases have >> already shipped man pages for jar files. >> >> There was discussion over the granularity of the jar file and does >> it make sense to have an interface stability for the overall jar. >> Currently, >> java has Public, Package, and Protected. There was debate as to >> whether that conveys enough of the stability of the jar and its >> methods to the >> developer. >> >> With all the FOSS that is being delivered into Solaris, projects are >> delivering in their native, natural form. This includes man pages, >> texinfo, >> html, and javadoc. So the problem isn't just with javadocs and jar >> files. >> There is quite a bit of FOSS out there with no interface stability >> in the external Sun documentation. This is not a problem for Sun >> project teams as they can always look at the interface tables in >> the ARC tables to determine stability level. >> >> Asking all java project teams to ship a man page in addition to >> javadocs doesn´t >> seem like the right solution and having some teams ship a man page >> and others not, does not provide consistency. >> >> There needs to more discussion to determine if it is critical that >> the ARC stability >> level be communicated to the Solaris end user for all the FOSS software >> that is being delivered. If so, a comprehensive solution needs to be >> formulated, whether it is a CLI, a man page, annotation embedded in >> the Javadocs >> (which will work for Sun products but you cant force that upstream). >> This is not being addressed in this case. Project teams can continue >> to ship documentation in their ¨natural¨form and if there is some >> stability suggested in that documentation that is fine. >> Up until now, most projects have not shipped man pages with jar >> files. This doesn´t seem to have been written down anywhere. With >> this case, we would like to make it explicit to not deliver man pages >> with jar files. This is setting precedent of ¨do not ship man pages >> with jar files.¨ This resulted in the below TCR. >> >> 5. Minority Opinion(s) >> >> Background >> >> It is not typical for programmers working with non C/C++/Assembler >> files, such as Java Jar files, to determine the >> Exported Interface stability level using the man command. Java >> programmers depend on Javadoc, Python programmers >> depend on pydoc and so forth to document interfaces and the >> stability would best be indicated there. >> Approval of OpenSolaris projects have been inconsistent in >> preferring man pages or native documentation. This opinion seeks >> to clarify the issue and define a policy for all such cases going >> forward. >> >> Best Practice >> >> Case A - Sun Developed Components >> >> 1) Sun project team developing a Jar file shall document the >> ARC interface classification in the native documentation. (i.e. >> Javadocs) >> >> Case B - Components imported from external OSS Communities >> >> 1) The OSS Community documents the interface classification in >> their native documentation >> >> a) OpenSolaris project team agrees with the classification >> and supports it >> - Javadoc or other native documentation required >> (unchanged) >> - No man page shall be allowed >> >> b) OpenSolaris project team disagrees with the >> classification >> - Javadoc or native documentation required, but >> project team must change the OSS documentation >> to match the project team's classification >> - No man page shall be allowed >> >> 2) OSS Community does not document interface classification in >> their native documentation >> a) OpenSolaris project team is strongly encouraged to >> update the native documentation to reflect the OpenSolaris project >> team >> classification. >> - Changed Javadoc or other native documentation >> required >> - No man page shall be allowed >> b) OpenSolaris project team cannot support deltas to the >> native documentation >> - Unchanged Javadoc or other native documentation >> required >> - A man page shall be provided >> >> >> >> 6. Advisory Information >> >> None. >> >> 7. Appendices >> >> 7.1. Appendix A: Technical Changes Required >> >> Do not ship man pages with Java jar files >> >> 7.2. Appendix B: Technical Changes Advised >> >> None. >> >> 7.3. Appendix C: Reference Material >> >> Unless stated otherwise, path names are relative to the case >> directory LSARC/2009/262 >> >> 1) Project Proposal file: >> >> >> LSARC/2009/262 Copyright 2009 Sun Microsystems >> _______________________________________________ >> opensolaris-arc mailing list >> opensolaris-arc@opensolaris.org > > -- > * Mark A. Carlson * > Sr. Architect > > *Systems Group* > Phone x69559 / 303-223-6139 > Email Mark.Carlson@Sun.COM > > > From margot.miller@sun.com Wed May 20 15:53:32 2009 Received: from sunmail4.singapore.sun.com (sunmail4.Singapore.Sun.COM [129.158.71.19]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4KMrUO2013147; Wed, 20 May 2009 15:53:30 -0700 (PDT) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by sunmail4.singapore.sun.com (8.13.4+Sun/8.13.3/ENSMAIL,v2.2) with ESMTP id n4KMrNsb015816; Thu, 21 May 2009 06:53:27 +0800 (SGT) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJY00101SX2WL00@nwk-avmta-2.sfbay.sun.com>; Wed, 20 May 2009 15:53:26 -0700 (PDT) Received: from jurassic-x4600.sfbay.sun.com ([129.146.17.59]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJY00HV3SX2H860@nwk-avmta-2.sfbay.sun.com>; Wed, 20 May 2009 15:53:26 -0700 (PDT) Received: from [10.7.250.88] (punchin-client-10-7-250-88.SFBay.Sun.COM [10.7.250.88]) by jurassic-x4600.sfbay.sun.com (8.14.3+Sun/8.14.3) with ESMTP id n4KMrP7s707156; Wed, 20 May 2009 15:53:25 -0700 (PDT) Date: Wed, 20 May 2009 15:53:25 -0700 From: Margot Miller Subject: Re: trove-2.0.4 LSARC/2009/262 In-reply-to: <4A14865B.9060307@sun.com> To: "Mark A. Carlson" Cc: LSARC-ext@sun.com, PSARC-ext@sun.com Message-id: <4A1489E5.5050601@sun.com> MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1; format=flowed Content-transfer-encoding: 8BIT X-PMX-Version: 5.4.1.325704 References: <4A147D0E.2030701@sun.com> <4A14865B.9060307@sun.com> User-Agent: Thunderbird 2.0.0.17 (X11/20081023) Status: RO Content-Length: 8694 I wouldn´t mind having a TCA to have teams document the interface classification in their native documentation. The only thing I disagree with is forcing teams to provide a man page if they don´t have the interface classification in their native documentation. Thanks Margot Mark A. Carlson wrote: > Deny - I'd change it to a TCA to "document the interface classification > in the native documentation" (follow the outline in the minority opinion). > > -- mark > > Margot Miller wrote: >> All, >> >> I have included the minority opinion written by Mark Carlson. >> >> We did in fact have quorum yesterday; our external member >> was not listed as a full member. >> >> In any case, due to the lack of perceived quorum yesterday, >> please vote on this case. >> >> Vote to approve the case as written (with the TCR) >> Vote to deny >> >> If we find we now have a majority denying the case because >> they don´t agree with the TCR, then the TCR camp will >> become the minority. >> >> Thanks >> Margot >> >> >> microsystems Systems Architecture Committee >> >> _________________________________________________________________ >> >> Subject: trove-2.0.4 >> >> Submitted by: Vivek Titamare >> >> File: LSARC/2009/262/opinion.txt >> >> Date: May, 2009 >> >> Committee: Margot Hackett Miller, Lloyd Chambers >> Minority: Mark Carlson >> >> >> Product Approval Committee: >> Solaris PAC >> solaris-pac-opinion@sun.com >> >> 1. Summary >> >> This project is one of the Linux familiarity cases; this one provides >> a library to do fast regular and primitive collections for >> Java. >> >> 2. Decision & Precedence Information >> >> The project is approved as specified in reference [1]. >> >> The project may be delivered in a minor release of Solaris. >> >> 3. Interfaces >> >> Exported Interfaces: >> >> __________________________________________________ >> | Interfaces Exported | >> |____________ ______ |____________ __ __|____________| >> |Interface | Classification | Comments| >> |_______________ __|_________________|_____________| >> | trove.jar | Uncommitted | | >> |SUNWtrove | Uncommitted | | >> |___________________|_________________|____________| >> >> >> Imported Interfaces: >> >> ______________________________________________________________ >> | Interfaces Exported | | >> |___________________|______________ __|________________________| >> |Interface | Classification | Comments | >> |_______________ __|_________________|________________________| >> | >> | SUNWj5dev | Committed | Java Development kit | >> | SUNWj5rt | Committed | Java Runtime library | >> | SUNWj6dev | Committed | Java Development kit | >> | SUNWj6rt | Committed | Java Runtime library | >> |___________________|_________________|________________________| >> >> >> >> >> 4. Opinion >> >> During review, the only real issue raised was whether this team >> should provide a man page in addition to the javadocs. The man >> page would basically give a brief description of the jar file, >> pointer to the javadocs, and state the interface stability of the jar >> file. >> Discussion ensued whether it makes sense to ship a man page >> with a jar file. Solaris developers expect man pages, but do >> Java developers? Is it worth the extra work to provide a man page >> and would Java developers even look for a man page. >> >> It was noted that this is not standard practice as most Java >> developers look >> for java documentation via javadocs, not via man. However, others >> stated that >> having a minimal man page for a java jar file would allow the interface >> classification to be visible to the end user and a few other ARC >> cases have >> already shipped man pages for jar files. >> >> There was discussion over the granularity of the jar file and does >> it make sense to have an interface stability for the overall jar. >> Currently, >> java has Public, Package, and Protected. There was debate as to >> whether that conveys enough of the stability of the jar and its >> methods to the >> developer. >> >> With all the FOSS that is being delivered into Solaris, projects are >> delivering in their native, natural form. This includes man pages, >> texinfo, >> html, and javadoc. So the problem isn't just with javadocs and jar >> files. >> There is quite a bit of FOSS out there with no interface stability >> in the external Sun documentation. This is not a problem for Sun >> project teams as they can always look at the interface tables in >> the ARC tables to determine stability level. >> >> Asking all java project teams to ship a man page in addition to >> javadocs doesn´t >> seem like the right solution and having some teams ship a man page >> and others not, does not provide consistency. >> >> There needs to more discussion to determine if it is critical that >> the ARC stability >> level be communicated to the Solaris end user for all the FOSS software >> that is being delivered. If so, a comprehensive solution needs to be >> formulated, whether it is a CLI, a man page, annotation embedded in >> the Javadocs >> (which will work for Sun products but you cant force that upstream). >> This is not being addressed in this case. Project teams can continue >> to ship documentation in their ¨natural¨form and if there is some >> stability suggested in that documentation that is fine. >> Up until now, most projects have not shipped man pages with jar >> files. This doesn´t seem to have been written down anywhere. With >> this case, we would like to make it explicit to not deliver man pages >> with jar files. This is setting precedent of ¨do not ship man pages >> with jar files.¨ This resulted in the below TCR. >> >> 5. Minority Opinion(s) >> >> Background >> >> It is not typical for programmers working with non C/C++/Assembler >> files, such as Java Jar files, to determine the >> Exported Interface stability level using the man command. Java >> programmers depend on Javadoc, Python programmers >> depend on pydoc and so forth to document interfaces and the >> stability would best be indicated there. >> Approval of OpenSolaris projects have been inconsistent in >> preferring man pages or native documentation. This opinion seeks >> to clarify the issue and define a policy for all such cases going >> forward. >> >> Best Practice >> >> Case A - Sun Developed Components >> >> 1) Sun project team developing a Jar file shall document the >> ARC interface classification in the native documentation. (i.e. >> Javadocs) >> >> Case B - Components imported from external OSS Communities >> >> 1) The OSS Community documents the interface classification in >> their native documentation >> >> a) OpenSolaris project team agrees with the classification >> and supports it >> - Javadoc or other native documentation required >> (unchanged) >> - No man page shall be allowed >> >> b) OpenSolaris project team disagrees with the >> classification >> - Javadoc or native documentation required, but >> project team must change the OSS documentation >> to match the project team's classification >> - No man page shall be allowed >> >> 2) OSS Community does not document interface classification in >> their native documentation >> a) OpenSolaris project team is strongly encouraged to >> update the native documentation to reflect the OpenSolaris project >> team >> classification. >> - Changed Javadoc or other native documentation >> required >> - No man page shall be allowed >> b) OpenSolaris project team cannot support deltas to the >> native documentation >> - Unchanged Javadoc or other native documentation >> required >> - A man page shall be provided >> >> >> >> 6. Advisory Information >> >> None. >> >> 7. Appendices >> >> 7.1. Appendix A: Technical Changes Required >> >> Do not ship man pages with Java jar files >> >> 7.2. Appendix B: Technical Changes Advised >> >> None. >> >> 7.3. Appendix C: Reference Material >> >> Unless stated otherwise, path names are relative to the case >> directory LSARC/2009/262 >> >> 1) Project Proposal file: >> >> >> LSARC/2009/262 Copyright 2009 Sun Microsystems >> _______________________________________________ >> opensolaris-arc mailing list >> opensolaris-arc@opensolaris.org > > -- > * Mark A. Carlson * > Sr. Architect > > *Systems Group* > Phone x69559 / 303-223-6139 > Email Mark.Carlson@Sun.COM > > > From tdc@computer.org Wed May 20 16:09:19 2009 Received: from sunmail2sca.sfbay.sun.com (sunmail2sca.SFBay.Sun.COM [129.145.155.234]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4KN9FbS001162; Wed, 20 May 2009 16:09:19 -0700 (PDT) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by sunmail2sca.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4KN9EoS027890; Wed, 20 May 2009 16:09:14 -0700 (PDT) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJY00201TNEW200@nwk-avmta-2.sfbay.sun.com>; Wed, 20 May 2009 16:09:14 -0700 (PDT) Received: from brmea-mail-2.sun.com ([192.18.98.43]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJY00HCRTNDHA80@nwk-avmta-2.sfbay.sun.com>; Wed, 20 May 2009 16:09:13 -0700 (PDT) Received: from relay44i.sun.com ([192.5.209.118]) by brmea-mail-2.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n4KN8ifI008766; Wed, 20 May 2009 23:09:13 +0000 (GMT) Received: from mmp43es.mmp.us.syntegra.com ([160.41.221.12] [160.41.221.12]) by relay44i.sun.com with ESMTP id BT-MMP-1259290; Wed, 20 May 2009 23:09:13 +0000 (Z) Received: from relay44i.sun.com (relay44i.sun.com [192.5.209.118]) by mmp43es.mmp.us.syntegra.com with ESMTP id BT-MMP-21542052; Wed, 20 May 2009 23:09:10 +0000 (Z) Received: from a.mail.sonic.net ([64.142.16.245] [64.142.16.245]) by relay4i.sun.com with ESMTP id BT-MMP-21584067; Wed, 20 May 2009 23:09:08 +0000 (Z) Received: from [10.0.1.5] (c-98-210-99-213.hsd1.ca.comcast.net [98.210.99.213]) (authenticated bits=0) by a.mail.sonic.net (8.13.8.Beta0-Sonic/8.13.7) with ESMTP id n4KN968M012191 (version=TLSv1/SSLv3 cipher=AES128-SHA bits=128 verify=NO); Wed, 20 May 2009 16:09:07 -0700 Date: Wed, 20 May 2009 16:09:06 -0700 From: Tom Childers Subject: Re: trove-2.0.4 LSARC/2009/262 In-reply-to: <4A1489E5.5050601@sun.com> To: LSARC-ext@sun.com, PSARC-ext@sun.com Message-id: MIME-version: 1.0 X-Mailer: Apple Mail (2.935.3) Content-type: text/plain; charset=ISO-8859-1; format=flowed; delsp=yes X-PMX-Version: 5.4.1.325704 X-Brightmail-Tracker: AAAAAA== X-Antispam: No, score=-2.6/5.0, scanned in 1.391sec at (localhost [127.0.0.1]) by smf-spamd v1.3.1 - http://smfs.sf.net/ References: <4A147D0E.2030701@sun.com> <4A14865B.9060307@sun.com> <4A1489E5.5050601@sun.com> Content-Transfer-Encoding: 8bit X-MIME-Autoconverted: from quoted-printable to 8bit by sac.sfbay.sun.com id n4KN9FbS001162 Status: RO Content-Length: 9330 Agreed. I vote to approve with the TCR, and would support a TCA to "document the interface classification in the native documentation". -tdc On May 20, 2009, at 3:53 PM, Margot Miller wrote: > I wouldn´t mind having a TCA to have teams document the > interface classification in their native documentation. The > only thing I disagree with is forcing teams to provide a man > page if they don´t have the interface classification in their > native documentation. > > Thanks > Margot > > > Mark A. Carlson wrote: >> Deny - I'd change it to a TCA to "document the interface >> classification >> in the native documentation" (follow the outline in the minority >> opinion). >> >> -- mark >> >> Margot Miller wrote: >>> All, >>> >>> I have included the minority opinion written by Mark Carlson. >>> >>> We did in fact have quorum yesterday; our external member >>> was not listed as a full member. >>> >>> In any case, due to the lack of perceived quorum yesterday, >>> please vote on this case. >>> >>> Vote to approve the case as written (with the TCR) >>> Vote to deny >>> >>> If we find we now have a majority denying the case because >>> they don´t agree with the TCR, then the TCR camp will >>> become the minority. >>> >>> Thanks >>> Margot >>> >>> >>> microsystems Systems Architecture Committee >>> >>> _________________________________________________________________ >>> >>> Subject: trove-2.0.4 >>> >>> Submitted by: Vivek Titamare >>> >>> File: LSARC/2009/262/opinion.txt >>> >>> Date: May, 2009 >>> >>> Committee: Margot Hackett Miller, Lloyd Chambers >>> Minority: Mark Carlson >>> >>> >>> Product Approval Committee: >>> Solaris PAC >>> solaris-pac-opinion@sun.com >>> >>> 1. Summary >>> >>> This project is one of the Linux familiarity cases; this one >>> provides >>> a library to do fast regular and primitive collections for >>> Java. >>> >>> 2. Decision & Precedence Information >>> >>> The project is approved as specified in reference [1]. >>> >>> The project may be delivered in a minor release of Solaris. >>> >>> 3. Interfaces >>> >>> Exported Interfaces: >>> >>> __________________________________________________ >>> | Interfaces Exported | >>> |____________ ______ |____________ __ __|____________| >>> |Interface | Classification | Comments| >>> |_______________ __|_________________|_____________| >>> | trove.jar | Uncommitted | | >>> |SUNWtrove | Uncommitted | | >>> |___________________|_________________|____________| >>> >>> >>> Imported Interfaces: >>> >>> ______________________________________________________________ >>> | Interfaces Exported | | >>> |___________________|______________ __|________________________| >>> |Interface | Classification | Comments | >>> |_______________ __|_________________|________________________| >>> | >>> | SUNWj5dev | Committed | Java Development kit | >>> | SUNWj5rt | Committed | Java Runtime library | >>> | SUNWj6dev | Committed | Java Development kit | >>> | SUNWj6rt | Committed | Java Runtime library | >>> |___________________|_________________|________________________| >>> >>> >>> >>> >>> 4. Opinion >>> >>> During review, the only real issue raised was whether this team >>> should provide a man page in addition to the javadocs. The man >>> page would basically give a brief description of the jar file, >>> pointer to the javadocs, and state the interface stability of the >>> jar file. >>> Discussion ensued whether it makes sense to ship a man page >>> with a jar file. Solaris developers expect man pages, but do >>> Java developers? Is it worth the extra work to provide a man page >>> and would Java developers even look for a man page. >>> >>> It was noted that this is not standard practice as most Java >>> developers look >>> for java documentation via javadocs, not via man. However, others >>> stated that >>> having a minimal man page for a java jar file would allow the >>> interface >>> classification to be visible to the end user and a few other ARC >>> cases have >>> already shipped man pages for jar files. >>> >>> There was discussion over the granularity of the jar file and does >>> it make sense to have an interface stability for the overall jar. >>> Currently, >>> java has Public, Package, and Protected. There was debate as to >>> whether that conveys enough of the stability of the jar and its >>> methods to the >>> developer. >>> >>> With all the FOSS that is being delivered into Solaris, projects are >>> delivering in their native, natural form. This includes man pages, >>> texinfo, >>> html, and javadoc. So the problem isn't just with javadocs and jar >>> files. >>> There is quite a bit of FOSS out there with no interface stability >>> in the external Sun documentation. This is not a problem for Sun >>> project teams as they can always look at the interface tables in >>> the ARC tables to determine stability level. >>> >>> Asking all java project teams to ship a man page in addition to >>> javadocs doesn´t >>> seem like the right solution and having some teams ship a man page >>> and others not, does not provide consistency. >>> >>> There needs to more discussion to determine if it is critical that >>> the ARC stability >>> level be communicated to the Solaris end user for all the FOSS >>> software >>> that is being delivered. If so, a comprehensive solution needs to be >>> formulated, whether it is a CLI, a man page, annotation embedded >>> in the Javadocs >>> (which will work for Sun products but you cant force that upstream). >>> This is not being addressed in this case. Project teams can >>> continue >>> to ship documentation in their ¨natural¨form and if there is some >>> stability suggested in that documentation that is fine. >>> Up until now, most projects have not shipped man pages with jar >>> files. This doesn´t seem to have been written down anywhere. With >>> this case, we would like to make it explicit to not deliver man >>> pages >>> with jar files. This is setting precedent of ¨do not ship man pages >>> with jar files.¨ This resulted in the below TCR. >>> >>> 5. Minority Opinion(s) >>> >>> Background >>> >>> It is not typical for programmers working with non C/C++/ >>> Assembler >>> files, such as Java Jar files, to determine the >>> Exported Interface stability level using the man command. Java >>> programmers depend on Javadoc, Python programmers >>> depend on pydoc and so forth to document interfaces and the >>> stability would best be indicated there. Approval of >>> OpenSolaris projects have been inconsistent in >>> preferring man pages or native documentation. This opinion >>> seeks >>> to clarify the issue and define a policy for all such cases >>> going >>> forward. >>> >>> Best Practice >>> >>> Case A - Sun Developed Components >>> >>> 1) Sun project team developing a Jar file shall document the >>> ARC interface classification in the native documentation. (i.e. >>> Javadocs) >>> >>> Case B - Components imported from external OSS Communities >>> >>> 1) The OSS Community documents the interface >>> classification in >>> their native documentation >>> >>> a) OpenSolaris project team agrees with the >>> classification >>> and supports it >>> - Javadoc or other native documentation required >>> (unchanged) >>> - No man page shall be allowed >>> >>> b) OpenSolaris project team disagrees with the >>> classification >>> - Javadoc or native documentation required, but >>> project team must change the OSS documentation >>> to match the project team's classification >>> - No man page shall be allowed >>> >>> 2) OSS Community does not document interface classification >>> in >>> their native documentation >>> a) OpenSolaris project team is strongly encouraged to >>> update the native documentation to reflect the OpenSolaris >>> project >>> team >>> classification. >>> - Changed Javadoc or other native documentation >>> required >>> - No man page shall be allowed >>> b) OpenSolaris project team cannot support deltas to the >>> native documentation >>> - Unchanged Javadoc or other native documentation >>> required >>> - A man page shall be provided >>> >>> >>> >>> 6. Advisory Information >>> >>> None. >>> >>> 7. Appendices >>> >>> 7.1. Appendix A: Technical Changes Required >>> >>> Do not ship man pages with Java jar files >>> >>> 7.2. Appendix B: Technical Changes Advised >>> >>> None. >>> >>> 7.3. Appendix C: Reference Material >>> >>> Unless stated otherwise, path names are relative to the case >>> directory LSARC/2009/262 >>> >>> 1) Project Proposal file: >>> >>> >>> LSARC/2009/262 Copyright 2009 Sun Microsystems >>> _______________________________________________ >>> opensolaris-arc mailing list >>> opensolaris-arc@opensolaris.org >> >> -- >> * Mark A. Carlson * >> Sr. Architect >> >> *Systems Group* >> Phone x69559 / 303-223-6139 >> Email Mark.Carlson@Sun.COM >> >> >> > > _______________________________________________ > opensolaris-arc mailing list > opensolaris-arc@opensolaris.org > From tdc@computer.org Wed May 20 16:09:19 2009 Received: from sunmail2sca.sfbay.sun.com (sunmail2sca.SFBay.Sun.COM [129.145.155.234]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4KN9FbS001162; Wed, 20 May 2009 16:09:19 -0700 (PDT) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by sunmail2sca.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4KN9EoS027890; Wed, 20 May 2009 16:09:14 -0700 (PDT) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJY00201TNEW200@nwk-avmta-2.sfbay.sun.com>; Wed, 20 May 2009 16:09:14 -0700 (PDT) Received: from brmea-mail-2.sun.com ([192.18.98.43]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJY00HCRTNDHA80@nwk-avmta-2.sfbay.sun.com>; Wed, 20 May 2009 16:09:13 -0700 (PDT) Received: from relay44i.sun.com ([192.5.209.118]) by brmea-mail-2.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n4KN8ifI008766; Wed, 20 May 2009 23:09:13 +0000 (GMT) Received: from mmp43es.mmp.us.syntegra.com ([160.41.221.12] [160.41.221.12]) by relay44i.sun.com with ESMTP id BT-MMP-1259290; Wed, 20 May 2009 23:09:13 +0000 (Z) Received: from relay44i.sun.com (relay44i.sun.com [192.5.209.118]) by mmp43es.mmp.us.syntegra.com with ESMTP id BT-MMP-21542052; Wed, 20 May 2009 23:09:10 +0000 (Z) Received: from a.mail.sonic.net ([64.142.16.245] [64.142.16.245]) by relay4i.sun.com with ESMTP id BT-MMP-21584067; Wed, 20 May 2009 23:09:08 +0000 (Z) Received: from [10.0.1.5] (c-98-210-99-213.hsd1.ca.comcast.net [98.210.99.213]) (authenticated bits=0) by a.mail.sonic.net (8.13.8.Beta0-Sonic/8.13.7) with ESMTP id n4KN968M012191 (version=TLSv1/SSLv3 cipher=AES128-SHA bits=128 verify=NO); Wed, 20 May 2009 16:09:07 -0700 Date: Wed, 20 May 2009 16:09:06 -0700 From: Tom Childers Subject: Re: trove-2.0.4 LSARC/2009/262 In-reply-to: <4A1489E5.5050601@sun.com> To: LSARC-ext@sun.com, PSARC-ext@sun.com Message-id: MIME-version: 1.0 X-Mailer: Apple Mail (2.935.3) Content-type: text/plain; charset=ISO-8859-1; format=flowed; delsp=yes X-PMX-Version: 5.4.1.325704 X-Brightmail-Tracker: AAAAAA== X-Antispam: No, score=-2.6/5.0, scanned in 1.391sec at (localhost [127.0.0.1]) by smf-spamd v1.3.1 - http://smfs.sf.net/ References: <4A147D0E.2030701@sun.com> <4A14865B.9060307@sun.com> <4A1489E5.5050601@sun.com> Content-Transfer-Encoding: 8bit X-MIME-Autoconverted: from quoted-printable to 8bit by sac.sfbay.sun.com id n4KN9FbS001162 Status: RO Content-Length: 9330 Agreed. I vote to approve with the TCR, and would support a TCA to "document the interface classification in the native documentation". -tdc On May 20, 2009, at 3:53 PM, Margot Miller wrote: > I wouldn´t mind having a TCA to have teams document the > interface classification in their native documentation. The > only thing I disagree with is forcing teams to provide a man > page if they don´t have the interface classification in their > native documentation. > > Thanks > Margot > > > Mark A. Carlson wrote: >> Deny - I'd change it to a TCA to "document the interface >> classification >> in the native documentation" (follow the outline in the minority >> opinion). >> >> -- mark >> >> Margot Miller wrote: >>> All, >>> >>> I have included the minority opinion written by Mark Carlson. >>> >>> We did in fact have quorum yesterday; our external member >>> was not listed as a full member. >>> >>> In any case, due to the lack of perceived quorum yesterday, >>> please vote on this case. >>> >>> Vote to approve the case as written (with the TCR) >>> Vote to deny >>> >>> If we find we now have a majority denying the case because >>> they don´t agree with the TCR, then the TCR camp will >>> become the minority. >>> >>> Thanks >>> Margot >>> >>> >>> microsystems Systems Architecture Committee >>> >>> _________________________________________________________________ >>> >>> Subject: trove-2.0.4 >>> >>> Submitted by: Vivek Titamare >>> >>> File: LSARC/2009/262/opinion.txt >>> >>> Date: May, 2009 >>> >>> Committee: Margot Hackett Miller, Lloyd Chambers >>> Minority: Mark Carlson >>> >>> >>> Product Approval Committee: >>> Solaris PAC >>> solaris-pac-opinion@sun.com >>> >>> 1. Summary >>> >>> This project is one of the Linux familiarity cases; this one >>> provides >>> a library to do fast regular and primitive collections for >>> Java. >>> >>> 2. Decision & Precedence Information >>> >>> The project is approved as specified in reference [1]. >>> >>> The project may be delivered in a minor release of Solaris. >>> >>> 3. Interfaces >>> >>> Exported Interfaces: >>> >>> __________________________________________________ >>> | Interfaces Exported | >>> |____________ ______ |____________ __ __|____________| >>> |Interface | Classification | Comments| >>> |_______________ __|_________________|_____________| >>> | trove.jar | Uncommitted | | >>> |SUNWtrove | Uncommitted | | >>> |___________________|_________________|____________| >>> >>> >>> Imported Interfaces: >>> >>> ______________________________________________________________ >>> | Interfaces Exported | | >>> |___________________|______________ __|________________________| >>> |Interface | Classification | Comments | >>> |_______________ __|_________________|________________________| >>> | >>> | SUNWj5dev | Committed | Java Development kit | >>> | SUNWj5rt | Committed | Java Runtime library | >>> | SUNWj6dev | Committed | Java Development kit | >>> | SUNWj6rt | Committed | Java Runtime library | >>> |___________________|_________________|________________________| >>> >>> >>> >>> >>> 4. Opinion >>> >>> During review, the only real issue raised was whether this team >>> should provide a man page in addition to the javadocs. The man >>> page would basically give a brief description of the jar file, >>> pointer to the javadocs, and state the interface stability of the >>> jar file. >>> Discussion ensued whether it makes sense to ship a man page >>> with a jar file. Solaris developers expect man pages, but do >>> Java developers? Is it worth the extra work to provide a man page >>> and would Java developers even look for a man page. >>> >>> It was noted that this is not standard practice as most Java >>> developers look >>> for java documentation via javadocs, not via man. However, others >>> stated that >>> having a minimal man page for a java jar file would allow the >>> interface >>> classification to be visible to the end user and a few other ARC >>> cases have >>> already shipped man pages for jar files. >>> >>> There was discussion over the granularity of the jar file and does >>> it make sense to have an interface stability for the overall jar. >>> Currently, >>> java has Public, Package, and Protected. There was debate as to >>> whether that conveys enough of the stability of the jar and its >>> methods to the >>> developer. >>> >>> With all the FOSS that is being delivered into Solaris, projects are >>> delivering in their native, natural form. This includes man pages, >>> texinfo, >>> html, and javadoc. So the problem isn't just with javadocs and jar >>> files. >>> There is quite a bit of FOSS out there with no interface stability >>> in the external Sun documentation. This is not a problem for Sun >>> project teams as they can always look at the interface tables in >>> the ARC tables to determine stability level. >>> >>> Asking all java project teams to ship a man page in addition to >>> javadocs doesn´t >>> seem like the right solution and having some teams ship a man page >>> and others not, does not provide consistency. >>> >>> There needs to more discussion to determine if it is critical that >>> the ARC stability >>> level be communicated to the Solaris end user for all the FOSS >>> software >>> that is being delivered. If so, a comprehensive solution needs to be >>> formulated, whether it is a CLI, a man page, annotation embedded >>> in the Javadocs >>> (which will work for Sun products but you cant force that upstream). >>> This is not being addressed in this case. Project teams can >>> continue >>> to ship documentation in their ¨natural¨form and if there is some >>> stability suggested in that documentation that is fine. >>> Up until now, most projects have not shipped man pages with jar >>> files. This doesn´t seem to have been written down anywhere. With >>> this case, we would like to make it explicit to not deliver man >>> pages >>> with jar files. This is setting precedent of ¨do not ship man pages >>> with jar files.¨ This resulted in the below TCR. >>> >>> 5. Minority Opinion(s) >>> >>> Background >>> >>> It is not typical for programmers working with non C/C++/ >>> Assembler >>> files, such as Java Jar files, to determine the >>> Exported Interface stability level using the man command. Java >>> programmers depend on Javadoc, Python programmers >>> depend on pydoc and so forth to document interfaces and the >>> stability would best be indicated there. Approval of >>> OpenSolaris projects have been inconsistent in >>> preferring man pages or native documentation. This opinion >>> seeks >>> to clarify the issue and define a policy for all such cases >>> going >>> forward. >>> >>> Best Practice >>> >>> Case A - Sun Developed Components >>> >>> 1) Sun project team developing a Jar file shall document the >>> ARC interface classification in the native documentation. (i.e. >>> Javadocs) >>> >>> Case B - Components imported from external OSS Communities >>> >>> 1) The OSS Community documents the interface >>> classification in >>> their native documentation >>> >>> a) OpenSolaris project team agrees with the >>> classification >>> and supports it >>> - Javadoc or other native documentation required >>> (unchanged) >>> - No man page shall be allowed >>> >>> b) OpenSolaris project team disagrees with the >>> classification >>> - Javadoc or native documentation required, but >>> project team must change the OSS documentation >>> to match the project team's classification >>> - No man page shall be allowed >>> >>> 2) OSS Community does not document interface classification >>> in >>> their native documentation >>> a) OpenSolaris project team is strongly encouraged to >>> update the native documentation to reflect the OpenSolaris >>> project >>> team >>> classification. >>> - Changed Javadoc or other native documentation >>> required >>> - No man page shall be allowed >>> b) OpenSolaris project team cannot support deltas to the >>> native documentation >>> - Unchanged Javadoc or other native documentation >>> required >>> - A man page shall be provided >>> >>> >>> >>> 6. Advisory Information >>> >>> None. >>> >>> 7. Appendices >>> >>> 7.1. Appendix A: Technical Changes Required >>> >>> Do not ship man pages with Java jar files >>> >>> 7.2. Appendix B: Technical Changes Advised >>> >>> None. >>> >>> 7.3. Appendix C: Reference Material >>> >>> Unless stated otherwise, path names are relative to the case >>> directory LSARC/2009/262 >>> >>> 1) Project Proposal file: >>> >>> >>> LSARC/2009/262 Copyright 2009 Sun Microsystems >>> _______________________________________________ >>> opensolaris-arc mailing list >>> opensolaris-arc@opensolaris.org >> >> -- >> * Mark A. Carlson * >> Sr. Architect >> >> *Systems Group* >> Phone x69559 / 303-223-6139 >> Email Mark.Carlson@Sun.COM >> >> >> > > _______________________________________________ > opensolaris-arc mailing list > opensolaris-arc@opensolaris.org > From John.Fischer@Sun.COM Wed May 20 18:28:33 2009 Received: from sunmail3mpk.sfbay.sun.com (sunmail3mpk.SFBay.Sun.COM [129.146.11.52]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4L1SXRp012622; Wed, 20 May 2009 18:28:33 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail3mpk.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4L1SXtp008642; Wed, 20 May 2009 18:28:33 -0700 (PDT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJZ00H0903LSR00@brm-avmta-1.central.sun.com>; Wed, 20 May 2009 19:28:33 -0600 (MDT) Received: from brmea-mail-4.sun.com ([192.18.98.36]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJZ00C3303JSU60@brm-avmta-1.central.sun.com>; Wed, 20 May 2009 19:28:32 -0600 (MDT) Received: from fe-amer-10.sun.com ([192.18.109.80]) by brmea-mail-4.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n4L1SVT2003020; Thu, 21 May 2009 01:28:31 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJZ00D00020EF00@mail-amer.sun.com>; Wed, 20 May 2009 19:28:31 -0600 (MDT) Received: from [192.168.10.13] ([unknown] [76.20.56.47]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJZ00BT403IFW00@mail-amer.sun.com>; Wed, 20 May 2009 19:28:31 -0600 (MDT) Date: Wed, 20 May 2009 18:27:13 -0700 From: John Fischer Subject: Re: trove-2.0.4 LSARC/2009/262 In-reply-to: Sender: John.Fischer@Sun.COM To: Tom Childers Cc: LSARC-ext@Sun.COM, PSARC-ext@Sun.COM Reply-to: John.Fischer@Sun.COM Message-id: <4A14ADF1.6030302@sun.com> MIME-version: 1.0 Content-type: text/plain; format=flowed; charset=ISO-8859-1 Content-transfer-encoding: 8BIT X-PMX-Version: 5.4.1.325704 References: <4A147D0E.2030701@sun.com> <4A14865B.9060307@sun.com> <4A1489E5.5050601@sun.com> User-Agent: Thunderbird 2.0.0.21 (X11/20090323) Status: RO Content-Length: 9609 Margot, Please put me down with the Minority group. Thanks, John Tom Childers wrote: > Agreed. I vote to approve with the TCR, and would support a TCA to > "document the interface classification in the native documentation". > -tdc > > > On May 20, 2009, at 3:53 PM, Margot Miller wrote: > >> I wouldn´t mind having a TCA to have teams document the >> interface classification in their native documentation. The >> only thing I disagree with is forcing teams to provide a man >> page if they don´t have the interface classification in their >> native documentation. >> >> Thanks >> Margot >> >> >> Mark A. Carlson wrote: >>> Deny - I'd change it to a TCA to "document the interface classification >>> in the native documentation" (follow the outline in the minority >>> opinion). >>> >>> -- mark >>> >>> Margot Miller wrote: >>>> All, >>>> >>>> I have included the minority opinion written by Mark Carlson. >>>> >>>> We did in fact have quorum yesterday; our external member >>>> was not listed as a full member. >>>> >>>> In any case, due to the lack of perceived quorum yesterday, >>>> please vote on this case. >>>> >>>> Vote to approve the case as written (with the TCR) >>>> Vote to deny >>>> >>>> If we find we now have a majority denying the case because >>>> they don´t agree with the TCR, then the TCR camp will >>>> become the minority. >>>> >>>> Thanks >>>> Margot >>>> >>>> >>>> microsystems Systems Architecture Committee >>>> >>>> _________________________________________________________________ >>>> >>>> Subject: trove-2.0.4 >>>> >>>> Submitted by: Vivek Titamare >>>> >>>> File: LSARC/2009/262/opinion.txt >>>> >>>> Date: May, 2009 >>>> >>>> Committee: Margot Hackett Miller, Lloyd Chambers >>>> Minority: Mark Carlson >>>> >>>> >>>> Product Approval Committee: >>>> Solaris PAC >>>> solaris-pac-opinion@sun.com >>>> >>>> 1. Summary >>>> >>>> This project is one of the Linux familiarity cases; this one provides >>>> a library to do fast regular and primitive collections for >>>> Java. >>>> >>>> 2. Decision & Precedence Information >>>> >>>> The project is approved as specified in reference [1]. >>>> >>>> The project may be delivered in a minor release of Solaris. >>>> >>>> 3. Interfaces >>>> >>>> Exported Interfaces: >>>> >>>> __________________________________________________ >>>> | Interfaces Exported | >>>> |____________ ______ |____________ __ __|____________| >>>> |Interface | Classification | Comments| >>>> |_______________ __|_________________|_____________| >>>> | trove.jar | Uncommitted | | >>>> |SUNWtrove | Uncommitted | | >>>> |___________________|_________________|____________| >>>> >>>> >>>> Imported Interfaces: >>>> >>>> ______________________________________________________________ >>>> | Interfaces Exported | | >>>> |___________________|______________ __|________________________| >>>> |Interface | Classification | Comments | >>>> |_______________ __|_________________|________________________| >>>> | >>>> | SUNWj5dev | Committed | Java Development kit | >>>> | SUNWj5rt | Committed | Java Runtime library | >>>> | SUNWj6dev | Committed | Java Development kit | >>>> | SUNWj6rt | Committed | Java Runtime library | >>>> |___________________|_________________|________________________| >>>> >>>> >>>> >>>> >>>> 4. Opinion >>>> >>>> During review, the only real issue raised was whether this team >>>> should provide a man page in addition to the javadocs. The man >>>> page would basically give a brief description of the jar file, >>>> pointer to the javadocs, and state the interface stability of the >>>> jar file. >>>> Discussion ensued whether it makes sense to ship a man page >>>> with a jar file. Solaris developers expect man pages, but do >>>> Java developers? Is it worth the extra work to provide a man page >>>> and would Java developers even look for a man page. >>>> >>>> It was noted that this is not standard practice as most Java >>>> developers look >>>> for java documentation via javadocs, not via man. However, others >>>> stated that >>>> having a minimal man page for a java jar file would allow the interface >>>> classification to be visible to the end user and a few other ARC >>>> cases have >>>> already shipped man pages for jar files. >>>> >>>> There was discussion over the granularity of the jar file and does >>>> it make sense to have an interface stability for the overall jar. >>>> Currently, >>>> java has Public, Package, and Protected. There was debate as to >>>> whether that conveys enough of the stability of the jar and its >>>> methods to the >>>> developer. >>>> >>>> With all the FOSS that is being delivered into Solaris, projects are >>>> delivering in their native, natural form. This includes man pages, >>>> texinfo, >>>> html, and javadoc. So the problem isn't just with javadocs and jar >>>> files. >>>> There is quite a bit of FOSS out there with no interface stability >>>> in the external Sun documentation. This is not a problem for Sun >>>> project teams as they can always look at the interface tables in >>>> the ARC tables to determine stability level. >>>> >>>> Asking all java project teams to ship a man page in addition to >>>> javadocs doesn´t >>>> seem like the right solution and having some teams ship a man page >>>> and others not, does not provide consistency. >>>> >>>> There needs to more discussion to determine if it is critical that >>>> the ARC stability >>>> level be communicated to the Solaris end user for all the FOSS software >>>> that is being delivered. If so, a comprehensive solution needs to be >>>> formulated, whether it is a CLI, a man page, annotation embedded in >>>> the Javadocs >>>> (which will work for Sun products but you cant force that upstream). >>>> This is not being addressed in this case. Project teams can continue >>>> to ship documentation in their ¨natural¨form and if there is some >>>> stability suggested in that documentation that is fine. >>>> Up until now, most projects have not shipped man pages with jar >>>> files. This doesn´t seem to have been written down anywhere. With >>>> this case, we would like to make it explicit to not deliver man pages >>>> with jar files. This is setting precedent of ¨do not ship man pages >>>> with jar files.¨ This resulted in the below TCR. >>>> >>>> 5. Minority Opinion(s) >>>> >>>> Background >>>> >>>> It is not typical for programmers working with non C/C++/Assembler >>>> files, such as Java Jar files, to determine the >>>> Exported Interface stability level using the man command. Java >>>> programmers depend on Javadoc, Python programmers >>>> depend on pydoc and so forth to document interfaces and the >>>> stability would best be indicated there. Approval of >>>> OpenSolaris projects have been inconsistent in >>>> preferring man pages or native documentation. This opinion seeks >>>> to clarify the issue and define a policy for all such cases going >>>> forward. >>>> >>>> Best Practice >>>> >>>> Case A - Sun Developed Components >>>> >>>> 1) Sun project team developing a Jar file shall document the >>>> ARC interface classification in the native documentation. (i.e. >>>> Javadocs) >>>> >>>> Case B - Components imported from external OSS Communities >>>> >>>> 1) The OSS Community documents the interface classification in >>>> their native documentation >>>> >>>> a) OpenSolaris project team agrees with the classification >>>> and supports it >>>> - Javadoc or other native documentation required >>>> (unchanged) >>>> - No man page shall be allowed >>>> >>>> b) OpenSolaris project team disagrees with the >>>> classification >>>> - Javadoc or native documentation required, but >>>> project team must change the OSS documentation >>>> to match the project team's classification >>>> - No man page shall be allowed >>>> >>>> 2) OSS Community does not document interface classification in >>>> their native documentation >>>> a) OpenSolaris project team is strongly encouraged to >>>> update the native documentation to reflect the OpenSolaris project >>>> team >>>> classification. >>>> - Changed Javadoc or other native documentation >>>> required >>>> - No man page shall be allowed >>>> b) OpenSolaris project team cannot support deltas to the >>>> native documentation >>>> - Unchanged Javadoc or other native documentation >>>> required >>>> - A man page shall be provided >>>> >>>> >>>> >>>> 6. Advisory Information >>>> >>>> None. >>>> >>>> 7. Appendices >>>> >>>> 7.1. Appendix A: Technical Changes Required >>>> >>>> Do not ship man pages with Java jar files >>>> >>>> 7.2. Appendix B: Technical Changes Advised >>>> >>>> None. >>>> >>>> 7.3. Appendix C: Reference Material >>>> >>>> Unless stated otherwise, path names are relative to the case >>>> directory LSARC/2009/262 >>>> >>>> 1) Project Proposal file: >>>> >>>> >>>> LSARC/2009/262 Copyright 2009 Sun Microsystems >>>> _______________________________________________ >>>> opensolaris-arc mailing list >>>> opensolaris-arc@opensolaris.org >>> >>> -- >>> * Mark A. Carlson * >>> Sr. Architect >>> >>> *Systems Group* >>> Phone x69559 / 303-223-6139 >>> Email Mark.Carlson@Sun.COM >>> >>> >>> >> >> _______________________________________________ >> opensolaris-arc mailing list >> opensolaris-arc@opensolaris.org >> > From John.Fischer@Sun.COM Wed May 20 18:28:33 2009 Received: from sunmail3mpk.sfbay.sun.com (sunmail3mpk.SFBay.Sun.COM [129.146.11.52]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4L1SXRp012622; Wed, 20 May 2009 18:28:33 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail3mpk.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id n4L1SXtp008642; Wed, 20 May 2009 18:28:33 -0700 (PDT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KJZ00H0903LSR00@brm-avmta-1.central.sun.com>; Wed, 20 May 2009 19:28:33 -0600 (MDT) Received: from brmea-mail-4.sun.com ([192.18.98.36]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KJZ00C3303JSU60@brm-avmta-1.central.sun.com>; Wed, 20 May 2009 19:28:32 -0600 (MDT) Received: from fe-amer-10.sun.com ([192.18.109.80]) by brmea-mail-4.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n4L1SVT2003020; Thu, 21 May 2009 01:28:31 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KJZ00D00020EF00@mail-amer.sun.com>; Wed, 20 May 2009 19:28:31 -0600 (MDT) Received: from [192.168.10.13] ([unknown] [76.20.56.47]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KJZ00BT403IFW00@mail-amer.sun.com>; Wed, 20 May 2009 19:28:31 -0600 (MDT) Date: Wed, 20 May 2009 18:27:13 -0700 From: John Fischer Subject: Re: trove-2.0.4 LSARC/2009/262 In-reply-to: Sender: John.Fischer@Sun.COM To: Tom Childers Cc: LSARC-ext@Sun.COM, PSARC-ext@Sun.COM Reply-to: John.Fischer@Sun.COM Message-id: <4A14ADF1.6030302@sun.com> MIME-version: 1.0 Content-type: text/plain; format=flowed; charset=ISO-8859-1 Content-transfer-encoding: 8BIT X-PMX-Version: 5.4.1.325704 References: <4A147D0E.2030701@sun.com> <4A14865B.9060307@sun.com> <4A1489E5.5050601@sun.com> User-Agent: Thunderbird 2.0.0.21 (X11/20090323) Status: RO Content-Length: 9609 Margot, Please put me down with the Minority group. Thanks, John Tom Childers wrote: > Agreed. I vote to approve with the TCR, and would support a TCA to > "document the interface classification in the native documentation". > -tdc > > > On May 20, 2009, at 3:53 PM, Margot Miller wrote: > >> I wouldn´t mind having a TCA to have teams document the >> interface classification in their native documentation. The >> only thing I disagree with is forcing teams to provide a man >> page if they don´t have the interface classification in their >> native documentation. >> >> Thanks >> Margot >> >> >> Mark A. Carlson wrote: >>> Deny - I'd change it to a TCA to "document the interface classification >>> in the native documentation" (follow the outline in the minority >>> opinion). >>> >>> -- mark >>> >>> Margot Miller wrote: >>>> All, >>>> >>>> I have included the minority opinion written by Mark Carlson. >>>> >>>> We did in fact have quorum yesterday; our external member >>>> was not listed as a full member. >>>> >>>> In any case, due to the lack of perceived quorum yesterday, >>>> please vote on this case. >>>> >>>> Vote to approve the case as written (with the TCR) >>>> Vote to deny >>>> >>>> If we find we now have a majority denying the case because >>>> they don´t agree with the TCR, then the TCR camp will >>>> become the minority. >>>> >>>> Thanks >>>> Margot >>>> >>>> >>>> microsystems Systems Architecture Committee >>>> >>>> _________________________________________________________________ >>>> >>>> Subject: trove-2.0.4 >>>> >>>> Submitted by: Vivek Titamare >>>> >>>> File: LSARC/2009/262/opinion.txt >>>> >>>> Date: May, 2009 >>>> >>>> Committee: Margot Hackett Miller, Lloyd Chambers >>>> Minority: Mark Carlson >>>> >>>> >>>> Product Approval Committee: >>>> Solaris PAC >>>> solaris-pac-opinion@sun.com >>>> >>>> 1. Summary >>>> >>>> This project is one of the Linux familiarity cases; this one provides >>>> a library to do fast regular and primitive collections for >>>> Java. >>>> >>>> 2. Decision & Precedence Information >>>> >>>> The project is approved as specified in reference [1]. >>>> >>>> The project may be delivered in a minor release of Solaris. >>>> >>>> 3. Interfaces >>>> >>>> Exported Interfaces: >>>> >>>> __________________________________________________ >>>> | Interfaces Exported | >>>> |____________ ______ |____________ __ __|____________| >>>> |Interface | Classification | Comments| >>>> |_______________ __|_________________|_____________| >>>> | trove.jar | Uncommitted | | >>>> |SUNWtrove | Uncommitted | | >>>> |___________________|_________________|____________| >>>> >>>> >>>> Imported Interfaces: >>>> >>>> ______________________________________________________________ >>>> | Interfaces Exported | | >>>> |___________________|______________ __|________________________| >>>> |Interface | Classification | Comments | >>>> |_______________ __|_________________|________________________| >>>> | >>>> | SUNWj5dev | Committed | Java Development kit | >>>> | SUNWj5rt | Committed | Java Runtime library | >>>> | SUNWj6dev | Committed | Java Development kit | >>>> | SUNWj6rt | Committed | Java Runtime library | >>>> |___________________|_________________|________________________| >>>> >>>> >>>> >>>> >>>> 4. Opinion >>>> >>>> During review, the only real issue raised was whether this team >>>> should provide a man page in addition to the javadocs. The man >>>> page would basically give a brief description of the jar file, >>>> pointer to the javadocs, and state the interface stability of the >>>> jar file. >>>> Discussion ensued whether it makes sense to ship a man page >>>> with a jar file. Solaris developers expect man pages, but do >>>> Java developers? Is it worth the extra work to provide a man page >>>> and would Java developers even look for a man page. >>>> >>>> It was noted that this is not standard practice as most Java >>>> developers look >>>> for java documentation via javadocs, not via man. However, others >>>> stated that >>>> having a minimal man page for a java jar file would allow the interface >>>> classification to be visible to the end user and a few other ARC >>>> cases have >>>> already shipped man pages for jar files. >>>> >>>> There was discussion over the granularity of the jar file and does >>>> it make sense to have an interface stability for the overall jar. >>>> Currently, >>>> java has Public, Package, and Protected. There was debate as to >>>> whether that conveys enough of the stability of the jar and its >>>> methods to the >>>> developer. >>>> >>>> With all the FOSS that is being delivered into Solaris, projects are >>>> delivering in their native, natural form. This includes man pages, >>>> texinfo, >>>> html, and javadoc. So the problem isn't just with javadocs and jar >>>> files. >>>> There is quite a bit of FOSS out there with no interface stability >>>> in the external Sun documentation. This is not a problem for Sun >>>> project teams as they can always look at the interface tables in >>>> the ARC tables to determine stability level. >>>> >>>> Asking all java project teams to ship a man page in addition to >>>> javadocs doesn´t >>>> seem like the right solution and having some teams ship a man page >>>> and others not, does not provide consistency. >>>> >>>> There needs to more discussion to determine if it is critical that >>>> the ARC stability >>>> level be communicated to the Solaris end user for all the FOSS software >>>> that is being delivered. If so, a comprehensive solution needs to be >>>> formulated, whether it is a CLI, a man page, annotation embedded in >>>> the Javadocs >>>> (which will work for Sun products but you cant force that upstream). >>>> This is not being addressed in this case. Project teams can continue >>>> to ship documentation in their ¨natural¨form and if there is some >>>> stability suggested in that documentation that is fine. >>>> Up until now, most projects have not shipped man pages with jar >>>> files. This doesn´t seem to have been written down anywhere. With >>>> this case, we would like to make it explicit to not deliver man pages >>>> with jar files. This is setting precedent of ¨do not ship man pages >>>> with jar files.¨ This resulted in the below TCR. >>>> >>>> 5. Minority Opinion(s) >>>> >>>> Background >>>> >>>> It is not typical for programmers working with non C/C++/Assembler >>>> files, such as Java Jar files, to determine the >>>> Exported Interface stability level using the man command. Java >>>> programmers depend on Javadoc, Python programmers >>>> depend on pydoc and so forth to document interfaces and the >>>> stability would best be indicated there. Approval of >>>> OpenSolaris projects have been inconsistent in >>>> preferring man pages or native documentation. This opinion seeks >>>> to clarify the issue and define a policy for all such cases going >>>> forward. >>>> >>>> Best Practice >>>> >>>> Case A - Sun Developed Components >>>> >>>> 1) Sun project team developing a Jar file shall document the >>>> ARC interface classification in the native documentation. (i.e. >>>> Javadocs) >>>> >>>> Case B - Components imported from external OSS Communities >>>> >>>> 1) The OSS Community documents the interface classification in >>>> their native documentation >>>> >>>> a) OpenSolaris project team agrees with the classification >>>> and supports it >>>> - Javadoc or other native documentation required >>>> (unchanged) >>>> - No man page shall be allowed >>>> >>>> b) OpenSolaris project team disagrees with the >>>> classification >>>> - Javadoc or native documentation required, but >>>> project team must change the OSS documentation >>>> to match the project team's classification >>>> - No man page shall be allowed >>>> >>>> 2) OSS Community does not document interface classification in >>>> their native documentation >>>> a) OpenSolaris project team is strongly encouraged to >>>> update the native documentation to reflect the OpenSolaris project >>>> team >>>> classification. >>>> - Changed Javadoc or other native documentation >>>> required >>>> - No man page shall be allowed >>>> b) OpenSolaris project team cannot support deltas to the >>>> native documentation >>>> - Unchanged Javadoc or other native documentation >>>> required >>>> - A man page shall be provided >>>> >>>> >>>> >>>> 6. Advisory Information >>>> >>>> None. >>>> >>>> 7. Appendices >>>> >>>> 7.1. Appendix A: Technical Changes Required >>>> >>>> Do not ship man pages with Java jar files >>>> >>>> 7.2. Appendix B: Technical Changes Advised >>>> >>>> None. >>>> >>>> 7.3. Appendix C: Reference Material >>>> >>>> Unless stated otherwise, path names are relative to the case >>>> directory LSARC/2009/262 >>>> >>>> 1) Project Proposal file: >>>> >>>> >>>> LSARC/2009/262 Copyright 2009 Sun Microsystems >>>> _______________________________________________ >>>> opensolaris-arc mailing list >>>> opensolaris-arc@opensolaris.org >>> >>> -- >>> * Mark A. Carlson * >>> Sr. Architect >>> >>> *Systems Group* >>> Phone x69559 / 303-223-6139 >>> Email Mark.Carlson@Sun.COM >>> >>> >>> >> >> _______________________________________________ >> opensolaris-arc mailing list >> opensolaris-arc@opensolaris.org >> > From aniruddh.dikhit@sun.com Thu May 21 18:25:53 2009 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4M1Pqq7025050; Thu, 21 May 2009 18:25:53 -0700 (PDT) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by sunmail5.uk.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n4M1PnXR007929; Fri, 22 May 2009 02:25:50 +0100 (BST) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KK00090DUN1C100@nwk-avmta-2.sfbay.sun.com>; Thu, 21 May 2009 18:25:49 -0700 (PDT) Received: from jurassic-x4600.sfbay.sun.com ([129.146.17.63]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KK0008O7UN1PW00@nwk-avmta-2.sfbay.sun.com>; Thu, 21 May 2009 18:25:49 -0700 (PDT) Received: from aniruddh-dikhits-macbook-pro.local (vpn-129-150-16-1.SFBay.Sun.COM [129.150.16.1]) by jurassic-x4600.sfbay.sun.com (8.14.3+Sun/8.14.3) with ESMTP id n4M1PkC9963933; Thu, 21 May 2009 18:25:46 -0700 (PDT) Date: Thu, 21 May 2009 18:25:54 -0700 From: Aniruddh Dikhit Subject: Re: trove-2.0.4 LSARC/2009/262 In-reply-to: <4A14ADF1.6030302@sun.com> To: John.Fischer@sun.com Cc: Tom Childers , LSARC-ext@sun.com, PSARC-ext@sun.com Message-id: <4A15FF22.3040403@sun.com> MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1; format=flowed Content-transfer-encoding: 8BIT X-PMX-Version: 5.4.1.325704 References: <4A147D0E.2030701@sun.com> <4A14865B.9060307@sun.com> <4A1489E5.5050601@sun.com> <4A14ADF1.6030302@sun.com> User-Agent: Thunderbird 2.0.0.21 (Macintosh/20090302) Status: RO Content-Length: 10034 Margot I am more aligned with the minority opinion on this issue. -Aniruddh John Fischer wrote: > Margot, > > Please put me down with the Minority group. > > Thanks, > > John > > > Tom Childers wrote: >> Agreed. I vote to approve with the TCR, and would support a TCA to >> "document the interface classification in the native documentation". >> -tdc >> >> >> On May 20, 2009, at 3:53 PM, Margot Miller wrote: >> >>> I wouldn´t mind having a TCA to have teams document the >>> interface classification in their native documentation. The >>> only thing I disagree with is forcing teams to provide a man >>> page if they don´t have the interface classification in their >>> native documentation. >>> >>> Thanks >>> Margot >>> >>> >>> Mark A. Carlson wrote: >>>> Deny - I'd change it to a TCA to "document the interface >>>> classification >>>> in the native documentation" (follow the outline in the minority >>>> opinion). >>>> >>>> -- mark >>>> >>>> Margot Miller wrote: >>>>> All, >>>>> >>>>> I have included the minority opinion written by Mark Carlson. >>>>> >>>>> We did in fact have quorum yesterday; our external member >>>>> was not listed as a full member. >>>>> >>>>> In any case, due to the lack of perceived quorum yesterday, >>>>> please vote on this case. >>>>> >>>>> Vote to approve the case as written (with the TCR) >>>>> Vote to deny >>>>> >>>>> If we find we now have a majority denying the case because >>>>> they don´t agree with the TCR, then the TCR camp will >>>>> become the minority. >>>>> >>>>> Thanks >>>>> Margot >>>>> >>>>> >>>>> microsystems Systems Architecture Committee >>>>> >>>>> _________________________________________________________________ >>>>> >>>>> Subject: trove-2.0.4 >>>>> >>>>> Submitted by: Vivek Titamare >>>>> >>>>> File: LSARC/2009/262/opinion.txt >>>>> >>>>> Date: May, 2009 >>>>> >>>>> Committee: Margot Hackett Miller, Lloyd Chambers >>>>> Minority: Mark Carlson >>>>> >>>>> >>>>> Product Approval Committee: >>>>> Solaris PAC >>>>> solaris-pac-opinion@sun.com >>>>> >>>>> 1. Summary >>>>> >>>>> This project is one of the Linux familiarity cases; this one provides >>>>> a library to do fast regular and primitive collections for >>>>> Java. >>>>> >>>>> 2. Decision & Precedence Information >>>>> >>>>> The project is approved as specified in reference [1]. >>>>> >>>>> The project may be delivered in a minor release of Solaris. >>>>> >>>>> 3. Interfaces >>>>> >>>>> Exported Interfaces: >>>>> >>>>> __________________________________________________ >>>>> | Interfaces Exported | >>>>> |____________ ______ |____________ __ __|____________| >>>>> |Interface | Classification | Comments| >>>>> |_______________ __|_________________|_____________| >>>>> | trove.jar | Uncommitted | | >>>>> |SUNWtrove | Uncommitted | | >>>>> |___________________|_________________|____________| >>>>> >>>>> >>>>> Imported Interfaces: >>>>> >>>>> ______________________________________________________________ >>>>> | Interfaces Exported | | >>>>> |___________________|______________ __|________________________| >>>>> |Interface | Classification | Comments | >>>>> |_______________ __|_________________|________________________| >>>>> | >>>>> | SUNWj5dev | Committed | Java Development kit | >>>>> | SUNWj5rt | Committed | Java Runtime library | >>>>> | SUNWj6dev | Committed | Java Development kit | >>>>> | SUNWj6rt | Committed | Java Runtime library | >>>>> |___________________|_________________|________________________| >>>>> >>>>> >>>>> >>>>> >>>>> 4. Opinion >>>>> >>>>> During review, the only real issue raised was whether this team >>>>> should provide a man page in addition to the javadocs. The man >>>>> page would basically give a brief description of the jar file, >>>>> pointer to the javadocs, and state the interface stability of the >>>>> jar file. >>>>> Discussion ensued whether it makes sense to ship a man page >>>>> with a jar file. Solaris developers expect man pages, but do >>>>> Java developers? Is it worth the extra work to provide a man page >>>>> and would Java developers even look for a man page. >>>>> >>>>> It was noted that this is not standard practice as most Java >>>>> developers look >>>>> for java documentation via javadocs, not via man. However, others >>>>> stated that >>>>> having a minimal man page for a java jar file would allow the >>>>> interface >>>>> classification to be visible to the end user and a few other ARC >>>>> cases have >>>>> already shipped man pages for jar files. >>>>> >>>>> There was discussion over the granularity of the jar file and does >>>>> it make sense to have an interface stability for the overall jar. >>>>> Currently, >>>>> java has Public, Package, and Protected. There was debate as to >>>>> whether that conveys enough of the stability of the jar and its >>>>> methods to the >>>>> developer. >>>>> >>>>> With all the FOSS that is being delivered into Solaris, projects are >>>>> delivering in their native, natural form. This includes man pages, >>>>> texinfo, >>>>> html, and javadoc. So the problem isn't just with javadocs and jar >>>>> files. >>>>> There is quite a bit of FOSS out there with no interface stability >>>>> in the external Sun documentation. This is not a problem for Sun >>>>> project teams as they can always look at the interface tables in >>>>> the ARC tables to determine stability level. >>>>> >>>>> Asking all java project teams to ship a man page in addition to >>>>> javadocs doesn´t >>>>> seem like the right solution and having some teams ship a man page >>>>> and others not, does not provide consistency. >>>>> >>>>> There needs to more discussion to determine if it is critical that >>>>> the ARC stability >>>>> level be communicated to the Solaris end user for all the FOSS >>>>> software >>>>> that is being delivered. If so, a comprehensive solution needs to be >>>>> formulated, whether it is a CLI, a man page, annotation embedded >>>>> in the Javadocs >>>>> (which will work for Sun products but you cant force that upstream). >>>>> This is not being addressed in this case. Project teams can continue >>>>> to ship documentation in their ¨natural¨form and if there is some >>>>> stability suggested in that documentation that is fine. >>>>> Up until now, most projects have not shipped man pages with jar >>>>> files. This doesn´t seem to have been written down anywhere. With >>>>> this case, we would like to make it explicit to not deliver man pages >>>>> with jar files. This is setting precedent of ¨do not ship man pages >>>>> with jar files.¨ This resulted in the below TCR. >>>>> >>>>> 5. Minority Opinion(s) >>>>> >>>>> Background >>>>> >>>>> It is not typical for programmers working with non >>>>> C/C++/Assembler >>>>> files, such as Java Jar files, to determine the >>>>> Exported Interface stability level using the man command. Java >>>>> programmers depend on Javadoc, Python programmers >>>>> depend on pydoc and so forth to document interfaces and the >>>>> stability would best be indicated there. Approval of >>>>> OpenSolaris projects have been inconsistent in >>>>> preferring man pages or native documentation. This opinion seeks >>>>> to clarify the issue and define a policy for all such cases going >>>>> forward. >>>>> >>>>> Best Practice >>>>> >>>>> Case A - Sun Developed Components >>>>> >>>>> 1) Sun project team developing a Jar file shall document the >>>>> ARC interface classification in the native documentation. (i.e. >>>>> Javadocs) >>>>> >>>>> Case B - Components imported from external OSS Communities >>>>> >>>>> 1) The OSS Community documents the interface >>>>> classification in >>>>> their native documentation >>>>> >>>>> a) OpenSolaris project team agrees with the >>>>> classification >>>>> and supports it >>>>> - Javadoc or other native documentation required >>>>> (unchanged) >>>>> - No man page shall be allowed >>>>> >>>>> b) OpenSolaris project team disagrees with the >>>>> classification >>>>> - Javadoc or native documentation required, but >>>>> project team must change the OSS documentation >>>>> to match the project team's classification >>>>> - No man page shall be allowed >>>>> >>>>> 2) OSS Community does not document interface classification in >>>>> their native documentation >>>>> a) OpenSolaris project team is strongly encouraged to >>>>> update the native documentation to reflect the OpenSolaris >>>>> project >>>>> team >>>>> classification. >>>>> - Changed Javadoc or other native documentation >>>>> required >>>>> - No man page shall be allowed >>>>> b) OpenSolaris project team cannot support deltas to the >>>>> native documentation >>>>> - Unchanged Javadoc or other native documentation >>>>> required >>>>> - A man page shall be provided >>>>> >>>>> >>>>> >>>>> 6. Advisory Information >>>>> >>>>> None. >>>>> >>>>> 7. Appendices >>>>> >>>>> 7.1. Appendix A: Technical Changes Required >>>>> >>>>> Do not ship man pages with Java jar files >>>>> >>>>> 7.2. Appendix B: Technical Changes Advised >>>>> >>>>> None. >>>>> >>>>> 7.3. Appendix C: Reference Material >>>>> >>>>> Unless stated otherwise, path names are relative to the case >>>>> directory LSARC/2009/262 >>>>> >>>>> 1) Project Proposal file: >>>>> >>>>> >>>>> LSARC/2009/262 Copyright 2009 Sun Microsystems >>>>> _______________________________________________ >>>>> opensolaris-arc mailing list >>>>> opensolaris-arc@opensolaris.org >>>> >>>> -- >>>> * Mark A. Carlson * >>>> Sr. Architect >>>> >>>> *Systems Group* >>>> Phone x69559 / 303-223-6139 >>>> Email Mark.Carlson@Sun.COM >>>> >>>> >>> >>> _______________________________________________ >>> opensolaris-arc mailing list >>> opensolaris-arc@opensolaris.org >>> >> > From aniruddh.dikhit@sun.com Thu May 21 18:25:53 2009 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4M1Pqq7025050; Thu, 21 May 2009 18:25:53 -0700 (PDT) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by sunmail5.uk.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n4M1PnXR007929; Fri, 22 May 2009 02:25:50 +0100 (BST) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KK00090DUN1C100@nwk-avmta-2.sfbay.sun.com>; Thu, 21 May 2009 18:25:49 -0700 (PDT) Received: from jurassic-x4600.sfbay.sun.com ([129.146.17.63]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KK0008O7UN1PW00@nwk-avmta-2.sfbay.sun.com>; Thu, 21 May 2009 18:25:49 -0700 (PDT) Received: from aniruddh-dikhits-macbook-pro.local (vpn-129-150-16-1.SFBay.Sun.COM [129.150.16.1]) by jurassic-x4600.sfbay.sun.com (8.14.3+Sun/8.14.3) with ESMTP id n4M1PkC9963933; Thu, 21 May 2009 18:25:46 -0700 (PDT) Date: Thu, 21 May 2009 18:25:54 -0700 From: Aniruddh Dikhit Subject: Re: trove-2.0.4 LSARC/2009/262 In-reply-to: <4A14ADF1.6030302@sun.com> To: John.Fischer@sun.com Cc: Tom Childers , LSARC-ext@sun.com, PSARC-ext@sun.com Message-id: <4A15FF22.3040403@sun.com> MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1; format=flowed Content-transfer-encoding: 8BIT X-PMX-Version: 5.4.1.325704 References: <4A147D0E.2030701@sun.com> <4A14865B.9060307@sun.com> <4A1489E5.5050601@sun.com> <4A14ADF1.6030302@sun.com> User-Agent: Thunderbird 2.0.0.21 (Macintosh/20090302) Status: RO Content-Length: 10034 Margot I am more aligned with the minority opinion on this issue. -Aniruddh John Fischer wrote: > Margot, > > Please put me down with the Minority group. > > Thanks, > > John > > > Tom Childers wrote: >> Agreed. I vote to approve with the TCR, and would support a TCA to >> "document the interface classification in the native documentation". >> -tdc >> >> >> On May 20, 2009, at 3:53 PM, Margot Miller wrote: >> >>> I wouldn´t mind having a TCA to have teams document the >>> interface classification in their native documentation. The >>> only thing I disagree with is forcing teams to provide a man >>> page if they don´t have the interface classification in their >>> native documentation. >>> >>> Thanks >>> Margot >>> >>> >>> Mark A. Carlson wrote: >>>> Deny - I'd change it to a TCA to "document the interface >>>> classification >>>> in the native documentation" (follow the outline in the minority >>>> opinion). >>>> >>>> -- mark >>>> >>>> Margot Miller wrote: >>>>> All, >>>>> >>>>> I have included the minority opinion written by Mark Carlson. >>>>> >>>>> We did in fact have quorum yesterday; our external member >>>>> was not listed as a full member. >>>>> >>>>> In any case, due to the lack of perceived quorum yesterday, >>>>> please vote on this case. >>>>> >>>>> Vote to approve the case as written (with the TCR) >>>>> Vote to deny >>>>> >>>>> If we find we now have a majority denying the case because >>>>> they don´t agree with the TCR, then the TCR camp will >>>>> become the minority. >>>>> >>>>> Thanks >>>>> Margot >>>>> >>>>> >>>>> microsystems Systems Architecture Committee >>>>> >>>>> _________________________________________________________________ >>>>> >>>>> Subject: trove-2.0.4 >>>>> >>>>> Submitted by: Vivek Titamare >>>>> >>>>> File: LSARC/2009/262/opinion.txt >>>>> >>>>> Date: May, 2009 >>>>> >>>>> Committee: Margot Hackett Miller, Lloyd Chambers >>>>> Minority: Mark Carlson >>>>> >>>>> >>>>> Product Approval Committee: >>>>> Solaris PAC >>>>> solaris-pac-opinion@sun.com >>>>> >>>>> 1. Summary >>>>> >>>>> This project is one of the Linux familiarity cases; this one provides >>>>> a library to do fast regular and primitive collections for >>>>> Java. >>>>> >>>>> 2. Decision & Precedence Information >>>>> >>>>> The project is approved as specified in reference [1]. >>>>> >>>>> The project may be delivered in a minor release of Solaris. >>>>> >>>>> 3. Interfaces >>>>> >>>>> Exported Interfaces: >>>>> >>>>> __________________________________________________ >>>>> | Interfaces Exported | >>>>> |____________ ______ |____________ __ __|____________| >>>>> |Interface | Classification | Comments| >>>>> |_______________ __|_________________|_____________| >>>>> | trove.jar | Uncommitted | | >>>>> |SUNWtrove | Uncommitted | | >>>>> |___________________|_________________|____________| >>>>> >>>>> >>>>> Imported Interfaces: >>>>> >>>>> ______________________________________________________________ >>>>> | Interfaces Exported | | >>>>> |___________________|______________ __|________________________| >>>>> |Interface | Classification | Comments | >>>>> |_______________ __|_________________|________________________| >>>>> | >>>>> | SUNWj5dev | Committed | Java Development kit | >>>>> | SUNWj5rt | Committed | Java Runtime library | >>>>> | SUNWj6dev | Committed | Java Development kit | >>>>> | SUNWj6rt | Committed | Java Runtime library | >>>>> |___________________|_________________|________________________| >>>>> >>>>> >>>>> >>>>> >>>>> 4. Opinion >>>>> >>>>> During review, the only real issue raised was whether this team >>>>> should provide a man page in addition to the javadocs. The man >>>>> page would basically give a brief description of the jar file, >>>>> pointer to the javadocs, and state the interface stability of the >>>>> jar file. >>>>> Discussion ensued whether it makes sense to ship a man page >>>>> with a jar file. Solaris developers expect man pages, but do >>>>> Java developers? Is it worth the extra work to provide a man page >>>>> and would Java developers even look for a man page. >>>>> >>>>> It was noted that this is not standard practice as most Java >>>>> developers look >>>>> for java documentation via javadocs, not via man. However, others >>>>> stated that >>>>> having a minimal man page for a java jar file would allow the >>>>> interface >>>>> classification to be visible to the end user and a few other ARC >>>>> cases have >>>>> already shipped man pages for jar files. >>>>> >>>>> There was discussion over the granularity of the jar file and does >>>>> it make sense to have an interface stability for the overall jar. >>>>> Currently, >>>>> java has Public, Package, and Protected. There was debate as to >>>>> whether that conveys enough of the stability of the jar and its >>>>> methods to the >>>>> developer. >>>>> >>>>> With all the FOSS that is being delivered into Solaris, projects are >>>>> delivering in their native, natural form. This includes man pages, >>>>> texinfo, >>>>> html, and javadoc. So the problem isn't just with javadocs and jar >>>>> files. >>>>> There is quite a bit of FOSS out there with no interface stability >>>>> in the external Sun documentation. This is not a problem for Sun >>>>> project teams as they can always look at the interface tables in >>>>> the ARC tables to determine stability level. >>>>> >>>>> Asking all java project teams to ship a man page in addition to >>>>> javadocs doesn´t >>>>> seem like the right solution and having some teams ship a man page >>>>> and others not, does not provide consistency. >>>>> >>>>> There needs to more discussion to determine if it is critical that >>>>> the ARC stability >>>>> level be communicated to the Solaris end user for all the FOSS >>>>> software >>>>> that is being delivered. If so, a comprehensive solution needs to be >>>>> formulated, whether it is a CLI, a man page, annotation embedded >>>>> in the Javadocs >>>>> (which will work for Sun products but you cant force that upstream). >>>>> This is not being addressed in this case. Project teams can continue >>>>> to ship documentation in their ¨natural¨form and if there is some >>>>> stability suggested in that documentation that is fine. >>>>> Up until now, most projects have not shipped man pages with jar >>>>> files. This doesn´t seem to have been written down anywhere. With >>>>> this case, we would like to make it explicit to not deliver man pages >>>>> with jar files. This is setting precedent of ¨do not ship man pages >>>>> with jar files.¨ This resulted in the below TCR. >>>>> >>>>> 5. Minority Opinion(s) >>>>> >>>>> Background >>>>> >>>>> It is not typical for programmers working with non >>>>> C/C++/Assembler >>>>> files, such as Java Jar files, to determine the >>>>> Exported Interface stability level using the man command. Java >>>>> programmers depend on Javadoc, Python programmers >>>>> depend on pydoc and so forth to document interfaces and the >>>>> stability would best be indicated there. Approval of >>>>> OpenSolaris projects have been inconsistent in >>>>> preferring man pages or native documentation. This opinion seeks >>>>> to clarify the issue and define a policy for all such cases going >>>>> forward. >>>>> >>>>> Best Practice >>>>> >>>>> Case A - Sun Developed Components >>>>> >>>>> 1) Sun project team developing a Jar file shall document the >>>>> ARC interface classification in the native documentation. (i.e. >>>>> Javadocs) >>>>> >>>>> Case B - Components imported from external OSS Communities >>>>> >>>>> 1) The OSS Community documents the interface >>>>> classification in >>>>> their native documentation >>>>> >>>>> a) OpenSolaris project team agrees with the >>>>> classification >>>>> and supports it >>>>> - Javadoc or other native documentation required >>>>> (unchanged) >>>>> - No man page shall be allowed >>>>> >>>>> b) OpenSolaris project team disagrees with the >>>>> classification >>>>> - Javadoc or native documentation required, but >>>>> project team must change the OSS documentation >>>>> to match the project team's classification >>>>> - No man page shall be allowed >>>>> >>>>> 2) OSS Community does not document interface classification in >>>>> their native documentation >>>>> a) OpenSolaris project team is strongly encouraged to >>>>> update the native documentation to reflect the OpenSolaris >>>>> project >>>>> team >>>>> classification. >>>>> - Changed Javadoc or other native documentation >>>>> required >>>>> - No man page shall be allowed >>>>> b) OpenSolaris project team cannot support deltas to the >>>>> native documentation >>>>> - Unchanged Javadoc or other native documentation >>>>> required >>>>> - A man page shall be provided >>>>> >>>>> >>>>> >>>>> 6. Advisory Information >>>>> >>>>> None. >>>>> >>>>> 7. Appendices >>>>> >>>>> 7.1. Appendix A: Technical Changes Required >>>>> >>>>> Do not ship man pages with Java jar files >>>>> >>>>> 7.2. Appendix B: Technical Changes Advised >>>>> >>>>> None. >>>>> >>>>> 7.3. Appendix C: Reference Material >>>>> >>>>> Unless stated otherwise, path names are relative to the case >>>>> directory LSARC/2009/262 >>>>> >>>>> 1) Project Proposal file: >>>>> >>>>> >>>>> LSARC/2009/262 Copyright 2009 Sun Microsystems >>>>> _______________________________________________ >>>>> opensolaris-arc mailing list >>>>> opensolaris-arc@opensolaris.org >>>> >>>> -- >>>> * Mark A. Carlson * >>>> Sr. Architect >>>> >>>> *Systems Group* >>>> Phone x69559 / 303-223-6139 >>>> Email Mark.Carlson@Sun.COM >>>> >>>> >>> >>> _______________________________________________ >>> opensolaris-arc mailing list >>> opensolaris-arc@opensolaris.org >>> >> > From margot.miller@sun.com Thu May 21 20:26:22 2009 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4M3QLcP024569; Thu, 21 May 2009 20:26:22 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail5.uk.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n4M3QGbU017347; Fri, 22 May 2009 04:26:18 +0100 (BST) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KK100K0507T0Z00@brm-avmta-1.central.sun.com>; Thu, 21 May 2009 21:26:17 -0600 (MDT) Received: from jurassic-x4600.sfbay.sun.com ([129.146.17.59]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KK100EMJ07S8I20@brm-avmta-1.central.sun.com>; Thu, 21 May 2009 21:26:16 -0600 (MDT) Received: from [10.7.250.88] (punchin-client-10-7-250-88.SFBay.Sun.COM [10.7.250.88]) by jurassic-x4600.sfbay.sun.com (8.14.3+Sun/8.14.3) with ESMTP id n4M3QFh3107592; Thu, 21 May 2009 20:26:15 -0700 (PDT) Date: Thu, 21 May 2009 20:26:15 -0700 From: Margot Miller Subject: Re: trove-2.0.4 LSARC/2009/262 In-reply-to: <4A15FF22.3040403@sun.com> To: Aniruddh Dikhit Cc: John.Fischer@sun.com, Tom Childers , LSARC-ext@sun.com, PSARC-ext@sun.com Message-id: <4A161B57.3090404@sun.com> MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1; format=flowed Content-transfer-encoding: 8BIT X-PMX-Version: 5.4.1.325704 References: <4A147D0E.2030701@sun.com> <4A14865B.9060307@sun.com> <4A1489E5.5050601@sun.com> <4A14ADF1.6030302@sun.com> <4A15FF22.3040403@sun.com> User-Agent: Thunderbird 2.0.0.17 (X11/20081023) Status: RO Content-Length: 10144 Thanks everyone for voting. With holiday coming up lets' keep this open for a few more days to give others a chance to vote if they want to- COB Tuesday May 26th. Margot Aniruddh Dikhit wrote: > Margot > > I am more aligned with the minority opinion on this issue. > > -Aniruddh > > John Fischer wrote: >> Margot, >> >> Please put me down with the Minority group. >> >> Thanks, >> >> John >> >> >> Tom Childers wrote: >>> Agreed. I vote to approve with the TCR, and would support a TCA to >>> "document the interface classification in the native documentation". >>> -tdc >>> >>> >>> On May 20, 2009, at 3:53 PM, Margot Miller wrote: >>> >>>> I wouldn´t mind having a TCA to have teams document the >>>> interface classification in their native documentation. The >>>> only thing I disagree with is forcing teams to provide a man >>>> page if they don´t have the interface classification in their >>>> native documentation. >>>> >>>> Thanks >>>> Margot >>>> >>>> >>>> Mark A. Carlson wrote: >>>>> Deny - I'd change it to a TCA to "document the interface >>>>> classification >>>>> in the native documentation" (follow the outline in the minority >>>>> opinion). >>>>> >>>>> -- mark >>>>> >>>>> Margot Miller wrote: >>>>>> All, >>>>>> >>>>>> I have included the minority opinion written by Mark Carlson. >>>>>> >>>>>> We did in fact have quorum yesterday; our external member >>>>>> was not listed as a full member. >>>>>> >>>>>> In any case, due to the lack of perceived quorum yesterday, >>>>>> please vote on this case. >>>>>> >>>>>> Vote to approve the case as written (with the TCR) >>>>>> Vote to deny >>>>>> >>>>>> If we find we now have a majority denying the case because >>>>>> they don´t agree with the TCR, then the TCR camp will >>>>>> become the minority. >>>>>> >>>>>> Thanks >>>>>> Margot >>>>>> >>>>>> >>>>>> microsystems Systems Architecture Committee >>>>>> >>>>>> _________________________________________________________________ >>>>>> >>>>>> Subject: trove-2.0.4 >>>>>> >>>>>> Submitted by: Vivek Titamare >>>>>> >>>>>> File: LSARC/2009/262/opinion.txt >>>>>> >>>>>> Date: May, 2009 >>>>>> >>>>>> Committee: Margot Hackett Miller, Lloyd Chambers >>>>>> Minority: Mark Carlson >>>>>> >>>>>> >>>>>> Product Approval Committee: >>>>>> Solaris PAC >>>>>> solaris-pac-opinion@sun.com >>>>>> >>>>>> 1. Summary >>>>>> >>>>>> This project is one of the Linux familiarity cases; this one >>>>>> provides >>>>>> a library to do fast regular and primitive collections for >>>>>> Java. >>>>>> >>>>>> 2. Decision & Precedence Information >>>>>> >>>>>> The project is approved as specified in reference [1]. >>>>>> >>>>>> The project may be delivered in a minor release of Solaris. >>>>>> >>>>>> 3. Interfaces >>>>>> >>>>>> Exported Interfaces: >>>>>> >>>>>> __________________________________________________ >>>>>> | Interfaces Exported | >>>>>> |____________ ______ |____________ __ __|____________| >>>>>> |Interface | Classification | Comments| >>>>>> |_______________ __|_________________|_____________| >>>>>> | trove.jar | Uncommitted | | >>>>>> |SUNWtrove | Uncommitted | | >>>>>> |___________________|_________________|____________| >>>>>> >>>>>> >>>>>> Imported Interfaces: >>>>>> >>>>>> ______________________________________________________________ >>>>>> | Interfaces Exported | | >>>>>> |___________________|______________ __|________________________| >>>>>> |Interface | Classification | Comments | >>>>>> |_______________ __|_________________|________________________| >>>>>> | >>>>>> | SUNWj5dev | Committed | Java Development kit | >>>>>> | SUNWj5rt | Committed | Java Runtime library | >>>>>> | SUNWj6dev | Committed | Java Development kit | >>>>>> | SUNWj6rt | Committed | Java Runtime library | >>>>>> |___________________|_________________|________________________| >>>>>> >>>>>> >>>>>> >>>>>> >>>>>> 4. Opinion >>>>>> >>>>>> During review, the only real issue raised was whether this team >>>>>> should provide a man page in addition to the javadocs. The man >>>>>> page would basically give a brief description of the jar file, >>>>>> pointer to the javadocs, and state the interface stability of the >>>>>> jar file. >>>>>> Discussion ensued whether it makes sense to ship a man page >>>>>> with a jar file. Solaris developers expect man pages, but do >>>>>> Java developers? Is it worth the extra work to provide a man page >>>>>> and would Java developers even look for a man page. >>>>>> >>>>>> It was noted that this is not standard practice as most Java >>>>>> developers look >>>>>> for java documentation via javadocs, not via man. However, others >>>>>> stated that >>>>>> having a minimal man page for a java jar file would allow the >>>>>> interface >>>>>> classification to be visible to the end user and a few other ARC >>>>>> cases have >>>>>> already shipped man pages for jar files. >>>>>> >>>>>> There was discussion over the granularity of the jar file and does >>>>>> it make sense to have an interface stability for the overall jar. >>>>>> Currently, >>>>>> java has Public, Package, and Protected. There was debate as to >>>>>> whether that conveys enough of the stability of the jar and its >>>>>> methods to the >>>>>> developer. >>>>>> >>>>>> With all the FOSS that is being delivered into Solaris, projects are >>>>>> delivering in their native, natural form. This includes man >>>>>> pages, texinfo, >>>>>> html, and javadoc. So the problem isn't just with javadocs and >>>>>> jar files. >>>>>> There is quite a bit of FOSS out there with no interface stability >>>>>> in the external Sun documentation. This is not a problem for Sun >>>>>> project teams as they can always look at the interface tables in >>>>>> the ARC tables to determine stability level. >>>>>> >>>>>> Asking all java project teams to ship a man page in addition to >>>>>> javadocs doesn´t >>>>>> seem like the right solution and having some teams ship a man page >>>>>> and others not, does not provide consistency. >>>>>> >>>>>> There needs to more discussion to determine if it is critical >>>>>> that the ARC stability >>>>>> level be communicated to the Solaris end user for all the FOSS >>>>>> software >>>>>> that is being delivered. If so, a comprehensive solution needs to be >>>>>> formulated, whether it is a CLI, a man page, annotation embedded >>>>>> in the Javadocs >>>>>> (which will work for Sun products but you cant force that upstream). >>>>>> This is not being addressed in this case. Project teams can continue >>>>>> to ship documentation in their ¨natural¨form and if there is some >>>>>> stability suggested in that documentation that is fine. >>>>>> Up until now, most projects have not shipped man pages with jar >>>>>> files. This doesn´t seem to have been written down anywhere. With >>>>>> this case, we would like to make it explicit to not deliver man >>>>>> pages >>>>>> with jar files. This is setting precedent of ¨do not ship man pages >>>>>> with jar files.¨ This resulted in the below TCR. >>>>>> >>>>>> 5. Minority Opinion(s) >>>>>> >>>>>> Background >>>>>> >>>>>> It is not typical for programmers working with non C/C++/Assembler >>>>>> files, such as Java Jar files, to determine the >>>>>> Exported Interface stability level using the man command. Java >>>>>> programmers depend on Javadoc, Python programmers >>>>>> depend on pydoc and so forth to document interfaces and the >>>>>> stability would best be indicated there. Approval of OpenSolaris >>>>>> projects have been inconsistent in >>>>>> preferring man pages or native documentation. This opinion seeks >>>>>> to clarify the issue and define a policy for all such cases going >>>>>> forward. >>>>>> >>>>>> Best Practice >>>>>> >>>>>> Case A - Sun Developed Components >>>>>> >>>>>> 1) Sun project team developing a Jar file shall document the >>>>>> ARC interface classification in the native documentation. (i.e. >>>>>> Javadocs) >>>>>> >>>>>> Case B - Components imported from external OSS Communities >>>>>> >>>>>> 1) The OSS Community documents the interface classification in >>>>>> their native documentation >>>>>> >>>>>> a) OpenSolaris project team agrees with the classification >>>>>> and supports it >>>>>> - Javadoc or other native documentation required >>>>>> (unchanged) >>>>>> - No man page shall be allowed >>>>>> >>>>>> b) OpenSolaris project team disagrees with the classification >>>>>> - Javadoc or native documentation required, but >>>>>> project team must change the OSS documentation >>>>>> to match the project team's classification >>>>>> - No man page shall be allowed >>>>>> >>>>>> 2) OSS Community does not document interface classification in >>>>>> their native documentation >>>>>> a) OpenSolaris project team is strongly encouraged to >>>>>> update the native documentation to reflect the OpenSolaris project >>>>>> team >>>>>> classification. >>>>>> - Changed Javadoc or other native documentation required >>>>>> - No man page shall be allowed >>>>>> b) OpenSolaris project team cannot support deltas to the >>>>>> native documentation >>>>>> - Unchanged Javadoc or other native documentation required >>>>>> - A man page shall be provided >>>>>> >>>>>> >>>>>> >>>>>> 6. Advisory Information >>>>>> >>>>>> None. >>>>>> >>>>>> 7. Appendices >>>>>> >>>>>> 7.1. Appendix A: Technical Changes Required >>>>>> >>>>>> Do not ship man pages with Java jar files >>>>>> >>>>>> 7.2. Appendix B: Technical Changes Advised >>>>>> >>>>>> None. >>>>>> >>>>>> 7.3. Appendix C: Reference Material >>>>>> >>>>>> Unless stated otherwise, path names are relative to the case >>>>>> directory LSARC/2009/262 >>>>>> >>>>>> 1) Project Proposal file: >>>>>> >>>>>> >>>>>> LSARC/2009/262 Copyright 2009 Sun Microsystems >>>>>> _______________________________________________ >>>>>> opensolaris-arc mailing list >>>>>> opensolaris-arc@opensolaris.org >>>>> >>>>> -- >>>>> * Mark A. Carlson * >>>>> Sr. Architect >>>>> >>>>> *Systems Group* >>>>> Phone x69559 / 303-223-6139 >>>>> Email Mark.Carlson@Sun.COM >>>>> >>>> >>>> _______________________________________________ >>>> opensolaris-arc mailing list >>>> opensolaris-arc@opensolaris.org >>>> >>> >> > From margot.miller@sun.com Thu May 21 20:26:22 2009 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4M3QLcP024569; Thu, 21 May 2009 20:26:22 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail5.uk.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n4M3QGbU017347; Fri, 22 May 2009 04:26:18 +0100 (BST) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KK100K0507T0Z00@brm-avmta-1.central.sun.com>; Thu, 21 May 2009 21:26:17 -0600 (MDT) Received: from jurassic-x4600.sfbay.sun.com ([129.146.17.59]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KK100EMJ07S8I20@brm-avmta-1.central.sun.com>; Thu, 21 May 2009 21:26:16 -0600 (MDT) Received: from [10.7.250.88] (punchin-client-10-7-250-88.SFBay.Sun.COM [10.7.250.88]) by jurassic-x4600.sfbay.sun.com (8.14.3+Sun/8.14.3) with ESMTP id n4M3QFh3107592; Thu, 21 May 2009 20:26:15 -0700 (PDT) Date: Thu, 21 May 2009 20:26:15 -0700 From: Margot Miller Subject: Re: trove-2.0.4 LSARC/2009/262 In-reply-to: <4A15FF22.3040403@sun.com> To: Aniruddh Dikhit Cc: John.Fischer@sun.com, Tom Childers , LSARC-ext@sun.com, PSARC-ext@sun.com Message-id: <4A161B57.3090404@sun.com> MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1; format=flowed Content-transfer-encoding: 8BIT X-PMX-Version: 5.4.1.325704 References: <4A147D0E.2030701@sun.com> <4A14865B.9060307@sun.com> <4A1489E5.5050601@sun.com> <4A14ADF1.6030302@sun.com> <4A15FF22.3040403@sun.com> User-Agent: Thunderbird 2.0.0.17 (X11/20081023) Status: RO Content-Length: 10144 Thanks everyone for voting. With holiday coming up lets' keep this open for a few more days to give others a chance to vote if they want to- COB Tuesday May 26th. Margot Aniruddh Dikhit wrote: > Margot > > I am more aligned with the minority opinion on this issue. > > -Aniruddh > > John Fischer wrote: >> Margot, >> >> Please put me down with the Minority group. >> >> Thanks, >> >> John >> >> >> Tom Childers wrote: >>> Agreed. I vote to approve with the TCR, and would support a TCA to >>> "document the interface classification in the native documentation". >>> -tdc >>> >>> >>> On May 20, 2009, at 3:53 PM, Margot Miller wrote: >>> >>>> I wouldn´t mind having a TCA to have teams document the >>>> interface classification in their native documentation. The >>>> only thing I disagree with is forcing teams to provide a man >>>> page if they don´t have the interface classification in their >>>> native documentation. >>>> >>>> Thanks >>>> Margot >>>> >>>> >>>> Mark A. Carlson wrote: >>>>> Deny - I'd change it to a TCA to "document the interface >>>>> classification >>>>> in the native documentation" (follow the outline in the minority >>>>> opinion). >>>>> >>>>> -- mark >>>>> >>>>> Margot Miller wrote: >>>>>> All, >>>>>> >>>>>> I have included the minority opinion written by Mark Carlson. >>>>>> >>>>>> We did in fact have quorum yesterday; our external member >>>>>> was not listed as a full member. >>>>>> >>>>>> In any case, due to the lack of perceived quorum yesterday, >>>>>> please vote on this case. >>>>>> >>>>>> Vote to approve the case as written (with the TCR) >>>>>> Vote to deny >>>>>> >>>>>> If we find we now have a majority denying the case because >>>>>> they don´t agree with the TCR, then the TCR camp will >>>>>> become the minority. >>>>>> >>>>>> Thanks >>>>>> Margot >>>>>> >>>>>> >>>>>> microsystems Systems Architecture Committee >>>>>> >>>>>> _________________________________________________________________ >>>>>> >>>>>> Subject: trove-2.0.4 >>>>>> >>>>>> Submitted by: Vivek Titamare >>>>>> >>>>>> File: LSARC/2009/262/opinion.txt >>>>>> >>>>>> Date: May, 2009 >>>>>> >>>>>> Committee: Margot Hackett Miller, Lloyd Chambers >>>>>> Minority: Mark Carlson >>>>>> >>>>>> >>>>>> Product Approval Committee: >>>>>> Solaris PAC >>>>>> solaris-pac-opinion@sun.com >>>>>> >>>>>> 1. Summary >>>>>> >>>>>> This project is one of the Linux familiarity cases; this one >>>>>> provides >>>>>> a library to do fast regular and primitive collections for >>>>>> Java. >>>>>> >>>>>> 2. Decision & Precedence Information >>>>>> >>>>>> The project is approved as specified in reference [1]. >>>>>> >>>>>> The project may be delivered in a minor release of Solaris. >>>>>> >>>>>> 3. Interfaces >>>>>> >>>>>> Exported Interfaces: >>>>>> >>>>>> __________________________________________________ >>>>>> | Interfaces Exported | >>>>>> |____________ ______ |____________ __ __|____________| >>>>>> |Interface | Classification | Comments| >>>>>> |_______________ __|_________________|_____________| >>>>>> | trove.jar | Uncommitted | | >>>>>> |SUNWtrove | Uncommitted | | >>>>>> |___________________|_________________|____________| >>>>>> >>>>>> >>>>>> Imported Interfaces: >>>>>> >>>>>> ______________________________________________________________ >>>>>> | Interfaces Exported | | >>>>>> |___________________|______________ __|________________________| >>>>>> |Interface | Classification | Comments | >>>>>> |_______________ __|_________________|________________________| >>>>>> | >>>>>> | SUNWj5dev | Committed | Java Development kit | >>>>>> | SUNWj5rt | Committed | Java Runtime library | >>>>>> | SUNWj6dev | Committed | Java Development kit | >>>>>> | SUNWj6rt | Committed | Java Runtime library | >>>>>> |___________________|_________________|________________________| >>>>>> >>>>>> >>>>>> >>>>>> >>>>>> 4. Opinion >>>>>> >>>>>> During review, the only real issue raised was whether this team >>>>>> should provide a man page in addition to the javadocs. The man >>>>>> page would basically give a brief description of the jar file, >>>>>> pointer to the javadocs, and state the interface stability of the >>>>>> jar file. >>>>>> Discussion ensued whether it makes sense to ship a man page >>>>>> with a jar file. Solaris developers expect man pages, but do >>>>>> Java developers? Is it worth the extra work to provide a man page >>>>>> and would Java developers even look for a man page. >>>>>> >>>>>> It was noted that this is not standard practice as most Java >>>>>> developers look >>>>>> for java documentation via javadocs, not via man. However, others >>>>>> stated that >>>>>> having a minimal man page for a java jar file would allow the >>>>>> interface >>>>>> classification to be visible to the end user and a few other ARC >>>>>> cases have >>>>>> already shipped man pages for jar files. >>>>>> >>>>>> There was discussion over the granularity of the jar file and does >>>>>> it make sense to have an interface stability for the overall jar. >>>>>> Currently, >>>>>> java has Public, Package, and Protected. There was debate as to >>>>>> whether that conveys enough of the stability of the jar and its >>>>>> methods to the >>>>>> developer. >>>>>> >>>>>> With all the FOSS that is being delivered into Solaris, projects are >>>>>> delivering in their native, natural form. This includes man >>>>>> pages, texinfo, >>>>>> html, and javadoc. So the problem isn't just with javadocs and >>>>>> jar files. >>>>>> There is quite a bit of FOSS out there with no interface stability >>>>>> in the external Sun documentation. This is not a problem for Sun >>>>>> project teams as they can always look at the interface tables in >>>>>> the ARC tables to determine stability level. >>>>>> >>>>>> Asking all java project teams to ship a man page in addition to >>>>>> javadocs doesn´t >>>>>> seem like the right solution and having some teams ship a man page >>>>>> and others not, does not provide consistency. >>>>>> >>>>>> There needs to more discussion to determine if it is critical >>>>>> that the ARC stability >>>>>> level be communicated to the Solaris end user for all the FOSS >>>>>> software >>>>>> that is being delivered. If so, a comprehensive solution needs to be >>>>>> formulated, whether it is a CLI, a man page, annotation embedded >>>>>> in the Javadocs >>>>>> (which will work for Sun products but you cant force that upstream). >>>>>> This is not being addressed in this case. Project teams can continue >>>>>> to ship documentation in their ¨natural¨form and if there is some >>>>>> stability suggested in that documentation that is fine. >>>>>> Up until now, most projects have not shipped man pages with jar >>>>>> files. This doesn´t seem to have been written down anywhere. With >>>>>> this case, we would like to make it explicit to not deliver man >>>>>> pages >>>>>> with jar files. This is setting precedent of ¨do not ship man pages >>>>>> with jar files.¨ This resulted in the below TCR. >>>>>> >>>>>> 5. Minority Opinion(s) >>>>>> >>>>>> Background >>>>>> >>>>>> It is not typical for programmers working with non C/C++/Assembler >>>>>> files, such as Java Jar files, to determine the >>>>>> Exported Interface stability level using the man command. Java >>>>>> programmers depend on Javadoc, Python programmers >>>>>> depend on pydoc and so forth to document interfaces and the >>>>>> stability would best be indicated there. Approval of OpenSolaris >>>>>> projects have been inconsistent in >>>>>> preferring man pages or native documentation. This opinion seeks >>>>>> to clarify the issue and define a policy for all such cases going >>>>>> forward. >>>>>> >>>>>> Best Practice >>>>>> >>>>>> Case A - Sun Developed Components >>>>>> >>>>>> 1) Sun project team developing a Jar file shall document the >>>>>> ARC interface classification in the native documentation. (i.e. >>>>>> Javadocs) >>>>>> >>>>>> Case B - Components imported from external OSS Communities >>>>>> >>>>>> 1) The OSS Community documents the interface classification in >>>>>> their native documentation >>>>>> >>>>>> a) OpenSolaris project team agrees with the classification >>>>>> and supports it >>>>>> - Javadoc or other native documentation required >>>>>> (unchanged) >>>>>> - No man page shall be allowed >>>>>> >>>>>> b) OpenSolaris project team disagrees with the classification >>>>>> - Javadoc or native documentation required, but >>>>>> project team must change the OSS documentation >>>>>> to match the project team's classification >>>>>> - No man page shall be allowed >>>>>> >>>>>> 2) OSS Community does not document interface classification in >>>>>> their native documentation >>>>>> a) OpenSolaris project team is strongly encouraged to >>>>>> update the native documentation to reflect the OpenSolaris project >>>>>> team >>>>>> classification. >>>>>> - Changed Javadoc or other native documentation required >>>>>> - No man page shall be allowed >>>>>> b) OpenSolaris project team cannot support deltas to the >>>>>> native documentation >>>>>> - Unchanged Javadoc or other native documentation required >>>>>> - A man page shall be provided >>>>>> >>>>>> >>>>>> >>>>>> 6. Advisory Information >>>>>> >>>>>> None. >>>>>> >>>>>> 7. Appendices >>>>>> >>>>>> 7.1. Appendix A: Technical Changes Required >>>>>> >>>>>> Do not ship man pages with Java jar files >>>>>> >>>>>> 7.2. Appendix B: Technical Changes Advised >>>>>> >>>>>> None. >>>>>> >>>>>> 7.3. Appendix C: Reference Material >>>>>> >>>>>> Unless stated otherwise, path names are relative to the case >>>>>> directory LSARC/2009/262 >>>>>> >>>>>> 1) Project Proposal file: >>>>>> >>>>>> >>>>>> LSARC/2009/262 Copyright 2009 Sun Microsystems >>>>>> _______________________________________________ >>>>>> opensolaris-arc mailing list >>>>>> opensolaris-arc@opensolaris.org >>>>> >>>>> -- >>>>> * Mark A. Carlson * >>>>> Sr. Architect >>>>> >>>>> *Systems Group* >>>>> Phone x69559 / 303-223-6139 >>>>> Email Mark.Carlson@Sun.COM >>>>> >>>> >>>> _______________________________________________ >>>> opensolaris-arc mailing list >>>> opensolaris-arc@opensolaris.org >>>> >>> >> > From Mark.Carlson@sun.com Wed May 27 07:42:16 2009 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4REgEqx000037; Wed, 27 May 2009 07:42:14 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail5.uk.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n4REg1ZP004985; Wed, 27 May 2009 15:42:13 +0100 (BST) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KKB0046H4UBWS00@nwk-avmta-1.sfbay.Sun.COM>; Wed, 27 May 2009 07:42:11 -0700 (PDT) Received: from brmea-mail-2.sun.com ([192.18.98.43]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KKB00FDY4U9ZX80@nwk-avmta-1.sfbay.Sun.COM>; Wed, 27 May 2009 07:42:09 -0700 (PDT) Received: from fe-amer-10.sun.com ([192.18.109.80]) by brmea-mail-2.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n4REg9SP003831; Wed, 27 May 2009 14:42:09 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KKB000004BUJH00@mail-amer.sun.com>; Wed, 27 May 2009 08:42:09 -0600 (MDT) Received: from Macintosh-335.local ([unknown] [129.150.32.29]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KKB008UD4TXNS50@mail-amer.sun.com>; Wed, 27 May 2009 08:41:59 -0600 (MDT) Date: Wed, 27 May 2009 08:41:55 -0600 From: "Mark A. Carlson" Subject: Re: trove-2.0.4 LSARC/2009/262 In-reply-to: <4A161B57.3090404@sun.com> Sender: Mark.Carlson@sun.com To: Margot Miller Cc: Aniruddh Dikhit , PSARC-ext@sun.com, LSARC-ext@sun.com Message-id: <4A1D5133.9070701@sun.com> MIME-version: 1.0 Content-type: multipart/alternative; boundary="Boundary_(ID_LFXzesbZwY8oJxErSfXINA)" X-PMX-Version: 5.4.1.325704 References: <4A147D0E.2030701@sun.com> <4A14865B.9060307@sun.com> <4A1489E5.5050601@sun.com> <4A14ADF1.6030302@sun.com> <4A15FF22.3040403@sun.com> <4A161B57.3090404@sun.com> User-Agent: Thunderbird 2.0.0.21 (Macintosh/20090302) Status: RO Content-Length: 27454 This is a multi-part message in MIME format. --Boundary_(ID_LFXzesbZwY8oJxErSfXINA) Content-type: text/plain; format=flowed; charset=ISO-8859-1 Content-transfer-encoding: 8BIT Looking at the mail thread, it appears the votes are: "Majority" Margot (didn't see an actual vote from you) Tom "Minority" Aniruddh John Mark Given this, I think we can consider the case approved and the opinion should switch the two opinions around. There should be the discussed TCA, but not the TCR. Can you please update the opinion and edit the IAM file? I will mark the other fast track cases closed approved. Thanks, -- mark Margot Miller wrote: > Thanks everyone for voting. > > With holiday coming up lets' keep this open for a few more days to > give others > a chance to vote if they want to- COB Tuesday May 26th. > > Margot > > > > Aniruddh Dikhit wrote: >> Margot >> >> I am more aligned with the minority opinion on this issue. >> >> -Aniruddh >> >> John Fischer wrote: >>> Margot, >>> >>> Please put me down with the Minority group. >>> >>> Thanks, >>> >>> John >>> >>> >>> Tom Childers wrote: >>>> Agreed. I vote to approve with the TCR, and would support a TCA to >>>> "document the interface classification in the native documentation". >>>> -tdc >>>> >>>> >>>> On May 20, 2009, at 3:53 PM, Margot Miller wrote: >>>> >>>>> I wouldn´t mind having a TCA to have teams document the >>>>> interface classification in their native documentation. The >>>>> only thing I disagree with is forcing teams to provide a man >>>>> page if they don´t have the interface classification in their >>>>> native documentation. >>>>> >>>>> Thanks >>>>> Margot >>>>> >>>>> >>>>> Mark A. Carlson wrote: >>>>>> Deny - I'd change it to a TCA to "document the interface >>>>>> classification >>>>>> in the native documentation" (follow the outline in the minority >>>>>> opinion). >>>>>> >>>>>> -- mark >>>>>> >>>>>> Margot Miller wrote: >>>>>>> All, >>>>>>> >>>>>>> I have included the minority opinion written by Mark Carlson. >>>>>>> >>>>>>> We did in fact have quorum yesterday; our external member >>>>>>> was not listed as a full member. >>>>>>> >>>>>>> In any case, due to the lack of perceived quorum yesterday, >>>>>>> please vote on this case. >>>>>>> >>>>>>> Vote to approve the case as written (with the TCR) >>>>>>> Vote to deny >>>>>>> >>>>>>> If we find we now have a majority denying the case because >>>>>>> they don´t agree with the TCR, then the TCR camp will >>>>>>> become the minority. >>>>>>> >>>>>>> Thanks >>>>>>> Margot >>>>>>> >>>>>>> >>>>>>> microsystems Systems Architecture Committee >>>>>>> >>>>>>> _________________________________________________________________ >>>>>>> >>>>>>> Subject: trove-2.0.4 >>>>>>> >>>>>>> Submitted by: Vivek Titamare >>>>>>> >>>>>>> File: LSARC/2009/262/opinion.txt >>>>>>> >>>>>>> Date: May, 2009 >>>>>>> >>>>>>> Committee: Margot Hackett Miller, Lloyd Chambers >>>>>>> Minority: Mark Carlson >>>>>>> >>>>>>> >>>>>>> Product Approval Committee: >>>>>>> Solaris PAC >>>>>>> solaris-pac-opinion@sun.com >>>>>>> >>>>>>> 1. Summary >>>>>>> >>>>>>> This project is one of the Linux familiarity cases; this one >>>>>>> provides >>>>>>> a library to do fast regular and primitive collections for >>>>>>> Java. >>>>>>> >>>>>>> 2. Decision & Precedence Information >>>>>>> >>>>>>> The project is approved as specified in reference [1]. >>>>>>> >>>>>>> The project may be delivered in a minor release of Solaris. >>>>>>> >>>>>>> 3. Interfaces >>>>>>> >>>>>>> Exported Interfaces: >>>>>>> >>>>>>> __________________________________________________ >>>>>>> | Interfaces Exported | >>>>>>> |____________ ______ |____________ __ __|____________| >>>>>>> |Interface | Classification | Comments| >>>>>>> |_______________ __|_________________|_____________| >>>>>>> | trove.jar | Uncommitted | | >>>>>>> |SUNWtrove | Uncommitted | | >>>>>>> |___________________|_________________|____________| >>>>>>> >>>>>>> >>>>>>> Imported Interfaces: >>>>>>> >>>>>>> ______________________________________________________________ >>>>>>> | Interfaces Exported | | >>>>>>> |___________________|______________ __|________________________| >>>>>>> |Interface | Classification | Comments | >>>>>>> |_______________ __|_________________|________________________| >>>>>>> | >>>>>>> | SUNWj5dev | Committed | Java Development kit | >>>>>>> | SUNWj5rt | Committed | Java Runtime library | >>>>>>> | SUNWj6dev | Committed | Java Development kit | >>>>>>> | SUNWj6rt | Committed | Java Runtime library | >>>>>>> |___________________|_________________|________________________| >>>>>>> >>>>>>> >>>>>>> >>>>>>> >>>>>>> 4. Opinion >>>>>>> >>>>>>> During review, the only real issue raised was whether this team >>>>>>> should provide a man page in addition to the javadocs. The man >>>>>>> page would basically give a brief description of the jar file, >>>>>>> pointer to the javadocs, and state the interface stability of >>>>>>> the jar file. >>>>>>> Discussion ensued whether it makes sense to ship a man page >>>>>>> with a jar file. Solaris developers expect man pages, but do >>>>>>> Java developers? Is it worth the extra work to provide a man page >>>>>>> and would Java developers even look for a man page. >>>>>>> >>>>>>> It was noted that this is not standard practice as most Java >>>>>>> developers look >>>>>>> for java documentation via javadocs, not via man. However, >>>>>>> others stated that >>>>>>> having a minimal man page for a java jar file would allow the >>>>>>> interface >>>>>>> classification to be visible to the end user and a few other ARC >>>>>>> cases have >>>>>>> already shipped man pages for jar files. >>>>>>> >>>>>>> There was discussion over the granularity of the jar file and does >>>>>>> it make sense to have an interface stability for the overall >>>>>>> jar. Currently, >>>>>>> java has Public, Package, and Protected. There was debate as to >>>>>>> whether that conveys enough of the stability of the jar and its >>>>>>> methods to the >>>>>>> developer. >>>>>>> >>>>>>> With all the FOSS that is being delivered into Solaris, projects >>>>>>> are >>>>>>> delivering in their native, natural form. This includes man >>>>>>> pages, texinfo, >>>>>>> html, and javadoc. So the problem isn't just with javadocs and >>>>>>> jar files. >>>>>>> There is quite a bit of FOSS out there with no interface stability >>>>>>> in the external Sun documentation. This is not a problem for Sun >>>>>>> project teams as they can always look at the interface tables in >>>>>>> the ARC tables to determine stability level. >>>>>>> >>>>>>> Asking all java project teams to ship a man page in addition to >>>>>>> javadocs doesn´t >>>>>>> seem like the right solution and having some teams ship a man page >>>>>>> and others not, does not provide consistency. >>>>>>> >>>>>>> There needs to more discussion to determine if it is critical >>>>>>> that the ARC stability >>>>>>> level be communicated to the Solaris end user for all the FOSS >>>>>>> software >>>>>>> that is being delivered. If so, a comprehensive solution needs >>>>>>> to be >>>>>>> formulated, whether it is a CLI, a man page, annotation embedded >>>>>>> in the Javadocs >>>>>>> (which will work for Sun products but you cant force that >>>>>>> upstream). >>>>>>> This is not being addressed in this case. Project teams can >>>>>>> continue >>>>>>> to ship documentation in their ¨natural¨form and if there is some >>>>>>> stability suggested in that documentation that is fine. >>>>>>> Up until now, most projects have not shipped man pages with jar >>>>>>> files. This doesn´t seem to have been written down anywhere. With >>>>>>> this case, we would like to make it explicit to not deliver man >>>>>>> pages >>>>>>> with jar files. This is setting precedent of ¨do not ship man pages >>>>>>> with jar files.¨ This resulted in the below TCR. >>>>>>> >>>>>>> 5. Minority Opinion(s) >>>>>>> >>>>>>> Background >>>>>>> >>>>>>> It is not typical for programmers working with non C/C++/Assembler >>>>>>> files, such as Java Jar files, to determine the >>>>>>> Exported Interface stability level using the man command. Java >>>>>>> programmers depend on Javadoc, Python programmers >>>>>>> depend on pydoc and so forth to document interfaces and the >>>>>>> stability would best be indicated there. Approval of OpenSolaris >>>>>>> projects have been inconsistent in >>>>>>> preferring man pages or native documentation. This opinion seeks >>>>>>> to clarify the issue and define a policy for all such cases going >>>>>>> forward. >>>>>>> >>>>>>> Best Practice >>>>>>> >>>>>>> Case A - Sun Developed Components >>>>>>> >>>>>>> 1) Sun project team developing a Jar file shall document the >>>>>>> ARC interface classification in the native documentation. (i.e. >>>>>>> Javadocs) >>>>>>> >>>>>>> Case B - Components imported from external OSS Communities >>>>>>> >>>>>>> 1) The OSS Community documents the interface classification in >>>>>>> their native documentation >>>>>>> >>>>>>> a) OpenSolaris project team agrees with the classification >>>>>>> and supports it >>>>>>> - Javadoc or other native documentation required >>>>>>> (unchanged) >>>>>>> - No man page shall be allowed >>>>>>> >>>>>>> b) OpenSolaris project team disagrees with the classification >>>>>>> - Javadoc or native documentation required, but >>>>>>> project team must change the OSS documentation >>>>>>> to match the project team's classification >>>>>>> - No man page shall be allowed >>>>>>> >>>>>>> 2) OSS Community does not document interface classification in >>>>>>> their native documentation >>>>>>> a) OpenSolaris project team is strongly encouraged to >>>>>>> update the native documentation to reflect the OpenSolaris project >>>>>>> team >>>>>>> classification. >>>>>>> - Changed Javadoc or other native documentation required >>>>>>> - No man page shall be allowed >>>>>>> b) OpenSolaris project team cannot support deltas to the >>>>>>> native documentation >>>>>>> - Unchanged Javadoc or other native documentation required >>>>>>> - A man page shall be provided >>>>>>> >>>>>>> >>>>>>> >>>>>>> 6. Advisory Information >>>>>>> >>>>>>> None. >>>>>>> >>>>>>> 7. Appendices >>>>>>> >>>>>>> 7.1. Appendix A: Technical Changes Required >>>>>>> >>>>>>> Do not ship man pages with Java jar files >>>>>>> >>>>>>> 7.2. Appendix B: Technical Changes Advised >>>>>>> >>>>>>> None. >>>>>>> >>>>>>> 7.3. Appendix C: Reference Material >>>>>>> >>>>>>> Unless stated otherwise, path names are relative to the case >>>>>>> directory LSARC/2009/262 >>>>>>> >>>>>>> 1) Project Proposal file: >>>>>>> >>>>>>> >>>>>>> LSARC/2009/262 Copyright 2009 Sun Microsystems >>>>>>> _______________________________________________ >>>>>>> opensolaris-arc mailing list >>>>>>> opensolaris-arc@opensolaris.org >>>>>> >>>>>> -- >>>>>> * Mark A. Carlson * >>>>>> Sr. Architect >>>>>> >>>>>> *Systems Group* >>>>>> Phone x69559 / 303-223-6139 >>>>>> Email Mark.Carlson@Sun.COM >>>>>> >>>>> >>>>> _______________________________________________ >>>>> opensolaris-arc mailing list >>>>> opensolaris-arc@opensolaris.org >>>>> >>>> >>> >> > > _______________________________________________ > opensolaris-arc mailing list > opensolaris-arc@opensolaris.org -- * Mark A. Carlson * Sr. Architect *Systems Group* Phone x69559 / 303-223-6139 Email Mark.Carlson@Sun.COM --Boundary_(ID_LFXzesbZwY8oJxErSfXINA) Content-type: text/html; CHARSET=US-ASCII Content-transfer-encoding: 7BIT Looking at the mail thread, it appears the votes are:

"Majority"
Margot (didn't see an actual vote from you)
Tom

"Minority"
Aniruddh
John
Mark

Given this, I think we can consider the case approved and the opinion
should switch the two opinions around. There should be the discussed
TCA, but not the TCR.

Can you please update the opinion and edit the IAM file?

I will mark the other fast track cases closed approved.

Thanks,

-- mark

Margot Miller wrote:
Thanks everyone for voting.

With holiday coming up lets' keep this open for a few more days to give others
a chance to vote if they want to- COB Tuesday May 26th.

Margot



Aniruddh Dikhit wrote:
Margot

I am more aligned with the minority opinion on this issue.

-Aniruddh

John Fischer wrote:
Margot,

Please put me down with the Minority group.

Thanks,

John


Tom Childers wrote:
Agreed. I vote to approve with the TCR, and would support a TCA to "document the interface classification in the native documentation".
-tdc


On May 20, 2009, at 3:53 PM, Margot Miller wrote:

I wouldn´t mind having a TCA to have teams document the
interface classification in their native documentation. The
only thing I disagree with is forcing teams to provide a man
page if they don´t have the interface classification in their
native documentation.

Thanks
Margot


Mark A. Carlson wrote:
Deny - I'd change it to a TCA to "document the interface classification
in the native documentation" (follow the outline in the minority opinion).

-- mark

Margot Miller wrote:
All,

I have included the minority opinion written by Mark Carlson.

We did in fact have quorum yesterday; our external member
was not listed as a full member.

In any case, due to the lack of perceived quorum yesterday,
please vote on this case.

Vote to approve the case as written (with the TCR)
Vote to deny

If we find we now have a majority denying the case because
they don´t agree with the TCR, then the TCR camp will
become the minority.

Thanks
Margot


microsystems Systems Architecture Committee

_________________________________________________________________

Subject: trove-2.0.4

Submitted by: Vivek Titamare

File: LSARC/2009/262/opinion.txt

Date: May, 2009

Committee: Margot Hackett Miller, Lloyd Chambers
Minority: Mark Carlson


Product Approval Committee:
Solaris PAC
solaris-pac-opinion@sun.com

1. Summary

This project is one of the Linux familiarity cases; this one provides
a library to do fast regular and primitive collections for
Java.

2. Decision & Precedence Information

The project is approved as specified in reference [1].

The project may be delivered in a minor release of Solaris.

3. Interfaces

Exported Interfaces:

__________________________________________________
| Interfaces Exported |
|____________ ______ |____________ __ __|____________|
|Interface | Classification | Comments|
|_______________ __|_________________|_____________|
| trove.jar | Uncommitted | |
|SUNWtrove | Uncommitted | |
|___________________|_________________|____________|


Imported Interfaces:

______________________________________________________________
| Interfaces Exported | |
|___________________|______________ __|________________________|
|Interface | Classification | Comments |
|_______________ __|_________________|________________________|
|
| SUNWj5dev | Committed | Java Development kit |
| SUNWj5rt | Committed | Java Runtime library |
| SUNWj6dev | Committed | Java Development kit |
| SUNWj6rt | Committed | Java Runtime library |
|___________________|_________________|________________________|




4. Opinion

During review, the only real issue raised was whether this team
should provide a man page in addition to the javadocs. The man
page would basically give a brief description of the jar file,
pointer to the javadocs, and state the interface stability of the jar file.
Discussion ensued whether it makes sense to ship a man page
with a jar file. Solaris developers expect man pages, but do
Java developers? Is it worth the extra work to provide a man page
and would Java developers even look for a man page.

It was noted that this is not standard practice as most Java developers look
for java documentation via javadocs, not via man. However, others stated that
having a minimal man page for a java jar file would allow the interface
classification to be visible to the end user and a few other ARC cases have
already shipped man pages for jar files.

There was discussion over the granularity of the jar file and does
it make sense to have an interface stability for the overall jar. Currently,
java has Public, Package, and Protected. There was debate as to
whether that conveys enough of the stability of the jar and its methods to the
developer.

With all the FOSS that is being delivered into Solaris, projects are
delivering in their native, natural form. This includes man pages, texinfo,
html, and javadoc. So the problem isn't just with javadocs and jar files.
There is quite a bit of FOSS out there with no interface stability
in the external Sun documentation. This is not a problem for Sun
project teams as they can always look at the interface tables in
the ARC tables to determine stability level.

Asking all java project teams to ship a man page in addition to javadocs doesn´t
seem like the right solution and having some teams ship a man page
and others not, does not provide consistency.

There needs to more discussion to determine if it is critical that the ARC stability
level be communicated to the Solaris end user for all the FOSS software
that is being delivered. If so, a comprehensive solution needs to be
formulated, whether it is a CLI, a man page, annotation embedded in the Javadocs
(which will work for Sun products but you cant force that upstream).
This is not being addressed in this case. Project teams can continue
to ship documentation in their ¨natural¨form and if there is some
stability suggested in that documentation that is fine.
Up until now, most projects have not shipped man pages with jar
files. This doesn´t seem to have been written down anywhere. With
this case, we would like to make it explicit to not deliver man pages
with jar files. This is setting precedent of ¨do not ship man pages
with jar files.¨ This resulted in the below TCR.

5. Minority Opinion(s)

Background

It is not typical for programmers working with non C/C++/Assembler
files, such as Java Jar files, to determine the
Exported Interface stability level using the man command. Java
programmers depend on Javadoc, Python programmers
depend on pydoc and so forth to document interfaces and the
stability would best be indicated there. Approval of OpenSolaris projects have been inconsistent in
preferring man pages or native documentation. This opinion seeks
to clarify the issue and define a policy for all such cases going
forward.

Best Practice

Case A - Sun Developed Components

1) Sun project team developing a Jar file shall document the
ARC interface classification in the native documentation. (i.e.
Javadocs)

Case B - Components imported from external OSS Communities

1) The OSS Community documents the interface classification in
their native documentation

a) OpenSolaris project team agrees with the classification
and supports it
- Javadoc or other native documentation required
(unchanged)
- No man page shall be allowed

b) OpenSolaris project team disagrees with the classification
- Javadoc or native documentation required, but
project team must change the OSS documentation
to match the project team's classification
- No man page shall be allowed

2) OSS Community does not document interface classification in
their native documentation
a) OpenSolaris project team is strongly encouraged to
update the native documentation to reflect the OpenSolaris project
team
classification.
- Changed Javadoc or other native documentation required
- No man page shall be allowed
b) OpenSolaris project team cannot support deltas to the
native documentation
- Unchanged Javadoc or other native documentation required
- A man page shall be provided



6. Advisory Information

None.

7. Appendices

7.1. Appendix A: Technical Changes Required

Do not ship man pages with Java jar files

7.2. Appendix B: Technical Changes Advised

None.

7.3. Appendix C: Reference Material

Unless stated otherwise, path names are relative to the case
directory LSARC/2009/262

1) Project Proposal file:


LSARC/2009/262 Copyright 2009 Sun Microsystems
_______________________________________________
opensolaris-arc mailing list
opensolaris-arc@opensolaris.org

-- 
<http://www.sun.com> * Mark A. Carlson *
Sr. Architect

*Systems Group*
Phone x69559 / 303-223-6139
Email Mark.Carlson@Sun.COM


_______________________________________________
opensolaris-arc mailing list
opensolaris-arc@opensolaris.org





_______________________________________________
opensolaris-arc mailing list
opensolaris-arc@opensolaris.org

--
Mark A. Carlson
Sr. Architect

Systems Group
Phone x69559 / 303-223-6139
Email Mark.Carlson@Sun.COM

--Boundary_(ID_LFXzesbZwY8oJxErSfXINA)-- From Mark.Carlson@sun.com Wed May 27 07:42:16 2009 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id n4REgEqx000037; Wed, 27 May 2009 07:42:14 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail5.uk.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id n4REg1ZP004985; Wed, 27 May 2009 15:42:13 +0100 (BST) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KKB0046H4UBWS00@nwk-avmta-1.sfbay.Sun.COM>; Wed, 27 May 2009 07:42:11 -0700 (PDT) Received: from brmea-mail-2.sun.com ([192.18.98.43]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KKB00FDY4U9ZX80@nwk-avmta-1.sfbay.Sun.COM>; Wed, 27 May 2009 07:42:09 -0700 (PDT) Received: from fe-amer-10.sun.com ([192.18.109.80]) by brmea-mail-2.sun.com (8.13.6+Sun/8.12.9) with ESMTP id n4REg9SP003831; Wed, 27 May 2009 14:42:09 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) id <0KKB000004BUJH00@mail-amer.sun.com>; Wed, 27 May 2009 08:42:09 -0600 (MDT) Received: from Macintosh-335.local ([unknown] [129.150.32.29]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.02 64bit (built Apr 16 2009)) with ESMTPSA id <0KKB008UD4TXNS50@mail-amer.sun.com>; Wed, 27 May 2009 08:41:59 -0600 (MDT) Date: Wed, 27 May 2009 08:41:55 -0600 From: "Mark A. Carlson" Subject: Re: trove-2.0.4 LSARC/2009/262 In-reply-to: <4A161B57.3090404@sun.com> Sender: Mark.Carlson@sun.com To: Margot Miller Cc: Aniruddh Dikhit , PSARC-ext@sun.com, LSARC-ext@sun.com Message-id: <4A1D5133.9070701@sun.com> MIME-version: 1.0 Content-type: multipart/alternative; boundary="Boundary_(ID_LFXzesbZwY8oJxErSfXINA)" X-PMX-Version: 5.4.1.325704 References: <4A147D0E.2030701@sun.com> <4A14865B.9060307@sun.com> <4A1489E5.5050601@sun.com> <4A14ADF1.6030302@sun.com> <4A15FF22.3040403@sun.com> <4A161B57.3090404@sun.com> User-Agent: Thunderbird 2.0.0.21 (Macintosh/20090302) Status: RO Content-Length: 27454 This is a multi-part message in MIME format. --Boundary_(ID_LFXzesbZwY8oJxErSfXINA) Content-type: text/plain; format=flowed; charset=ISO-8859-1 Content-transfer-encoding: 8BIT Looking at the mail thread, it appears the votes are: "Majority" Margot (didn't see an actual vote from you) Tom "Minority" Aniruddh John Mark Given this, I think we can consider the case approved and the opinion should switch the two opinions around. There should be the discussed TCA, but not the TCR. Can you please update the opinion and edit the IAM file? I will mark the other fast track cases closed approved. Thanks, -- mark Margot Miller wrote: > Thanks everyone for voting. > > With holiday coming up lets' keep this open for a few more days to > give others > a chance to vote if they want to- COB Tuesday May 26th. > > Margot > > > > Aniruddh Dikhit wrote: >> Margot >> >> I am more aligned with the minority opinion on this issue. >> >> -Aniruddh >> >> John Fischer wrote: >>> Margot, >>> >>> Please put me down with the Minority group. >>> >>> Thanks, >>> >>> John >>> >>> >>> Tom Childers wrote: >>>> Agreed. I vote to approve with the TCR, and would support a TCA to >>>> "document the interface classification in the native documentation". >>>> -tdc >>>> >>>> >>>> On May 20, 2009, at 3:53 PM, Margot Miller wrote: >>>> >>>>> I wouldn´t mind having a TCA to have teams document the >>>>> interface classification in their native documentation. The >>>>> only thing I disagree with is forcing teams to provide a man >>>>> page if they don´t have the interface classification in their >>>>> native documentation. >>>>> >>>>> Thanks >>>>> Margot >>>>> >>>>> >>>>> Mark A. Carlson wrote: >>>>>> Deny - I'd change it to a TCA to "document the interface >>>>>> classification >>>>>> in the native documentation" (follow the outline in the minority >>>>>> opinion). >>>>>> >>>>>> -- mark >>>>>> >>>>>> Margot Miller wrote: >>>>>>> All, >>>>>>> >>>>>>> I have included the minority opinion written by Mark Carlson. >>>>>>> >>>>>>> We did in fact have quorum yesterday; our external member >>>>>>> was not listed as a full member. >>>>>>> >>>>>>> In any case, due to the lack of perceived quorum yesterday, >>>>>>> please vote on this case. >>>>>>> >>>>>>> Vote to approve the case as written (with the TCR) >>>>>>> Vote to deny >>>>>>> >>>>>>> If we find we now have a majority denying the case because >>>>>>> they don´t agree with the TCR, then the TCR camp will >>>>>>> become the minority. >>>>>>> >>>>>>> Thanks >>>>>>> Margot >>>>>>> >>>>>>> >>>>>>> microsystems Systems Architecture Committee >>>>>>> >>>>>>> _________________________________________________________________ >>>>>>> >>>>>>> Subject: trove-2.0.4 >>>>>>> >>>>>>> Submitted by: Vivek Titamare >>>>>>> >>>>>>> File: LSARC/2009/262/opinion.txt >>>>>>> >>>>>>> Date: May, 2009 >>>>>>> >>>>>>> Committee: Margot Hackett Miller, Lloyd Chambers >>>>>>> Minority: Mark Carlson >>>>>>> >>>>>>> >>>>>>> Product Approval Committee: >>>>>>> Solaris PAC >>>>>>> solaris-pac-opinion@sun.com >>>>>>> >>>>>>> 1. Summary >>>>>>> >>>>>>> This project is one of the Linux familiarity cases; this one >>>>>>> provides >>>>>>> a library to do fast regular and primitive collections for >>>>>>> Java. >>>>>>> >>>>>>> 2. Decision & Precedence Information >>>>>>> >>>>>>> The project is approved as specified in reference [1]. >>>>>>> >>>>>>> The project may be delivered in a minor release of Solaris. >>>>>>> >>>>>>> 3. Interfaces >>>>>>> >>>>>>> Exported Interfaces: >>>>>>> >>>>>>> __________________________________________________ >>>>>>> | Interfaces Exported | >>>>>>> |____________ ______ |____________ __ __|____________| >>>>>>> |Interface | Classification | Comments| >>>>>>> |_______________ __|_________________|_____________| >>>>>>> | trove.jar | Uncommitted | | >>>>>>> |SUNWtrove | Uncommitted | | >>>>>>> |___________________|_________________|____________| >>>>>>> >>>>>>> >>>>>>> Imported Interfaces: >>>>>>> >>>>>>> ______________________________________________________________ >>>>>>> | Interfaces Exported | | >>>>>>> |___________________|______________ __|________________________| >>>>>>> |Interface | Classification | Comments | >>>>>>> |_______________ __|_________________|________________________| >>>>>>> | >>>>>>> | SUNWj5dev | Committed | Java Development kit | >>>>>>> | SUNWj5rt | Committed | Java Runtime library | >>>>>>> | SUNWj6dev | Committed | Java Development kit | >>>>>>> | SUNWj6rt | Committed | Java Runtime library | >>>>>>> |___________________|_________________|________________________| >>>>>>> >>>>>>> >>>>>>> >>>>>>> >>>>>>> 4. Opinion >>>>>>> >>>>>>> During review, the only real issue raised was whether this team >>>>>>> should provide a man page in addition to the javadocs. The man >>>>>>> page would basically give a brief description of the jar file, >>>>>>> pointer to the javadocs, and state the interface stability of >>>>>>> the jar file. >>>>>>> Discussion ensued whether it makes sense to ship a man page >>>>>>> with a jar file. Solaris developers expect man pages, but do >>>>>>> Java developers? Is it worth the extra work to provide a man page >>>>>>> and would Java developers even look for a man page. >>>>>>> >>>>>>> It was noted that this is not standard practice as most Java >>>>>>> developers look >>>>>>> for java documentation via javadocs, not via man. However, >>>>>>> others stated that >>>>>>> having a minimal man page for a java jar file would allow the >>>>>>> interface >>>>>>> classification to be visible to the end user and a few other ARC >>>>>>> cases have >>>>>>> already shipped man pages for jar files. >>>>>>> >>>>>>> There was discussion over the granularity of the jar file and does >>>>>>> it make sense to have an interface stability for the overall >>>>>>> jar. Currently, >>>>>>> java has Public, Package, and Protected. There was debate as to >>>>>>> whether that conveys enough of the stability of the jar and its >>>>>>> methods to the >>>>>>> developer. >>>>>>> >>>>>>> With all the FOSS that is being delivered into Solaris, projects >>>>>>> are >>>>>>> delivering in their native, natural form. This includes man >>>>>>> pages, texinfo, >>>>>>> html, and javadoc. So the problem isn't just with javadocs and >>>>>>> jar files. >>>>>>> There is quite a bit of FOSS out there with no interface stability >>>>>>> in the external Sun documentation. This is not a problem for Sun >>>>>>> project teams as they can always look at the interface tables in >>>>>>> the ARC tables to determine stability level. >>>>>>> >>>>>>> Asking all java project teams to ship a man page in addition to >>>>>>> javadocs doesn´t >>>>>>> seem like the right solution and having some teams ship a man page >>>>>>> and others not, does not provide consistency. >>>>>>> >>>>>>> There needs to more discussion to determine if it is critical >>>>>>> that the ARC stability >>>>>>> level be communicated to the Solaris end user for all the FOSS >>>>>>> software >>>>>>> that is being delivered. If so, a comprehensive solution needs >>>>>>> to be >>>>>>> formulated, whether it is a CLI, a man page, annotation embedded >>>>>>> in the Javadocs >>>>>>> (which will work for Sun products but you cant force that >>>>>>> upstream). >>>>>>> This is not being addressed in this case. Project teams can >>>>>>> continue >>>>>>> to ship documentation in their ¨natural¨form and if there is some >>>>>>> stability suggested in that documentation that is fine. >>>>>>> Up until now, most projects have not shipped man pages with jar >>>>>>> files. This doesn´t seem to have been written down anywhere. With >>>>>>> this case, we would like to make it explicit to not deliver man >>>>>>> pages >>>>>>> with jar files. This is setting precedent of ¨do not ship man pages >>>>>>> with jar files.¨ This resulted in the below TCR. >>>>>>> >>>>>>> 5. Minority Opinion(s) >>>>>>> >>>>>>> Background >>>>>>> >>>>>>> It is not typical for programmers working with non C/C++/Assembler >>>>>>> files, such as Java Jar files, to determine the >>>>>>> Exported Interface stability level using the man command. Java >>>>>>> programmers depend on Javadoc, Python programmers >>>>>>> depend on pydoc and so forth to document interfaces and the >>>>>>> stability would best be indicated there. Approval of OpenSolaris >>>>>>> projects have been inconsistent in >>>>>>> preferring man pages or native documentation. This opinion seeks >>>>>>> to clarify the issue and define a policy for all such cases going >>>>>>> forward. >>>>>>> >>>>>>> Best Practice >>>>>>> >>>>>>> Case A - Sun Developed Components >>>>>>> >>>>>>> 1) Sun project team developing a Jar file shall document the >>>>>>> ARC interface classification in the native documentation. (i.e. >>>>>>> Javadocs) >>>>>>> >>>>>>> Case B - Components imported from external OSS Communities >>>>>>> >>>>>>> 1) The OSS Community documents the interface classification in >>>>>>> their native documentation >>>>>>> >>>>>>> a) OpenSolaris project team agrees with the classification >>>>>>> and supports it >>>>>>> - Javadoc or other native documentation required >>>>>>> (unchanged) >>>>>>> - No man page shall be allowed >>>>>>> >>>>>>> b) OpenSolaris project team disagrees with the classification >>>>>>> - Javadoc or native documentation required, but >>>>>>> project team must change the OSS documentation >>>>>>> to match the project team's classification >>>>>>> - No man page shall be allowed >>>>>>> >>>>>>> 2) OSS Community does not document interface classification in >>>>>>> their native documentation >>>>>>> a) OpenSolaris project team is strongly encouraged to >>>>>>> update the native documentation to reflect the OpenSolaris project >>>>>>> team >>>>>>> classification. >>>>>>> - Changed Javadoc or other native documentation required >>>>>>> - No man page shall be allowed >>>>>>> b) OpenSolaris project team cannot support deltas to the >>>>>>> native documentation >>>>>>> - Unchanged Javadoc or other native documentation required >>>>>>> - A man page shall be provided >>>>>>> >>>>>>> >>>>>>> >>>>>>> 6. Advisory Information >>>>>>> >>>>>>> None. >>>>>>> >>>>>>> 7. Appendices >>>>>>> >>>>>>> 7.1. Appendix A: Technical Changes Required >>>>>>> >>>>>>> Do not ship man pages with Java jar files >>>>>>> >>>>>>> 7.2. Appendix B: Technical Changes Advised >>>>>>> >>>>>>> None. >>>>>>> >>>>>>> 7.3. Appendix C: Reference Material >>>>>>> >>>>>>> Unless stated otherwise, path names are relative to the case >>>>>>> directory LSARC/2009/262 >>>>>>> >>>>>>> 1) Project Proposal file: >>>>>>> >>>>>>> >>>>>>> LSARC/2009/262 Copyright 2009 Sun Microsystems >>>>>>> _______________________________________________ >>>>>>> opensolaris-arc mailing list >>>>>>> opensolaris-arc@opensolaris.org >>>>>> >>>>>> -- >>>>>> * Mark A. Carlson * >>>>>> Sr. Architect >>>>>> >>>>>> *Systems Group* >>>>>> Phone x69559 / 303-223-6139 >>>>>> Email Mark.Carlson@Sun.COM >>>>>> >>>>> >>>>> _______________________________________________ >>>>> opensolaris-arc mailing list >>>>> opensolaris-arc@opensolaris.org >>>>> >>>> >>> >> > > _______________________________________________ > opensolaris-arc mailing list > opensolaris-arc@opensolaris.org -- * Mark A. Carlson * Sr. Architect *Systems Group* Phone x69559 / 303-223-6139 Email Mark.Carlson@Sun.COM --Boundary_(ID_LFXzesbZwY8oJxErSfXINA) Content-type: text/html; CHARSET=US-ASCII Content-transfer-encoding: 7BIT Looking at the mail thread, it appears the votes are:

"Majority"
Margot (didn't see an actual vote from you)
Tom

"Minority"
Aniruddh
John
Mark

Given this, I think we can consider the case approved and the opinion
should switch the two opinions around. There should be the discussed
TCA, but not the TCR.

Can you please update the opinion and edit the IAM file?

I will mark the other fast track cases closed approved.

Thanks,

-- mark

Margot Miller wrote:
Thanks everyone for voting.

With holiday coming up lets' keep this open for a few more days to give others
a chance to vote if they want to- COB Tuesday May 26th.

Margot



Aniruddh Dikhit wrote:
Margot

I am more aligned with the minority opinion on this issue.

-Aniruddh

John Fischer wrote:
Margot,

Please put me down with the Minority group.

Thanks,

John


Tom Childers wrote:
Agreed. I vote to approve with the TCR, and would support a TCA to "document the interface classification in the native documentation".
-tdc


On May 20, 2009, at 3:53 PM, Margot Miller wrote:

I wouldn´t mind having a TCA to have teams document the
interface classification in their native documentation. The
only thing I disagree with is forcing teams to provide a man
page if they don´t have the interface classification in their
native documentation.

Thanks
Margot


Mark A. Carlson wrote:
Deny - I'd change it to a TCA to "document the interface classification
in the native documentation" (follow the outline in the minority opinion).

-- mark

Margot Miller wrote:
All,

I have included the minority opinion written by Mark Carlson.

We did in fact have quorum yesterday; our external member
was not listed as a full member.

In any case, due to the lack of perceived quorum yesterday,
please vote on this case.

Vote to approve the case as written (with the TCR)
Vote to deny

If we find we now have a majority denying the case because
they don´t agree with the TCR, then the TCR camp will
become the minority.

Thanks
Margot


microsystems Systems Architecture Committee

_________________________________________________________________

Subject: trove-2.0.4

Submitted by: Vivek Titamare

File: LSARC/2009/262/opinion.txt

Date: May, 2009

Committee: Margot Hackett Miller, Lloyd Chambers
Minority: Mark Carlson


Product Approval Committee:
Solaris PAC
solaris-pac-opinion@sun.com

1. Summary

This project is one of the Linux familiarity cases; this one provides
a library to do fast regular and primitive collections for
Java.

2. Decision & Precedence Information

The project is approved as specified in reference [1].

The project may be delivered in a minor release of Solaris.

3. Interfaces

Exported Interfaces:

__________________________________________________
| Interfaces Exported |
|____________ ______ |____________ __ __|____________|
|Interface | Classification | Comments|
|_______________ __|_________________|_____________|
| trove.jar | Uncommitted | |
|SUNWtrove | Uncommitted | |
|___________________|_________________|____________|


Imported Interfaces:

______________________________________________________________
| Interfaces Exported | |
|___________________|______________ __|________________________|
|Interface | Classification | Comments |
|_______________ __|_________________|________________________|
|
| SUNWj5dev | Committed | Java Development kit |
| SUNWj5rt | Committed | Java Runtime library |
| SUNWj6dev | Committed | Java Development kit |
| SUNWj6rt | Committed | Java Runtime library |
|___________________|_________________|________________________|




4. Opinion

During review, the only real issue raised was whether this team
should provide a man page in addition to the javadocs. The man
page would basically give a brief description of the jar file,
pointer to the javadocs, and state the interface stability of the jar file.
Discussion ensued whether it makes sense to ship a man page
with a jar file. Solaris developers expect man pages, but do
Java developers? Is it worth the extra work to provide a man page
and would Java developers even look for a man page.

It was noted that this is not standard practice as most Java developers look
for java documentation via javadocs, not via man. However, others stated that
having a minimal man page for a java jar file would allow the interface
classification to be visible to the end user and a few other ARC cases have
already shipped man pages for jar files.

There was discussion over the granularity of the jar file and does
it make sense to have an interface stability for the overall jar. Currently,
java has Public, Package, and Protected. There was debate as to
whether that conveys enough of the stability of the jar and its methods to the
developer.

With all the FOSS that is being delivered into Solaris, projects are
delivering in their native, natural form. This includes man pages, texinfo,
html, and javadoc. So the problem isn't just with javadocs and jar files.
There is quite a bit of FOSS out there with no interface stability
in the external Sun documentation. This is not a problem for Sun
project teams as they can always look at the interface tables in
the ARC tables to determine stability level.

Asking all java project teams to ship a man page in addition to javadocs doesn´t
seem like the right solution and having some teams ship a man page
and others not, does not provide consistency.

There needs to more discussion to determine if it is critical that the ARC stability
level be communicated to the Solaris end user for all the FOSS software
that is being delivered. If so, a comprehensive solution needs to be
formulated, whether it is a CLI, a man page, annotation embedded in the Javadocs
(which will work for Sun products but you cant force that upstream).
This is not being addressed in this case. Project teams can continue
to ship documentation in their ¨natural¨form and if there is some
stability suggested in that documentation that is fine.
Up until now, most projects have not shipped man pages with jar
files. This doesn´t seem to have been written down anywhere. With
this case, we would like to make it explicit to not deliver man pages
with jar files. This is setting precedent of ¨do not ship man pages
with jar files.¨ This resulted in the below TCR.

5. Minority Opinion(s)

Background

It is not typical for programmers working with non C/C++/Assembler
files, such as Java Jar files, to determine the
Exported Interface stability level using the man command. Java
programmers depend on Javadoc, Python programmers
depend on pydoc and so forth to document interfaces and the
stability would best be indicated there. Approval of OpenSolaris projects have been inconsistent in
preferring man pages or native documentation. This opinion seeks
to clarify the issue and define a policy for all such cases going
forward.

Best Practice

Case A - Sun Developed Components

1) Sun project team developing a Jar file shall document the
ARC interface classification in the native documentation. (i.e.
Javadocs)

Case B - Components imported from external OSS Communities

1) The OSS Community documents the interface classification in
their native documentation

a) OpenSolaris project team agrees with the classification
and supports it
- Javadoc or other native documentation required
(unchanged)
- No man page shall be allowed

b) OpenSolaris project team disagrees with the classification
- Javadoc or native documentation required, but
project team must change the OSS documentation
to match the project team's classification
- No man page shall be allowed

2) OSS Community does not document interface classification in
their native documentation
a) OpenSolaris project team is strongly encouraged to
update the native documentation to reflect the OpenSolaris project
team
classification.
- Changed Javadoc or other native documentation required
- No man page shall be allowed
b) OpenSolaris project team cannot support deltas to the
native documentation
- Unchanged Javadoc or other native documentation required
- A man page shall be provided



6. Advisory Information

None.

7. Appendices

7.1. Appendix A: Technical Changes Required

Do not ship man pages with Java jar files

7.2. Appendix B: Technical Changes Advised

None.

7.3. Appendix C: Reference Material

Unless stated otherwise, path names are relative to the case
directory LSARC/2009/262

1) Project Proposal file:


LSARC/2009/262 Copyright 2009 Sun Microsystems
_______________________________________________
opensolaris-arc mailing list
opensolaris-arc@opensolaris.org

-- 
<http://www.sun.com> * Mark A. Carlson *
Sr. Architect

*Systems Group*
Phone x69559 / 303-223-6139
Email Mark.Carlson@Sun.COM


_______________________________________________
opensolaris-arc mailing list
opensolaris-arc@opensolaris.org





_______________________________________________
opensolaris-arc mailing list
opensolaris-arc@opensolaris.org

--
Mark A. Carlson
Sr. Architect

Systems Group
Phone x69559 / 303-223-6139
Email Mark.Carlson@Sun.COM

--Boundary_(ID_LFXzesbZwY8oJxErSfXINA)--