[KI-LC] Fwd: Documenting UMA publication workflows

Eve Maler eve at xmlgrrl.com
Thu Mar 10 18:31:57 CST 2016


I think Maciej had some updates that he wanted to make to this flow, having
to do with how/when to create new docs in the GitHub repo, but at least the
soft (symbolic) link stuff is here... And -- bonus! -- this has the Status
wording. :-)


*Eve Maler*Cell +1 425.345.6756 | Skype: xmlgrrl | Twitter: @xmlgrrl


---------- Forwarded message ----------
From: Eve Maler <eve at xmlgrrl.com>
Date: Mon, Dec 28, 2015 at 7:30 PM
Subject: Documenting UMA publication workflows
To: "wg-uma at kantarainitiative.org WG" <wg-uma at kantarainitiative.org>


Hi folks-- Hope you are enjoying post-Christmas reentry or more holiday
time, or whatever the case may be. Maciej and I are working on publishing
the new Recommendations, and due to that, I unearthed the
permanent/symbolic link information that I promised to Justin; we thought
it would be a good idea to document the processes here -- and in the GitHub
readme... It seems to work pretty well for now given that there isn't that
much to the entire publishing process for our WG or others, but if you see
ways to improve it for the future, let us know.

After completing a draft spec revision cycle and getting it approved:

   1. Edit the draft-uma-core-vn_n[_n] and
   draft-oauth-resource-reg-vn_n[_n] sources to change from Status #3 to #4
   (see below), leaving the previous date in place.
   2. Run the stylesheet over the XML sources to produce .html outputs,
   review the results as required, sync GitHub, and upload the last drafts by
   FTP (Eve and Oliver can do this).
   3. Save the draft-uma-core-vn_n[_n] and
   draft-oauth-resource-reg-vn_n[_n] sources off to new files in the repo
   starting with rec- instead.
   4. Change the Status section of the new files from #4 to #5, the date,
   and any other metadata (some of this has to be done in the stylesheet,
   which is in the repo).
   5. Update the two specs' References links to each other in the Reference
   section.
   6. Run the stylesheet over the XML sources to produce HTML output with
   .html extensions, review the results as required, sync to GitHub, and FTP
   the HTML results to the website (Eve and Oliver can do this).
   7. Get symbolic links created (see below) from the versioned rec- HTML
   links to generic links (Oliver can do this).

After launching a new draft spec revision cycle:

   1. Save the rec-uma-core-vn_n[_n] and rec-oauth-resource-reg-vn_n[_n]
   sources off to new files in the repo starting with draft- and having the
   agreed new version numbers instead.
   2. Edit the Status section from #5 to #1.
   3. Proceed to edit the new drafts, and periodically produce HTML results
   that can be uploaded through FTP.
   4. Get symbolic links created from the versioned draft- HTML links to
   generic links (Oliver can do this).

Here are the stages of the Status section (embed links throughout as
appropriate):

   1. This document is a draft technical specification produced by the
User-Managed
   Access Work Group
   <http://kantarainitiative.org/confluence/display/uma/Home>.
   2. This document is a Kantara Initiative Draft Recommendation approved
   by the User-Managed Access Work Group
   <http://kantarainitiative.org/confluence/display/uma/Home>.
   3. This document is a Draft Recommendation approved by the User-Managed
   Access Work Group
   <http://kantarainitiative.org/confluence/display/uma/Home> and certified
   by the Leadership Council to undergo a Kantara All-Member Ballot.
   4. This document is a Draft Recommendation approved by the User-Managed
   Access Work Group
   <http://kantarainitiative.org/confluence/display/uma/Home> and certified
   by the Leadership Council to undergo a Kantara All-Member Ballot. The
   Ballot having passed, this document has been superseded by the
   Recommendation version of the document.
   5. This document was developed by the User-Managed Access Work Group
   <http://kantarainitiative.org/confluence/display/uma/Home> and approved
   by the Membership of the Kantara Initiative
   <http://kantarainitiative.org/> as a Recommendation.

Here is how the symbolic links work:

https://docs.kantarainitiative.org/uma/rec-uma-core-vn_n[_n].html -
Permanent link to specific Core Rec
https://docs.kantarainitiative.org/uma/rec-oauth-resource-reg-vn_n[_n].html
- Permanent link to specific RSR Rec
https://docs.kantarainitiative.org/uma/draft-uma-core-vn_n[_n].html -
Permanent link to specific Core Rec
https://docs.kantarainitiative.org/uma/draft-oauth-resource-reg-vn_n[_n].html
- Permanent link to specific RSR Rec

https://docs.kantarainitiative.org/uma/rec-uma-core.html - Symbolic link to
latest Core Rec
https://docs.kantarainitiative.org/uma/rec-oauth-resource-reg.html -
Symbolic link to latest RSR Rec
https://docs.kantarainitiative.org/uma/draft-uma-core.html - Symbolic link
to latest Core draft
https://docs.kantarainitiative.org/uma/draft-oauth-resource-reg.html -
Symbolic link to latest RSR draft


*Eve Maler*Cell +1 425.345.6756 | Skype: xmlgrrl | Twitter: @xmlgrrl
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://kantarainitiative.org/pipermail/lc/attachments/20160310/bb311e2b/attachment-0001.html>


More information about the LC mailing list