Release Spec 1.3 Draft 1 for public consumption

[Former user]

Originally reported on Google Code with ID 84 ``` 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.

```

Reported by `danbonachea` on 2012-08-20 02:54:18

[Former user]

``` I've just added a cover note for draft 1.0 ```

Reported by `danbonachea` on 2012-08-20 02:57:08

[Former user]

Reported by `danbonachea` on 2012-08-20 03:26:03 - Labels added: Milestone-Spec-1.3

[Former user]

``` 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.

```

Reported by `gary.funck` on 2012-08-20 15:26:35

[Former user]

``` "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

```

Reported by `danbonachea` on 2012-08-20 17:36:40

[Former user]

``` 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. ```

Reported by `gary.funck` on 2012-08-21 17:14:20

[Former user]

``` 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.

```

Reported by `danbonachea` on 2012-08-21 17:38:59

[Former user]

``` 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.

```

Reported by `gary.funck` on 2012-08-21 17:45:55

[Former user]

``` 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. ```

Reported by `yili.zheng` on 2012-08-22 02:07:03

[Former user]

``` "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.

```

Reported by `danbonachea` on 2012-08-22 03:16:00

[Former user]

``` 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.

```

Reported by `gary.funck` on 2012-08-22 14:57:52

[Former user]

``` "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. ```

Reported by `danbonachea` on 2012-08-22 20:37:02

[Former user]

Reported by `gary.funck` on 2012-08-22 23:04:59

[Former user]

``` Draft 1 has been checked in as revision 88.

```

Reported by `gary.funck` on 2012-08-22 23:10:36

[Former user]

```

Revision: 89 Author: [e-mail] 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 ```

Reported by `gary.funck` on 2012-08-22 23:25:36

[Former user]

``` 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.

```

Reported by `gary.funck` on 2012-08-23 00:04:10

[Former user]

``` Revision: 90 Author: [e-mail] 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

```

Reported by `gary.funck` on 2012-08-23 00:17:08

[Former user]

``` 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.

```

Reported by `gary.funck` on 2012-08-23 00:20:19

[Former user]

``` "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).

```

Reported by `danbonachea` on 2012-08-23 05:30:26

[Former user]

``` Revision: 91 Author: [e-mail] 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

```

Reported by `gary.funck` on 2012-08-23 05:44:22

[Former user]

``` 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.

```

Reported by `gary.funck` on 2012-08-23 14:29:11

[Former user]

``` 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.

```

Reported by `gary.funck` on 2012-08-23 14:50:22

[Former user]

``` 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.

```

Reported by `gary.funck` on 2012-08-23 15:09:08

[Former user]

``` 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."

```

Reported by `gary.funck` on 2012-08-23 15:19:44

[Former user]

``` 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.

```

Reported by `gary.funck` on 2012-08-23 15:37:39

[Former user]

``` 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.

```

Reported by `gary.funck` on 2012-08-23 17:26:07

[Former user]

``` "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.

```

Reported by `danbonachea` on 2012-08-23 22:41:17

[Former user]

``` 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.

```

Reported by `gary.funck` on 2012-08-23 23:09:15

[Former user]

``` "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? ```

Reported by `danbonachea` on 2012-08-23 23:48:59

[Former user]

``` 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: [e-mail] [e-mail] [e-mail]

Yili also suggested: [e-mail]

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

```

Reported by `gary.funck` on 2012-08-24 16:11:06

[Former user]

``` 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: [e-mail]

```

Reported by `danbonachea` on 2012-08-24 17:49:17

[Former user]

``` 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. ```

Reported by `danbonachea` on 2012-08-24 17:56:51

[Former user]

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

1. 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.

```

Reported by `gary.funck` on 2012-08-24 18:18:55

[Former user]

``` 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.

```

Reported by `gary.funck` on 2012-08-25 00:52:19

<hr>

• *Attachment: [upc-spec-1-3-draft-01-notice.txt](https://storage.googleapis.com/google-code-attachments/upc-specification/issue-84/comment-33/upc-spec-1-3-draft-01-notice.txt)*

[Former user]

``` In comment #30, Dan wrote: "I would additionally suggest: [e-mail]"

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.

```

Reported by `gary.funck` on 2012-08-25 15:36:09

[Former user]

``` 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. ```

Reported by `gary.funck` on 2012-08-25 15:39:59

[Former user]

```

mutt -s'UPC Specification 1.3 Draft 1' '[e-mail]' mutt -s'UPC Specification 1.3 Draft 1' '[e-mail]' mutt -s'UPC Specification 1.3 Draft 1' '[e-mail]' mutt -s'UPC Specification 1.3 Draft 1' '[e-mail]' mutt -s'UPC Specification 1.3 Draft 1' '[e-mail]'

Done.

```

Reported by `gary.funck` on 2012-08-25 16:50:48 - Status changed: `Done`