Documenting UMA publication workflows
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
Regarding our publication workflows as documented in this thread: The symbolic linking process (which Oliver sets up manually for us) pretty nicely handles routing people to different versions of the spec and to the latest ("unversioned") spec. However, we've got this awkward manual step where we flip back and forth between "draft-" and "rec-" named specs at draft-to-final and final-to-new-draft stages. Since we're about to embark on an instance of the latter stage, should we consider moving away from the "draft-" and "rec-" naming scheme and using something more generic? Kantara's production of technical specs is not so voluminous as to demand putting in place an automated toolchain (a la IETF/IESG) for managing such things. Any suggestions for changes at this juncture, keeping in mind that it would be ideal to propagate the idea throughout Kantara, and not just use it for our WG? I'd like to see if we can come up with and assess recommendations quickly. Thanks! *Eve Maler*Cell +1 425.345.6756 | Skype: xmlgrrl | Twitter: @xmlgrrl On Mon, Dec 28, 2015 at 7:30 PM, Eve Maler <eve@xmlgrrl.com> wrote:
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
Justin, George, and Eve met on these topics today. Some conclusions about logistics: - We want to ask Kantara staff to break out the ".../docs" area so that there's a specific Kantara space for each level of KI-approved types of documents, e.g. Recommendations and other, and then each group has its own area for group-approved and other stages of docs. This helps those who want to access docs and distinguish them by their location (e.g. through browser history). - We don't like starting published doc URLs with rec- vs. draft-. Better to keep the start of the link the same (e.g. uma-core-2.0-) and tack on a suffix like draft-<datestamp> or draft-<buildnumber>. We're slightly leaning towards build numbers; we'd do this manually. Or we could use the Git commit hash, which isn't sequential, nor pronounceable... We're agreed on build numbers -- and let's use them freely. - The source in GitHub would just be uma-core-2.0. And yes, we prefer the dot; it's 2016. :-) - Now, after launching a new draft spec revision cycle, we would tag and branch instead. Since we currently have versioned file names, and a bunch of weird old stuff in our repo, we need to clean it up. We shouldn't be checking in the HTML, and that's to be uploaded to the KI site in any case. Justin is willing to take that one (AI: "Nuke the UMA repository"). Regarding spec substance, Eve is taking an action item to comb through the meeting minutes where we've made decisions regarding "UMA.next" and parcel out spec editing assignments, most heavily to herself and Maciej at first. Justin is cautious about taking spec editing action items in the short term but will see what he can do about reviewing. George is especially interested to look at metadata topics. *Eve Maler*Cell +1 425.345.6756 | Skype: xmlgrrl | Twitter: @xmlgrrl On Mon, Dec 28, 2015 at 7:30 PM, Eve Maler <eve@xmlgrrl.com> wrote:
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
participants (1)
-
Eve Maler