Release Spec 1.3 Draft 1 for public consumption

[GoogleCodeExporter]

I believe the current 1.3 draft is now semantically equivalent to 1.2. We need 
to officially stamp 1.3 draft 1.0 and release it to the public, so that we can 
start committing semantic changes and updates. 

I propose the following "release procedure" for this and future spec drafts:

1. Add a brief "cover note" summarizing the changes in this draft, and a 
release announcement email.
2. Update draft number to end in .0 (eg Draft 1.0)
3. Generate the official PDF and HTML output, both with and without change bars.
4. Visually scan each page of the output for formatting problems. Fix any 
problems and goto 3.
5. Create a project-wide SVN tag for the draft
6. Post the draft in the downloads section
7. Mail the draft to the whole world with release announcement
8. Increment the draft number for future commits (eg. Draft 1.1)

As Gary has done the most Latex slinging I nominate him to execute this 
procedure for draft 1.0.

Original issue reported on code.google.com by danbonachea on 20 Aug 2012 at 2:54

[GoogleCodeExporter]

I've just added a cover note for draft 1.0

Original comment by danbonachea on 20 Aug 2012 at 2:57

[GoogleCodeExporter]

Original comment by danbonachea on 20 Aug 2012 at 3:26

• Added labels: Milestone-Spec-1.3

[GoogleCodeExporter]

Dan, I agree that now is a good time to release the 1.0 Draft, and the 
procedure that you outline looks good.  I'll begin work on it, and let 
you/others know if I run into any glitches where I can use some additional help.

A few questions/observations:

HTML:  When I originally changed the LaTeX mark up to make it more HTML 
friendly it required some rework of the existing mark up.  The latex2html 
package emulates commonly occurring latex macros in Perl (of all things) and 
that is a less-than-precise emulation as one might expect.  The latex2html 
program is often particular about the form that some latex macros take.  Also 
the ordering of \usepackage{} is important.  Implementing HTML may require some 
formatting changes to the existing latex markup that may make diff's of the 
mark up more difficult. I'll spend some time on this and see if HTML can be 
re-implemented easily.  If not, my recommendation is that we defer that task.

Question: will the lib/proposed documents be excluded from the 1.3.1.0 draft?

If lib/proposed/* is excluded, then presumably the svn tagged hierarchy will 
not include lib/proposed?  Technically, this is problematic because the 
lib/Makefile will unconditionally re-curse into lib/proposed.  If we decide 
that is necessary, we may either need to tweak the Makefile to accept some 
EXCLUDE_PROPOSED make variable or we need to branch the 1.0 draft and make the 
Makefile change in the branch.  A branch would allow us to add (or customize) a 
release notice that we send out via email for example.

Original comment by gary.funck on 20 Aug 2012 at 3:26

[GoogleCodeExporter]

"I'll spend some time on this and see if HTML can be re-implemented easily.  If 
not, my recommendation is that we defer that task."

I agree. Given that, I think we should focus on entirely on PDF output and 
making it look correct until the new document is ratified. Once that happens, 
we can create a private branch of the ratified document and do whatever HTML 
hackery there to create a final HTML output for distribution.

"Question: will the lib/proposed documents be excluded from the 1.3.1.0 draft?"

Yes - this draft is supposed to be a reformatted 1.2, so omit all new content. 
We can and should start distributing proposed library drafts separately, once 
we are close to committee consensus on them.

"If lib/proposed/* is excluded, then presumably the svn tagged hierarchy will 
not include lib/proposed?"

No - just tag the whole repository. Tags are free, and we should not be 
distributing the document source, just the 3 PDF documents output. 

We may even want to take steps to make the TeX sources private, so random 
people can't easily download them and build divergent and potentially confusing 
versions.

As an addendum to the release procedure, I think we should also 
password-protect the PDF output files (to prevent accidental, casual 
modifications). We should also consider adding a certified digital signature 
(to provide authenticity verification). In order for the latter to be 
meaningful we would need to purchase a CDS digital certificate from a root 
provider like VeriSign or Entrust: 
http://www.adobe.com/security/partners_cds.html

Original comment by danbonachea on 20 Aug 2012 at 5:36

[GoogleCodeExporter]

Going down the list:

1. Add a brief "cover note" summarizing the changes in this draft, and a 
release announcement email.

I assume that the cover note that Dan added on the first page is sufficient for 
each document per se.

2. Update draft number to end in .0 (eg Draft 1.0)

I'll do this soon.

3. Generate the official PDF and HTML output, both with and without change bars.

Do we currently have any changes that warrant change bars?  My impression is 
"no."

For example, the mis-spelling UPC_MAX_BLOCKSIZE remains in the table at 6.2p2.
This is consistent with the purpose/scope of this initial draft, I think.

I recommend removing the "List of Changes" on page 3.  It only shows authors 
and the raw count of their changes.  When I originally added this capability, I 
had hoped it would summarize the change and link to it.  Unfortunately, the 
latex package that we use to log changes doesn't do that.  Also, we don't have 
a "list of changes" section in the library specification documents.

4. Visually scan each page of the output for formatting problems. Fix any 
problems and goto 3.

I have made a pass over the language specification and the two library 
documents ("required" and "optional").  Everything looks good, no surprises.  I 
will note that there are some excursions over the right margin that can be 
distracting, but per earlier discussions, we won't attempt to fix those.

In the main language specification, there is an "Acknowledgements" section that 
should likely be updated in the next draft.  Also, "Introduction" discusses the 
specification versions, date of release and so on.  This should be updated in 
the next draft.

Original comment by gary.funck on 21 Aug 2012 at 5:14

[GoogleCodeExporter]

I agree with all your observations in comment 5. No change bars should be 
needed for this draft, as we are asserting it is semantically identical, and it 
will be the baseline for change bar comparison in future drafts.

I think it may still be useful to have an informal List of Changes as a page 
near the start in future drafts, even if it's static text that we update 
manually. It's empty for this draft but in future drafts it can help focus 
reviewer attention on the sections with changes. We might even consider keeping 
it for the final spec - C99/C11 has a similar section which I find useful.

Original comment by danbonachea on 21 Aug 2012 at 5:38

[GoogleCodeExporter]

Dan wrote: "I think it may still be useful to have an informal List of Changes 
as a page near the start in future drafts, even if it's static text that we 
update manually. It's empty for this draft but in future drafts it can help 
focus reviewer attention on the sections with changes. We might even consider 
keeping it for the final spec - C99/C11 has a similar section which I find 
useful."

I agree.  However, for this draft, I will leave out the list of changes 
section.  For the next draft it will be added back in, but will use manually 
added entries, perhaps with forward references to relevant sections.

Original comment by gary.funck on 21 Aug 2012 at 5:45

[GoogleCodeExporter]

Just a couple of small suggestions:
1) When announcing the draft to the public, how about just including a link for 
download instead of attaching a PDF.  Some people may consider an unsolicited 
PDF attachment as a spam or even a virus.
2) How about only using integers for draft versions?  I.e., Draft 1, 2, 3...
It may be just my peculiarity but I feel having minor version numbers for 
drafts (e.g., UPC 1.3 Draft 1.2) seems too complicated. 

Original comment by yili.zh...@gmail.com on 22 Aug 2012 at 2:07

[GoogleCodeExporter]

"How about only using integers for draft versions?  I.e., Draft 1, 2, 3...
It may be just my peculiarity but I feel having minor version numbers for 
drafts (e.g., UPC 1.3 Draft 1.2) seems too complicated."

Agreed - the "published" drafts should always have an integer draft number (I 
don't really care if its "1.0" or "1", perhaps the latter is less confusing). 
The motivation for a decimal in the unreleased version is to make it clear that 
PDFs generated from the day-to-day version in SVN are NOT an official draft or 
version controlled.

Original comment by danbonachea on 22 Aug 2012 at 3:16

[GoogleCodeExporter]

Speaking of whole-numbered draft numbers, I'll offer an alternative.

There is a latex package called "svn-multi"; it supports querying the last SVN 
version number of an update, author, date, and URL of last change.  It has an 
advantage over similar svn-related packages in that it will output the highest 
numbered SVN rev. in a series of all updates to any of the individual .tex 
files that are part of the larger document.  It is fairly easy to set up and 
use (by adding a couple of lines of latex at the top of each .tex file and be 
setting svn props on each file).  This could easily be done with a batch edit). 
 In that scenario, you would see draft versions like '46', '47', ... and so on. 
 We could prefix 1. in front of that to emphasize first draft if necessary.  
The rev. numbers would likely be different across separate spec. documents, 
unless (for example) the common preamble file happened to be the last file 
updated.

Let me know if this addition of svn last change revision number/date/author 
might be of interest.

Original comment by gary.funck on 22 Aug 2012 at 2:57

[GoogleCodeExporter]

"Let me know if this addition of svn last change revision number/date/author 
might be of interest."

It might be nice for our internal use, but given how carefully we're monitoring 
commits it's probably not worth spending alot of time on. It also would not 
capture uncommitted changes, so the document editors still have to be careful 
what they're building/distributing. In any case it's not relevant to publicly 
distributing draft 1.0, which is currently our biggest blocker to progress on 
spec revision.

Original comment by danbonachea on 22 Aug 2012 at 8:37

[GoogleCodeExporter]

Original comment by gary.funck on 22 Aug 2012 at 11:04

• Changed title: Release Spec 1.3 Draft 1 for public consumption

[GoogleCodeExporter]

Draft 1 has been checked in as revision 88.

Original comment by gary.funck on 22 Aug 2012 at 11:10

[GoogleCodeExporter]

Revision: 89
Author:   gary.funck@gmail.com
Date:     Wed Aug 22 16:21:44 2012
Log:      Tag spec. 1.3 draft 1
http://code.google.com/p/upc-specification/source/detail?r=89

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

Original comment by gary.funck on 22 Aug 2012 at 11:25

[GoogleCodeExporter]

The spec. files have been uploaded to the Download section, and have been 
marked as "Featured".  You can either download them from the Download section, 
or go to the main project page: http://code.google.com/p/upc-specification/ and 
look for featured downloads in the left side bar.

Please down load the draft 1 specs. and give them a quick review.  Report any 
problems here.

Original comment by gary.funck on 23 Aug 2012 at 12:04

[GoogleCodeExporter]

Revision: 90
Author:   gary.funck@gmail.com
Date:     Wed Aug 22 17:08:52 2012
Log:      Bump the draft version number to 2
http://code.google.com/p/upc-specification/source/detail?r=90

Original comment by gary.funck on 23 Aug 2012 at 12:17

[GoogleCodeExporter]

Although I'm relatively confident that the Draft 1 documents are OK (that's why 
I went ahead and bumped the draft number and created the tag), I will wait to 
hear from someone on this list that draft documents are in suitable form for 
release before taking the next step of drating a release note and sending it 
out.

Original comment by gary.funck on 23 Aug 2012 at 12:20

[GoogleCodeExporter]

"I will wait to hear from someone on this list that draft documents are in 
suitable form for release before taking the next step of drating a release note 
and sending it out."

The documents you posted look ok to me on casual inspection. As mentioned in 
comment 4 I think we should consider password protecting the PDF (as ISO specs 
do), to prevent accidental modification by users - but that's a minor issue.

I do have one important criticism, regarding the last step in the release 
procedure:

"8. Increment the draft number for future commits (eg. Draft 1.1)"

I really meant 'Draft 1.1' here, not 'Draft 2'. The latter is currently 
committed in SVN, which has the potential to cause confusion because any PDFs 
we generate internally and pass around over the coming weeks are definitely NOT 
'Draft 2' and should not be labeled as such. I want to clearly distinguish any 
Day-to-day SVN versions (fractional drafts) from public draft releases 
(integral draft), so SVN should never contain an integer draft number except in 
the tagged draft. Please change this in SVN ASAP (I would do it myself but 
don't have access to my working copy atm).

Original comment by danbonachea on 23 Aug 2012 at 5:30

[GoogleCodeExporter]

Revision: 91
Author:   gary.funck@gmail.com
Date:     Wed Aug 22 22:42:52 2012
Log:      Reset the draft version to 1.1
http://code.google.com/p/upc-specification/source/detail?r=91

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/proposed/tick/upc-lib-tick-spec.tex
  /trunk/lib/req/upc-lib-required-spec.tex

Original comment by gary.funck on 23 Aug 2012 at 5:44

[GoogleCodeExporter]

Dan as noted in Comment 19, I have reset the version to 1.1.  I had chosen 2 
based upon the recommendation that we use single digit numbers for drafts.  I 
had assumed that either we viewed it as a draft-in-progress or that we would 
bump the number to 3 (similar to the even/odd style of Linux kernel releases) 
when we made our next release. In any event, it is now set to 1.1.

Original comment by gary.funck on 23 Aug 2012 at 2:29

[GoogleCodeExporter]

In comment #4 Dan suggested: "As an addendum to the release procedure, I think 
we should also password-protect the PDF output files (to prevent accidental, 
casual modifications). We should also consider adding a certified digital 
signature (to provide authenticity verification)."

I do not plan to password protect nor digitally sign the PDF's.  My main 
motivation for not doing so is simply to minimize my own time spent on 
administrative tasks.  Secondarily, I think that the chance that the documents 
will be mis-used is low.

If we do copy protect the PDF's, I recommend *not* dis-allowing copy/paste.

Note that the SHA-1 check sums of the documents are listed on the download 
page.  

If someone else wants to be responsible for adding copy protection and 
digitally signing, please reply to this comment _today_ and volunteer.

Original comment by gary.funck on 23 Aug 2012 at 2:50

[GoogleCodeExporter]

In comment #4 Dan suggests: "We may even want to take steps to make the TeX 
sources private, so random people can't easily download them and build 
divergent and potentially confusing versions."

I looked at the project's "Administration" tab, and in fact see *no* method for 
making the project _private_, in the sense that it cannot be found via a Google 
search, or cannot be viewed by a non-member.  Non-members can view, but not 
modify, the project content inclusive the issues list, the SVN repository, and 
the wiki.

If you find a method for selectively "cloaking" aspects of the project's web 
site, please post it here.

That said, I personally would prefer to keep both the project open, and its 
development and review process open.  However, if there is consensus or simply 
a strong emphasis on restricting access, I recommend that this aspect of 
project management be discussed here or on a new issue ticket.

Side note: I logged off of Google/Gmail, becoming a normal non-member.  I 
confirmed that I could find the project (a search of "UPC specification" turns 
up this project as item number 6.  Further, I could view all project content.

Original comment by gary.funck on 23 Aug 2012 at 3:09

[GoogleCodeExporter]

In my view, this release of Draft 1 will have limited
utility to a UPC user because it essentially doesn't
change anything.  In fact, I have no problem with
no announcement and just simply agreeing that it
is the base line.

A broader question is: how can users receiving notice
of the UPC spec. split and the ongoing specification
update participate in the review?  

There are several choices of forum for feedback.
  1. They can be added to the UPC specification
  development (upc-spec-dev) mailing list. Unfortunately, that is
  a rather high volume list and their contribution
  may be lost.
  2. We can start a new mailing list, upc-spec-discuss.  Per Google
  projects, this appears to be the generally recommended approach.
  3. We can allow the users to request being added to
  UPC Specification Google Project, as a member
  who can fully participate on the issues list
  but can't do svn updates, wiki updates, etc.
  I haven't looked into the details of controlling those users.
  5. They can send comments to either an individual
  who is part of the upc-spec-dev project.

There are likely several other possibilities.

Please make your recommendations here.

Note: The Administration tab says the following:

"Project contributors start with the same permissions as non-members, but their 
role in the project is visible.

Additional permissions can be granted to committers and contributors on the 
project's people sub-tab."

Original comment by gary.funck on 23 Aug 2012 at 3:19

[GoogleCodeExporter]

Follow up, observations on both contributors and non-members.

This page details the permissions ascribed to each project member category.
http://code.google.com/p/support/wiki/Permissions
As you can see, non-members can view content, create an issue, add an issue 
comment and add a wiki comment.

Contributors start as non-members, but can have permissions selectively 
upgraded.

Original comment by gary.funck on 23 Aug 2012 at 3:37

[GoogleCodeExporter]

Additional info., re: non-member capabilities:

- If you are a non-member, and do *not* have a Google account, you will *not* 
be able to add comments to issues, etc.

- If you are a non-member and can log in as a Google user, you *will* be able 
create issues, add comments to issues, and add comments to wiki pages.

- Separately, Nenad noted that there is an RFE in the Google Projects issue 
tracker requesting private projects; confirming that there is no current 
mechanism for limiting access to a Google Project.

Original comment by gary.funck on 23 Aug 2012 at 5:26

[GoogleCodeExporter]

"If someone else wants to be responsible for adding copy protection and 
digitally signing, please reply to this comment _today_ and volunteer."

I've just replaced the copies in the download directory with the same document 
but password-protected and digitally signed. I volunteer to handle that task 
for every draft we release. I'm using a self-certified digital signature, so if 
we ever want "real" authentication, someone will need to volunteer to purchase 
a root certified CDS signature certificate (comment 4).

"In my view, this release of Draft 1 will have limited utility to a UPC user 
because it essentially doesn't change anything.  In fact, I have no problem 
with no announcement and just simply agreeing that it is the base line."

I agree there are no real changes to review, but I think it's still worth one 
email to the user's lists, basically stating "Look, the spec is really 
changing, here's a preview, if you want to participate or contribute input, now 
is your chance".

"That said, I personally would prefer to keep both the project open, and its 
development and review process open.  However, if there is consensus or simply 
a strong emphasis on restricting access, I recommend that this aspect of 
project management be discussed here or on a new issue ticket."

I don't think we should try to "hide" our issues list or downloads, in fact as 
long as we don't have problems with malicious updates to the issue database I 
don't see a problem with allowing any interested party full access to the issue 
database and email list and archives.

I was only suggesting that we "hide" the tex sources (ie SVN) to discourage 
non-members from building a divergent spec, but it doesn't appear that's 
feasible on this site, so be it.

Original comment by danbonachea on 23 Aug 2012 at 10:41

[GoogleCodeExporter]

Before we send an announcement, I recommend that we agree to tell the users 
about the UPC specification development project, how they can access the issues 
list and/or the wiki, and contribute to those specification-related resources.

I recommend that for now we defer any decision to add a new mailing list whose 
sole purpose is to discuss the specification.  Instead, we might permit adding 
interested parties as contributors (with some upgraded privileges) or add them 
to upc-spec-dev mailing list.

Original comment by gary.funck on 23 Aug 2012 at 11:09

[GoogleCodeExporter]

"I recommend that for now we defer any decision to add a new mailing list whose 
sole purpose is to discuss the specification."

Agreed - that is probably unnecessary.

"Instead, we might permit adding interested parties as contributors (with some 
upgraded privileges) or add them to upc-spec-dev mailing list."

The draft note on the front cover already includes a hyperlink to this spec dev 
website, where anyone can find the downloads, wiki and issues list. Perhaps 
your announcement email can include a note that people can reply to you (Gary) 
if they want additional permissions or to be added our existing spec-dev 
mailing list.

Is there anything else we need to figure out?

Original comment by danbonachea on 23 Aug 2012 at 11:48

[GoogleCodeExporter]

In comment #28, Dan asks: "Is there anything else we need to figure out?"

I think that we're good to go.

I will draft a release notice and post it here for review/comment.

As far as sending the notice, I recommend the following email lists:
 upc-spec@hermes.gwu.edu
 upc-users@lbl.gov
 upc@hermes.gwu.edu

Yili also suggested:
 hpc-announce@mcs.anl.gov

Do those four email lists seem sufficient for this notice and subsequent 
notices?

Original comment by gary.funck on 24 Aug 2012 at 4:11

[GoogleCodeExporter]

hpc-announce seems to be only CFPs (many for quite unrelated fields), so I'm 
not sure we should spam that one, but it's your call.

I would additionally suggest:
UPC-HELP@hermes.gwu.edu

Original comment by danbonachea on 24 Aug 2012 at 5:49

[GoogleCodeExporter]

I've created a wiki for holding the release procedure we hammered out in this 
issue:

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

Gary please feel free to add any details you think are important.

Once the draft goes out to the world we can close this issue.

Original comment by danbonachea on 24 Aug 2012 at 5:56

[GoogleCodeExporter]

Dan, thanks.  I added a step 1:
1. Create an issue ticket to track the progress of the draft release. (example: 
issue #84)

I note also the step to run the release note by upc-spec-dev and upc-spec-wg: 
OK.

FYI, I think that upc-spec-wg should always be cc'd separately from the other 
UPC email lists.  It is currently a closed list (not publicly visible, IIRC).  
For that matter, upc-spec-dev may also be, but I see no issue with making it 
public, and allowing subscription requests.

Original comment by gary.funck on 24 Aug 2012 at 6:18

[GoogleCodeExporter]

Attached, is the release notice that I plan to send out.
Dan and Yili have reviewed it and OK'd it.

I will send it out tomorrow AM.

Original comment by gary.funck on 25 Aug 2012 at 12:52

Attachments:

• upc-spec-1-3-draft-01-notice.txt

[GoogleCodeExporter]

In comment #30,  Dan wrote: "I would additionally suggest: 
UPC-HELP@hermes.gwu.edu"

I visited the archives for that email list (I'm not subscribed):
https://hermes.gwu.edu/cgi-bin/wa?A0=upc-help
Sadly, it is both overwhelmed by spam and generally non-responsive to any 
recent relevant inquiries.  My recommendation is that the list should be 
de-commissioned and that the few relevant/responsive posts be added to a FAQ.

I do not plan to send the spec. draft release notice to that email list.

Original comment by gary.funck on 25 Aug 2012 at 3:36

[GoogleCodeExporter]

Note: I plan to add a top-level 'admin' directory to the SVN tree that will 
hold things like release notices, scripts for sending them out and anything 
else that relates to administrating the UPC specification project.

Original comment by gary.funck on 25 Aug 2012 at 3:39

[GoogleCodeExporter]

mutt -s'UPC Specification 1.3 Draft 1' 'upc@hermes.gwu.edu'
mutt -s'UPC Specification 1.3 Draft 1' 'upc-users@lbl.gov'
mutt -s'UPC Specification 1.3 Draft 1' 'upc-spec@hermes.gwu.edu'
mutt -s'UPC Specification 1.3 Draft 1' 'upc-spec-dev@googlegroups.com'
mutt -s'UPC Specification 1.3 Draft 1' 'upc-spec-wg@googlegroups.com'

Done.

Original comment by gary.funck on 25 Aug 2012 at 4:50

• Changed state: Done