Publish Draft 2

[GoogleCodeExporter]

This issue is for the discussion and resolution of publishing our next spec 
draft (draft 2) for wider community distribution and comment.

Changes currently ratified in our working draft:
-----------------------------------------------
Issue 9: Library: High-Performance Wall-Clock Timers (upc_tick_t)
Issue 51: revise text to eliminate an ambiguity in barrier matching semantics
Issue 32: THREADS/MYTHREAD have "integral value" rather than "type int"
Issue 83: Strengthen the "default" pragma from
"implementation-defined" to "relaxed"
Issue 33: clarification: MYTHREAD and THREADS are expressions (cannot
assign to or take address of them)
Issue 49: clarification: unlock of freed lock
Issue 4: Progress guarantee of upc_notify and upc_wait
Issue 55: Miscelaneous specification document typographical errors
Issue 82: Remove the deprecated upc_local_alloc function

We currently have no issues in the PendingApproval state. Some issues are 
likely to move into that state after the 9/21 meeting, but due to the one month 
comment period they cannot be ratified into the working draft before 10/21, 
which would put a draft published at that time squarely in the pre-SC time 
crunch.

I believe the current changes are sufficient to justify soliciting community 
feedback, and that we should commence the technical process to publish Draft 2 
immediately. 

We should also plan to publish Draft 3 near the end of October, which will 
include any changes that are officially proposed in the next week or so, and 
may likely be the last draft published before SC.

Original issue reported on code.google.com by danbonachea on 14 Sep 2012 at 9:56

[GoogleCodeExporter]

Assign to Gary to run the release procedure, which is here:

http://code.google.com/p/upc-specification/wiki/DraftReleaseProcedure

As before, I can help with step 6.

Original comment by danbonachea on 14 Sep 2012 at 10:03

• Added labels: Priority-Critical, Type-Task
• Removed labels: Priority-Medium, Type-Defect

[GoogleCodeExporter]

Dan,

The current document mark up files have these refs. to a Draft version.

lang/upc-lang-spec.tex:\newcommand{\mydraftversion}{Draft 1.2}
lib/opt/upc-lib-optional-spec.tex:\newcommand{\mydraftversion}{Draft 1.1}
lib/proposed/amo/upc-lib-atomic-ops-spec.tex:\newcommand{\mydraftversion}{Draft 
1.1}
lib/proposed/castability/upc-lib-castability-spec.tex:\newcommand{\mydraftversio
n}{Draft 1.1}
lib/proposed/nb-mem-ops/upc-lib-nb-mem-ops-spec.tex:\newcommand{\mydraftversion}
{Draft 1.1}
lib/req/upc-lib-required-spec.tex:\newcommand{\mydraftversion}{Draft 1.2}

Do you recommend that all of these versions will go to "Draft 2"?

Original comment by gary.funck on 19 Sep 2012 at 10:36

[GoogleCodeExporter]

Dan,

The current release procedure states:

2.Write a brief "cover note" summarizing the changes in this draft, and a 
release announcement email. Add the cover note to TeX. 

Given that there is now list of changes table (page 2), courtesy of some 
improvements that you made to the change macros, is there any need for 
additional "cover note" text in the draft document?

Obviously, for the release note, we might consider re-listing each issue 
described in the list of changes.

Original comment by gary.funck on 19 Sep 2012 at 10:41

[GoogleCodeExporter]

The language and required library documents have changed, so those should 
definitely be changed to Draft 2 and released. The optional doc is completely 
unchanged, but if you want to release that as well for completeness go ahead. 
The proposed documents should NOT be released, as they do not represent a 
committee consensus.

The current cover note is sufficiently generic that it's probably fine as-is, 
and as you say the new List of Changes section gives the details. I think the 
cover note should remain in all drafts to reinforce this fact this is a 
non-final, non-normative draft document. Perhaps just change the release 
procedure to:

2. Review the cover note and List of Changes section to ensure accuracy. Write 
a release announcement email summarizing the changes in this draft.

As a side note, I've noticed the page number hyperlinks in the List of Changes 
section sometimes redirect to the wrong page in the document (even though the 
printed page number is correct). I suspect this is caused by the anchor 
appearing in a footnote, and possibly insufficient iterations of latex-mk. I 
haven't spent time to track it down (especially since this table won't appear 
in the final document), but perhaps someone else with more TeX expertise knows 
how to fix this..

Original comment by danbonachea on 19 Sep 2012 at 11:05

[GoogleCodeExporter]

Dan wrote: "I've noticed the page number hyperlinks in the List of Changes 
section sometimes redirect to the wrong page in the document (even though the 
printed page number is correct). I suspect this is caused by the anchor 
appearing in a footnote, and possibly insufficient iterations of latex-mk."

Looking at the generated .lot file, it looks to me like the internal \ref{} 
that is being used to advance to the appropriate page is a reference to the 
*section* containing the changed text. If you click on the second issue 55 
change, which has page 31 listed, it goes to the beginning of section 6.6.2 
(page 30) ... which is the section where the change appears on the *next* page 
(page 31 as listed in the lot).

There may be a way to generate a label for the page where the change is 
actually made and reference that label, but given my limited knowledge of 
latex, I don't know how to accomplish that.

Aside: I did run pdflatex 7 times in a row by hand.  This did not affect the 
final page numbers shown, as expected, based upon the observations noted above.

Original comment by gary.funck on 19 Sep 2012 at 11:51

[GoogleCodeExporter]

"looks to me like the internal \ref{} that is being used to advance to the 
appropriate page is a reference to the *section* containing the changed text"

Ah ok - that makes sense, because I hijacked the latex list of tables to create 
that list, and hyperref is probably assuming the \table will create a label it 
can reference. It's a minor issue that doesn't affect the printed version or 
the final (non-draft) document, so let's just ignore it for now.

Original comment by danbonachea on 20 Sep 2012 at 12:43

[GoogleCodeExporter]

Attached, are:
1. the proposed release notice for Draft 2.
2. Draft 2 diff's.

Original comment by gary.funck on 21 Sep 2012 at 5:46

Attachments:

• upc-spec-1-3-draft-2-notice.txt
• ups-spec-draft-2-release-diffs.txt

[GoogleCodeExporter]

The draft note embedded in the release notice txt is outdated:

"This draft is otherwise believed to be semantically
identical in every detail to UPC language specification version 1.2
(ratified May 2005)"

should probably just replace that paragraph with the current cover note.

Original comment by danbonachea on 21 Sep 2012 at 5:44

[GoogleCodeExporter]

Also, what's the purpose of upc-spec-draft-2-release-diffs.txt ? (currently the 
contents are totally uninteresting)

I don't think it's necessary to release a TeX diff, I did enough hacking with 
the changes package to make all the relevant changes appear in the PDF output. 

Original comment by danbonachea on 21 Sep 2012 at 5:47

[GoogleCodeExporter]

I posted the diffs file for review only.  It lists the intended change of the 
various draft version identifiers.

I will update the release notice and re-post it as an attachment.

Original comment by gary.funck on 21 Sep 2012 at 7:59

[GoogleCodeExporter]

Revision: 127
Author:   gary.funck@gmail.com
Date:     Sat Sep 22 10:41:29 2012
Log:      Bump draft version to Draft 2
and add a Draft 2 release email notice.
http://code.google.com/p/upc-specification/source/detail?r=127

Added:
  /trunk/admin/upc-spec-1-3-draft-2-notice.txt
Modified:
  /trunk/lang/upc-lang-spec.tex
  /trunk/lib/opt/upc-lib-optional-spec.tex
  /trunk/lib/proposed/amo/upc-lib-atomic-ops-spec.tex
  /trunk/lib/proposed/castability/upc-lib-castability-spec.tex
  /trunk/lib/proposed/nb-mem-ops/upc-lib-nb-mem-ops-spec.tex
  /trunk/lib/req/upc-lib-required-spec.tex

Original comment by gary.funck on 22 Sep 2012 at 5:44

[GoogleCodeExporter]

Dan,
I briefly reviewed Draft 2, and noticed that the required library document does 
not have a "list of changes".  Please advise.

Original comment by gary.funck on 22 Sep 2012 at 5:46

[GoogleCodeExporter]

In comment 4, Dan suggested the following change to the draft release procedure.
"2. Review the cover note and List of Changes section to ensure accuracy. Write 
a release announcement email summarizing the changes in this draft."

I have updated the draft release procedure accordingly.

Original comment by gary.funck on 22 Sep 2012 at 5:48

[GoogleCodeExporter]

"I briefly reviewed Draft 2, and noticed that the required library document 
does not have a "list of changes".  Please advise."

Didn't seem worthwhile to include a LOC in the library doc for draft 2, since 
the only change was the very obvious addition of a new library section. We can 
easily add the LOC in a future draft of that doc if a bigger list of changes 
warrants.

Original comment by danbonachea on 22 Sep 2012 at 7:14

[GoogleCodeExporter]

Dan wrote: "Didn't seem worthwhile to include a LOC in the library doc for 
draft 2 ...".

Makes sense to me.

Please review the current Draft 2 document and if it OK, build the signed 
versions of the PDF files, upload them, etc.  Thanks.

Original comment by gary.funck on 22 Sep 2012 at 7:20

[GoogleCodeExporter]

Is now an appropriate time to bump the version number?

\subsubsection{Predefined macro names}

\index{predefined macros}
\npf The following macro names shall be defined by the
    implementation\footnote{In addition to these macro names,
    the semantics of [ISO/IEC00 Sec. 6.10.8] apply to the identifier MYTHREAD.}
[...]
\item{\tt \_\_UPC\_VERSION\_\_}
\index{\_\_UPC\_VERSION\_\_}
The integer constant 200505L.

Original comment by gary.funck on 22 Sep 2012 at 8:37

[GoogleCodeExporter]

"build the signed versions of the PDF files, upload them, etc"

Done - please verify you can read them. 

I created a self-certified digital identify for our working group. I still 
think someone should pony up the cash to purchase a real root certification for 
document signing, but until then I'll just use this private one.

Original comment by danbonachea on 22 Sep 2012 at 9:17

[GoogleCodeExporter]

"Is now an appropriate time to bump the version number?"

I would strongly say no - this is not a normative document, so that should not 
be incremented until the 1.3 spec is ratified (or nearly so).

Original comment by danbonachea on 22 Sep 2012 at 9:29

[GoogleCodeExporter]

Re: Comment 17 "Done - please verify you can read them."

Confirmed.

I will note that the change bars on the last page of the lib/req timers 
proposal cut off part of the text because it exceeds the right margin.  Not a 
show-stopper, just an observation.

Original comment by gary.funck on 22 Sep 2012 at 11:58

[GoogleCodeExporter]

Re: Comment 18 "I would strongly say no - this is not a normative document, so 
that should not be incremented until the 1.3 spec is ratified (or nearly so)."

Makes sense, however the counter-argument is that this Draft 2 is no longer 
version 200505 either.

Original comment by gary.funck on 23 Sep 2012 at 12:02

[GoogleCodeExporter]

Revision: 131
Author:   gary.funck@gmail.com
Date:     Sun Sep 23 17:02:59 2012
Log:      Tag spec. 1.3 draft 2 from trunk revision 130.

http://code.google.com/p/upc-specification/source/detail?r=131

Added:
 /tags/spec-1-3-draft-02

Original comment by gary.funck on 24 Sep 2012 at 12:13

[GoogleCodeExporter]

Dan,
If you haven't done so already, please rebuild the Draft 2 pdf's sign them and 
upload them.  When done please send out an email to the upc-spec-dev and 
upc-spec-wg lists.  After someone on those lists pings back that it is OK, we 
will release Draft 2.

Yili,
If you have a minute to quickly review the docs. after they're uploaded and Dan 
has sent an email, and then reply back to this issue, that would be appreciated.

Thanks.

Original comment by gary.funck on 24 Sep 2012 at 12:17

[GoogleCodeExporter]

Has something changed that requires rebuilding? Unless you had a problem 
opening the ones I already uploaded yesterday (and which have been visible on 
the site for 24 hours), those should be current..

Original comment by danbonachea on 24 Sep 2012 at 2:12

[GoogleCodeExporter]

I see you just moved the tag to r130, but it doesn't seem worthwhile to redo 
everything for that cosmetic fix, since the upload has already been on the 
website 24 hours - just re-tag from r128 and call it good.

Original comment by danbonachea on 24 Sep 2012 at 2:17

[GoogleCodeExporter]

The public draft 2 uploaded by Dan yesterday looks good to me.
Thanks! 

Original comment by yzh...@lbl.gov on 24 Sep 2012 at 2:33

[GoogleCodeExporter]

Dan/Yili, we will go with the r128 Draft 2 PDF's that have been uploaded.

I will adjust the tag momentarily.

Tomorrow AM, I will send out the notice.

A detail: the last that I checked, the draft 1 PDF's were still tagged as 
"favorites" in the download area.  Dan, your call, re: leave only the latest 
draft marked as a "favorite".

Original comment by gary.funck on 24 Sep 2012 at 3:15

[GoogleCodeExporter]

Revision: 132
Author:   gary.funck@gmail.com
Date:     Sun Sep 23 21:33:23 2012
Log:      Tag spec. 1.3 draft 2 from trunk revision 128.

http://code.google.com/p/upc-specification/source/detail?r=132

Added:
  /tags/spec-1-3-draft-02/trunk

Original comment by gary.funck on 24 Sep 2012 at 4:35

[GoogleCodeExporter]

The tag operation in comment 27 is a "fail", because it put trunk under the tag 
name.
Will try again.

Original comment by gary.funck on 24 Sep 2012 at 4:46

[GoogleCodeExporter]

Revision: 134
Author:   gary.funck@gmail.com
Date:     Sun Sep 23 21:50:10 2012
Log:      Tag spec. 1.3 draft 2 from trunk revision 128.

http://code.google.com/p/upc-specification/source/detail?r=134

Added:
 /tags/spec-1-3-draft-02

Original comment by gary.funck on 24 Sep 2012 at 4:51

[GoogleCodeExporter]

Thanks for processing the new draft and sorry it turned out to be such a hassle 
- I was hoping this would become more streamlined as we went along..

"A detail: the last that I checked, the draft 1 PDF's were still tagged as 
"favorites" in the download area.  Dan, your call, re: leave only the latest 
draft marked as a "favorite"."

I was planning to leave both Draft 1 and the current draft as favorites, since 
Draft 1 is the baseline for change comparisons.

PS- Don't forget to bump the draft version on the working trunk once everything 
is done.

Original comment by danbonachea on 24 Sep 2012 at 8:58

[GoogleCodeExporter]

$ send-upc-draft-release-mail 2 'September 22, 2012'
mutt -s'UPC Specification 1.3 Draft 2' 'upc@hermes.gwu.edu'
mutt -s'UPC Specification 1.3 Draft 2' 'upc-users@lbl.gov'
mutt -s'UPC Specification 1.3 Draft 2' 'upc-spec@hermes.gwu.edu'
mutt -s'UPC Specification 1.3 Draft 2' 'upc-spec-dev@googlegroups.com'
mutt -s'UPC Specification 1.3 Draft 2' 'upc-spec-wg@googlegroups.com'

Original comment by gary.funck on 24 Sep 2012 at 2:50

[GoogleCodeExporter]

Revision: 135
Author:   gary.funck@gmail.com
Date:     Mon Sep 24 07:54:15 2012
Log:      Bump the draft version number to 2.1
http://code.google.com/p/upc-specification/source/detail?r=135

Modified:
  /trunk/lang/upc-lang-spec.tex
  /trunk/lib/opt/upc-lib-optional-spec.tex
  /trunk/lib/proposed/amo/upc-lib-atomic-ops-spec.tex
  /trunk/lib/proposed/castability/upc-lib-castability-spec.tex
  /trunk/lib/proposed/nb-mem-ops/upc-lib-nb-mem-ops-spec.tex
  /trunk/lib/req/upc-lib-required-spec.tex

Original comment by gary.funck on 24 Sep 2012 at 2:56

[GoogleCodeExporter]

Draft 2 release complete.

Original comment by gary.funck on 24 Sep 2012 at 2:59

• Changed state: Fixed