HOW TO USE THE ISAC ISSUE REPORT TEMPLATE (Version: $Revision: 1.10 $ $Date: 1995/08/17 20:29:00 $.) PURPOSE ======= The Issue Report Template is used to to bring VHDL issues to the attention of the ISAC, the Issues Screening and Analysis Committee, a subgroup of the VHDL Analysis and Standardization group (VASG), the group responsible for the standardization and maintenance of VHDL. FORMAT ====== The Issue Report Template is a text file comprising a number of fields. Some fields can contain only one value of an enumerated type, others can contain free-form text. The text fields are of unlimited length, but no line of the file should exceed eighty characters in length. Each field begins with a header, a string terminated by a colon except in the case of the last five fields. The value portion of colon-terminated fields are indented to form a column; please preserve the columnar structure when filling in these fields. The last five fields are full-width fields with the value portion of the field immediately following the header. Two blank lines should separate the field header from the previous field. Tab characters should not be used for formatting, since not all display and output devices can correctly handle tabs. REPORT FIELDS ============= The fields and appropriate contents are described below. The person or group responsible for providing the information is also identified. VHDL Issue Number: ------------------ This is a four-digit field whose contents is assigned by the ISAC. Classification: --------------- This field describes the issue author's classification of the report. It should be filled out by the issue's author and takes on one value of an enumerated type, as follows: Language Definition Problem: This value is used to report a problem with the defintional part of the LRM; for example, an inconsistency, ambiguity, or omission in the document. This field is appropriate if the LRM problem affects the definition of VHDL in some way. Examples, Notes, and Appendices: This value is used to report a problem in the LRM examples, notes, or appendices other than purely typographical issues. Terminology, Grammar, and Typographical Errors: This value is used to report a problem in the LRM relating to terminology, usage of the English language, or typography. Language Deficiencies and Modeling Problems: This value is used to request language enhancements. Language Version: ----------------- This field, entered by the issue author, identifies the language version to which the issue pertains. It has two possible values, VHDL-87 and VHDL-93. If the issue pertains to both versions of the language, use the latest: VHDL- 93. Summary: -------- This field is used by the issue author to capture a succinct and precise summary of the reported issue. Should more than one line be necessary, indent the second and subsequent lines to match starting column of the first line. Related Issues: --------------- The issue author should cross-reference any related ISAC Issues by listing their (four-digit) numbers in a comma-separated list. The ISAC may augment this field with additional relevant issue report numbers. Relevant LRM Sections: ---------------------- The section numbers of LRM sections relevant to this issue should be entered here by the issue author. The ISAC may augment this field as necessary. Key Words and Phrases: ---------------------- The issue author enters relevant LRM and VHDL terms in a comma-separated list in this field. If the list exceeds one line in length, indent subsequent lines. Current Status: --------------- The issue's status is tracked in this field. It takes on one of the following values: Submitted: The issue has been submitted to the ISAC, but no further action has been taken. This is the only value the issue author assigns to this field. Analyzed: The ISAC assigns this value to this field when the issue has been analyzed by the ISAC. The ISAC also fills in the "VASG-ISAC Analysis & Rationale" field at this time. It may also fill out the "VASG-ISAC Recommendation for IEEE Std 1076-1993" and "VASG-ISAC Recommendation for Future Revisions" fields at this time. ISAC-Approved: The ISAC assigns this value to this field when it has reached consensus on the the issue's proposed disposition. The fields "VASG- ISAC Recommendation for IEEE Std 1076-1993" and "VASG-ISAC Recommendation for Future Revisions" must be filled out at this time. VASG-Approved: This value is assigned to this field when the ISAC has presented the issue and its proposed disposition to the VASG and the VASG has achieved consensus on the disposition. At this point, the issue disposition is part of the official interpretation of 1076-1993. Edits to the fields "VASG-ISAC Analysis & Rationale," "VASG-ISAC Recommendation for IEEE Std 1076-1993," and "VASG-ISAC Recommendation for Future Revisions" may occur as a result of the presentation to the VASG. Superseded: This value is asssigned to this field by the ISAC if the reported issue is subsumed by another issue report. Among the reasons for this action may be: duplicate reports received concerning the same issue, consolidation of related issues into a single report, and rewriting existing issue reports to separate closed and outstanding issues. 1076-1993 Disposition: ---------------------- This field is filled in by the ISAC when preparing a final analysis of the issues reported on an previous version of VHDL. It takes on one of the following values: N/A: The issue report is a new issue report against the current version (1076-1993) of VHDL and does not (yet) apply to a previous version, so this field is not applicable. Unknown: The issue has not been sufficiently analyzed to determine its status. Further analysis will occur. Closed (All Issues Completely Addressed): The issue(s) reported have been completely addressed in the current version of VHDL. Bugs Fixed, Enhancements Outstanding (No ISAC Issues): All issues that are the responsibility of the ISAC have been completely addressed in the current version of VHDL; however, there remain other issues to be forwarded to subsequent restandardization committees. Superseded (ISAC Issues Outstanding): Some or all of the issues reported in the current issue report have not been addressed in the current version of VHDL. These issues have been captured in a new issue report. Disposition Rationale: ---------------------- This field is filled in simultaneously with the previous field. For new issue reports (against the current version of the language), this field is not applicable and it contains the value "N/A". For issues against a previous version, the ISAC documents here the rationale reached during the final analysis of an issue. Superseded By: -------------- If this issue report is superseded by another, this field identifies the other report by number. Otherwise, this field is not applicable and contains the value "N/A". Date Submitted: --------------- When submitting an issue, fill in this field in "yyyy/mm/dd" format. That is, use the four-digit year, the two-digit month number, and the two-digit day of the month. Use slashes to separate the fields. Example: "1993/10/14" Author of Submission: --------------------- The issue's author fills in his or her name here. Author's Affiliation: --------------------- The issue author's company name is provided here. Author's Post Address: ---------------------- The issue author fills in his or her preferred postal address here. Author's Phone Number: ---------------------- The issue author fills in his or her daytime voice phone number here. Non-US phone numbers should be prefixed by country and city codes. Author's Fax Number: -------------------- The issue author fills in his or her facsimile number here, if available. Non-US phone numbers should be prefixed by country and city codes. Author's Net Address: --------------------- The issue author's electronic mail address is provided here, if available. Internet addresses, followed by uunet addresses, are preferred. Date Analyzed: -------------- The ISAC fills in this field with the date of analysis, in the format of the Data Submitted field. Author of Analysis: ------------------- The ISAC fills in this field with the name of the person analyzing the issue on behalf of the ISAC. Revision Number: ---------------- This field contains the revision number of the issue report. The ISAC updates this field each time the issue report is updated or modified. The field value is in the form of an RCS (Revision Control System) Revision keyword string. New issue reports should be submitted with a Revision Number field value consisting of "$" followed by "Revision" followed by "$". (Note: That string can't be represented simply here because these instructions are also kept in RCS.) Date Last Revised: ------------------ This field contains the date of last revision of the issue report. The ISAC updates this field each time the issue report is updated or modified. The field value is in the form of an RCS Date keyword string. New issue reports should be submitted with a Date Last Revised field value consisting of "$" followed by "Date" followed by "$". (Note: That string can't be represented simply here because these instructions are also kept in RCS.) Description of Problem: ----------------------- The issue author fills in this field, explaining the issue in detail. Quotations from the LRM, where relevant, are encouraged. Proposed Resolution: -------------------- The issue author fills in this field with his or her desired resolution of the issue. VASG-ISAC Analysis & Rationale: ------------------------------- The ISAC fills in this field with the results of its analysis of the reported issue. VASG-ISAC Recommendation for IEEE Std 1076-1993: ------------------------------------------------ The ISAC fills in this field with its proposed short-term resolution of the reported issue. VASG-ISAC Recommendation for Future Revisions --------------------------------------------- The ISAC fills in this field with its proposed long-term resolution of the reported issue. TEXT FIELD STYLE ================= In the full-width text fields, the recommended formatting style is as follows: - Use a blank line to separate paragraphs; don't indent the first lines. - Align top-level paragraphs at the left margin. - Indent whole paragraphs (for example, for LRM quotes). The following items are requests from Daniel. As of 95/05/13, the ISAC has accepted or rejected these. - For numbers of issue reports, use all four digits. - For report numbers in header fields, use just the number (without "IR"). - For abbreviated references in text, please use the form "IR 0123" (not "IR0123"). (Certainly, you can write out "issue report 0123" if you want.) GENERATING AN ISSUE REPORT ========================== 1. Obtain a copy of the issue reporting template. It is stored on the machine vhdl.org (198.31.14.3) in the directory /vi/isac/IRs1k as the file "IRTemplate.txt" (as of August 17, 1995). 2. Fill out the issue template, referring to the above field descriptions. Be sure to fill in the fields Classification, Language Version, Summary, Related Issues, Relevant LRM Sections, Key Words and Phrases, Current Status (always with the value "Submitted"), Date Submitted, Author of Submission, Author's Affiliation, Author's Post Address, Author's Phone Number, Author's Fax Number, Author's Net Address, Revision Number (with a value of 1), Date Last Revised, Description of Problem, and Proposed Resolution. Do not fill in any other fields. 3. Send the completed issue report to Electronic mail submissions are preferred. If email is not possible, please send a disk via post. The disk format should be either PC, Mac, or Sun, and it should contain unformatted ASCII text.