Difference between revisions of "ITI CP Integration Process"

From IHE Wiki
Jump to navigation Jump to search
 
(190 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 +
__TOC__
  
 +
== CP ADMINISTRATOR:  To prepare Github for CP integration into TI Supps (Word, not HTML) ==
 +
'''(1) Get the Word documents for the Currently Published Final Text volumes and TI Supplements:'''
 +
* Go to the location where Mary stores currently published IHE framework documents:
 +
** On the IHE Google Drive in:  in [https://drive.google.com/drive/folders/1WTHmopm5TC0omqvC2TjIlzskrIF2cArh IHE Documents > DocumentPublication > CurrentPublished > ITInfrastructure]
 +
* Download a local copy of the Word document(s) that will be updated by CPs.  Each of the file names will end with a version and a date, for example: ''IHE_ITI_Suppl_mCSD_Rev3-1_TI_2019-03-06.docx'' or ''IHE_ITI_TF_Rev16-0_Vol1_FT_2019-07-12.docx''
 +
* Update the filenames to remove the date, eg ''IHE_ITI_Suppl_mCSD_Rev3-1_TI.docx'' or ''IHE_ITI_TF_Rev16-0_Vol1_FT.docx''
  
−
== To Integrate CPs ==
+
'''(2) Upload the CurrentPublished Word documents into Gitub:'''
  
−
''this is Gila's process''
+
Note: These instructions assume the user is using the web UI for Github.
  
−
== To check integrated CPs ==
+
* Go to: https://github.com/IHE/IT-Infrastructure/tree/master/ForPublication
 +
* First, delete all files in the directory (leftover from last year's work) except for the README. 
 +
** One by one, select each file (click on the file name), then select the delete icon to remove the file.
 +
* Next, you will add this year's copy of the Word docs (from previous step):
 +
** Select the "Upload Files" button
 +
** Select and upload all Word files that you prepared in the previous step.
 +
* On the bottom of the UI in the 'Commit Changes' section, add a comment that describes this step, e.g., "CurrentPublished version to start 2020 CP integration"
 +
* Select the "Commit changes" button
 +
 
 +
'''(3) Create a branch in the Publications repo in Github'''
 +
 
 +
This is where editors do their integration work...
 +
 
 +
* The IHE Publications repository in Github is here:  https://github.com/IHE/publications
 +
* Create a branch; give it a name e.g. CP-integration-2022
 +
 
 +
== EDITORS:  To Integrate CPs into TI Supps (Word, not HTML) using Github ==
 +
 
 +
'''(1) To prepare...'''
 +
*Refer to the Dashboard showing docs being published this year.  It identifies editors and reviewers for each document, plus the CPs that apply to each doc:  See the <b>Pub{{CURRENTYEAR}}</b> tab on the [https://docs.google.com/spreadsheets/d/1gdr_Y8xZBvbb326J4z67cqprxOexFgtkPj_VlD3rB9E/edit?usp=sharing ITI CP Tracking Spreadsheet]
 +
* Final Text CPs ready for integration are found:
 +
** On the IHE Google Drive in:  IHE Documents [https://drive.google.com/drive/folders/1hsevv-tLKB8iMrM1IsAvzGvSONyO2ag9 IHE Documents > IT_Infrastructure > TF_Maintenance > CPs > 3_FinalText]
 +
 
 +
'''(2) In Github, find the document that you are assigned to update'''
 +
* Get the Word version of the current published doc. You will find it on '''***GITHUB***''' at https://github.com/IHE/IT-Infrastructure/tree/master/ForPublication  (Note that these were retrieved from Mary's archive at [https://drive.google.com/drive/folders/1qJVFWjhzb_5JgxSDGGE8j-l4FpERyhsG IHE Documents>DocumentPublication>CurrentPublished>ITInfrastructure]
 +
* Select the document you want, then Download a local copy.
 +
* '''Do not''' change the file name.
 +
 
 +
'''(3) Make edits based on CPs to integrate'''
 +
# Turn on track changes in the Word document and proceed to make edits...
 +
# Use the [https://docs.google.com/spreadsheets/d/1gdr_Y8xZBvbb326J4z67cqprxOexFgtkPj_VlD3rB9E/edit?usp=sharing ITI CP TrackingSreadsheet] to find the individual CPs that apply to your Volume or TI:
 +
## The <b>Pub{{CURRENTYEAR}}</b> tab lists the CPs that affect each document and a link to find the CP.
 +
### Note that some CPs modify multiple documents
 +
### It may help to make a local copy of the spreadsheet so you can make notes as you progress
 +
#Start with oldest (Lowest number) CPs first
 +
#Open it
 +
#Scroll down in the CP to the first set of editor instructions.  Note that editor instructions are contained in a box prior to the edited text.  What they mean:
 +
##If the instructions are just flat text, that means it is copied from the TI or TF in order to help you find the position in the document to insert the change. “Normal” text in the CP is NOT a change to the Volume or TI.
 +
##If it is <u>'''bold and underlined'''</u>, that indicates text that should be inserted
 +
### To insert use “paste special” and insert “only unformatted text”. DO NOT INSERT FORMATTING STYLES FROM OTHER DOCUMENTS or it will add to the template list of styles and this is a major problem for publication.
 +
###If you need to re-apply bullets, use the format-painter to re-apply the bullets OR use the style-pulldown menu to find the pre-set style from the template.
 +
##If it is <s>'''bold and strike-out'''</s>, it means delete
 +
##If it is in a “box” it is instructions for you as the editor, don’t copy the “box” in!!!
 +
#Make the first change. Make sure to check whether the change needs to be made elsewhere in the Volume or TI! (e.g.  if the instructions say: Change all instances of XY to YZ)
 +
# When you make an edit due to the CP, add a Word comment that includes the CP number that the change came from.  This helps reviewers who will later confirm your changes.
 +
#Repeat steps 5-7… for each change within the CP until the CP is completely integrated into the Volume or TI
 +
#Make a note in your local copy of the spreadsheet that you completed integration of that CP
 +
#Rinse, repeat at step 4, using the next CP to be integrated
 +
 
 +
'''(4) Put your updated document back into Github'''
 +
*When all CPs for your Volume or TI are fully integrated, upload the updated to '''***GITHUB***:
 +
**Go here: https://github.com/IHE/IT-Infrastructure/tree/master/ForPublication
 +
**Select "Upload files", and upload the file you just edited (remember, you have not changed the file name) 
 +
**'''DO NOT COMMIT NOW'''
 +
**Add Comment listing CPs you integrated
 +
**Create a new branch and name it:  eg APPC-2021-CPintegration
 +
** Click "Propose changes"
 +
** Select Assignee (on the right) and pick the reviewer for your document
 +
** Click "Create pull request"
 +
** Now the Assignee gets an email via Github.  You will also see your pull request in https://github.com/IHE/IT-Infrastructure on the 'Pull requests' tab
 +
 
 +
'''(5) Notify the project manager of your accomplishment!'''
 +
*Send an email to Lynn Felhofer and let her know that your Volume and/or TI is ready for the reviewer to check that the CPs have been correctly integrated.  (She will follow up with the reviewer)
 +
 
 +
'''(6) Notes:'''
 +
*  In some cases, there is a sequence of editors, so one editor completes an integration first, and then passes it on to the next editor.  This happens when profiles move from TI to FT, or when a CP modifies multiple documents.  If this is the case, it will be noted on the Dashboard, and Lynn will inform the next editor.
 +
*  In the rare case that your CP has a diagram that is saved in a separate file (ie not integrated into the documentation, please put it on the FTP once the documentation and diagrams are final.  The diagrams are archived here: 
 +
** On the IHE FTP site in: /DocumentPublication/NonStandardDiagrams/ITI
 +
** (after June 2020) On the IHE Google Drive in:  [https://drive.google.com/drive/folders/1wCwyfWatwYfHUwPXpJ5tknoPGAqKXNg0 DocumentPublication > NonStandardDiagrams > ITI]
 +
 
 +
Caveats
 +
 
 +
*If CPs overlap, or if you find a conflict with a previous CP, try to solve it.  When in doubt, ask for help. (Cochairs should know who to reach out to.)
 +
*If there is a problem with figures that are impossible to update, or that you are unable to update, reach out to the cochairs for help as well
 +
*If the headers or “normal” text used to position the you so you can find where to insert changes within the TF is different than what you find in the TF – check the date when the CP was last updated. If the CP is significantly older (more than 1 year) than the TF, chances are the TF content has since changed and you do not need to change it back to what is in the CP.
 +
*If you run into any other problems… reach out to the co-chairs.
 +
 
 +
== REVIEWERS:  To check CPs integrated into TI Supps (Word, not HTML) using Github ==
 
   
 
   
−
'''Why:'''  Integrating CPs into Final Text volumes and TI supplements is a task requiring attention to detail.  It is beneficial to check the integration work prior to delivering updated documentation to the Documentation Specialist.  This provided a "second set of eyes" on the documentation, and may prevent a future CP.
+
'''Why:'''  Integrating CPs into Final Text volumes and TI supplements is a task requiring attention to detail.  It is beneficial for someone to check the integration work prior to delivering updated docs to the Documentation Specialist.  This provides a "second set of eyes" on the documentation updates, and may prevent a future CP.
  
 
'''When:'''  After CP integration is complete, before submitting a document for publication.
 
'''When:'''  After CP integration is complete, before submitting a document for publication.
Line 15: Line 99:
 
'''How:'''
 
'''How:'''
  
−
'''(1) Find the document you are assigned to verify'''
+
'''(1) In GitHub, find the document you are assigned to verify'''
−
* The editor doing the CP integration should be sending an email to indicate the document is 'ready' for you to verify
+
* After the editor did the CP integration, he/she uploaded the updated document into GitHub and then created a "Pull request" with you  (the reviewer) as an Assignee. 
−
* He/she should have put the document in ftp://ftp.ihe.net/IT_Infrastructure/CURRENTYEAR/Technical_Cmte/Workitems/Pre-Publication%20Drafts%20of%20TIs%20and%20TFs
+
* Then, GitHub sends an email to you to indicate the document is 'ready' for you to verify.
 +
* Pull request are found here:  https://github.com/IHE/IT-Infrastructure/pulls
 +
* Find your pull request on the list, and click on the entry to see the details.
 +
* Within the pull request, select the "Files changed" tab".  Download the document to make a local copy.
  
 
'''(2) Identify the CPs approved for Final Text'''
 
'''(2) Identify the CPs approved for Final Text'''
−
* Find the directory following this naming convention ftp://ftp.ihe.net/IT_Infrastructure/TF_Maintenance-CURRENTYEAR/CPs/3_FinalText/ eg. ftp://ftp.ihe.net/IT_Infrastructure/TF_Maintenance-2014/CPs/3_FinalText/
+
* Access the [https://docs.google.com/spreadsheets/d/1gdr_Y8xZBvbb326J4z67cqprxOexFgtkPj_VlD3rB9E/edit?usp=sharing ITI CP Tracking Spreadsheet]
−
* Open the excel file in that directory maintained by the CP manager
+
** The <b>Pub{{CURRENTYEAR}}</b> tab lists the CPs that affect each document
−
* The spreadsheet contains one row for each Final Text CP.  The columns in the spreadsheet are:
+
** The '''Approved CPs''' tab contains links to the CPs.  Final Text CPs ready for integration are found:
−
** CP number
+
** On the IHE Google Drive in: IHE Documents [https://drive.google.com/drive/folders/1hsevv-tLKB8iMrM1IsAvzGvSONyO2ag9 IHE Documents > IT_Infrastructure > TF_Maintenance > CPs > 3_FinalText]
−
** profile
+
* Download the CPs that affect the document you are verifying
−
** Vol/Supp affected
+
 
−
**Title
+
'''(3)''' (if applicable) '''Find a TI Supplement that will be integrated into Final Text'''
−
** Ballot
+
 
−
** File location
+
Sometimes, a TI Supplement is approved to be integrated into a Final Text Volume.  If this applies:
  
−
'''(3) Identify the Final Text CPs that affect the document you are verifying'''
+
* Go to the location where Mary stores currently published IHE framework documents:
−
* In the spreadsheet, examine the "Vol/Supp affected" column to identify the CPs you need.  Notice that some CPs affect more than one document
+
** On the IHE Google Drive in:  in [https://drive.google.com/drive/folders/1WTHmopm5TC0omqvC2TjIlzskrIF2cArh IHE Documents > DocumentPublication > CurrentPublished > ITInfrastructure]
 +
* Download a local copy of the Word document(s)
  
−
'''Verify the integration'''
+
'''(4) Verify the integration'''
−
* Open the document to verify and a CP affecting the document.
+
* Open the document you are verifying and a CP (or TI Suppl) affecting the document. 
 +
* Ensure that "Tracked changes" is set to "Final showing markup" so you can easily see the editor's updates.
 
* In the CP, the changes are included beneath the CP's rationale. Interpret the editor's instructions as follows:
 
* In the CP, the changes are included beneath the CP's rationale. Interpret the editor's instructions as follows:
 +
 
a.    Editors instructions are included in a 'box'.  This guides the editor to find the location in the document to make a change.
 
a.    Editors instructions are included in a 'box'.  This guides the editor to find the location in the document to make a change.
 +
 
b. If the text in the CP just flat text (regular font), that means it has been copied from the TI or TF in order to help you find the position in the document where the change occurs. “Regular font” text in the CP is NOT a change to the Volume or TI.
 
b. If the text in the CP just flat text (regular font), that means it has been copied from the TI or TF in order to help you find the position in the document where the change occurs. “Regular font” text in the CP is NOT a change to the Volume or TI.
−
c. If text is bold and underlined font, that indicates text that should be inserted
+
 
−
d. If text is bold and strike-out font, it means delete the text
+
c. If text is <u>'''bold and underlined'''</u> font, that indicates text that should be inserted (''Note:  a somewhat common integration mistake to watch for is when the editor adds the bold/underline text but forgets to remove the bold/underline font'')
 +
 
 +
d. If text is <s>'''bold and strike-out'''</s> font, it means delete the text
 +
 
 +
* Repeat until you have checked all CPs affecting the document you are verifying
 +
 
 +
'''(4a) If you find issue with the CP integration...''' else, go to (5)
 +
* (This can happen because an editor missed something in the CP, or perhaps interpreted the intended change differently than you did.)
 +
* Ensure "Track changes" is set to "On" in the document you are verifying.
 +
* Fix the text to the way you think the CP should be applied.
 +
* Save the updated document
 +
* Send an email to the document editor indicating that you have made a change; cc the CP Manager (Lynn).  The purpose of this email exchange is for the editor to review your change and come to resolution on any issues.
 +
'''(4b) Upload your updated document into the same branch...'''
 +
* In '''GITHUB''':  https://github.com/IHE/IT-Infrastructure
 +
* On the '''<>Code''' tab, find the grey box with the "Branch: XXXX", and select the branch for the document you are reviewing
 +
* Navigate to the '''ForPublication''' directory in the GitHub web UI
 +
* Use '''Upload file''' to upload your revised version of the doc you reviewed and corrected.
 +
* At this point you have added your changes to the same branch. You will then approve the branch
 +
 
 +
'''(5) Approve the branch  (You are finished with the review & have found no issues, or you have uploaded a revised doc to the same branch)
 +
* go to the Pull Request. You should see a green "Merge pull request" button on this web page. (This is the page you were directed to in emails)
 +
* Underneath the Merge pull request" button is a place to "Leave a comment". Please indicate as your comment the review that you did. Could be as simple as "Reviewed and found as Okay.", or "Reviewed and updated as needed."
 +
* Select the green "Merge pull request" button
 +
* Once the Merge is done, there will be a "Delete branch" button
 +
* Select the "Delete branch" button, this will cleanup and the pull request will be gone.
 +
 
 +
 
 +
'''(6) Finally, the CP Manager accept all changes will upload the document w/ CPs correctly edited to:
 +
*  (for committee archives)...
 +
*  (and notify Mary)...
 +
 
 +
== EDITORS:  To Integrate CPs into Final Text Volumes (HTML format) using Github ==
 +
 
 +
'''(1) To prepare...'''
 +
*Refer to the Dashboard showing docs being published this year.  It identifies editors and reviewers for each document, plus the CPs that apply to each doc:  See the <b>Pub{{CURRENTYEAR}}</b> tab on the [https://docs.google.com/spreadsheets/d/1gdr_Y8xZBvbb326J4z67cqprxOexFgtkPj_VlD3rB9E/edit?usp=sharing ITI CP Tracking Spreadsheet]
 +
* Final Text CPs ready for integration are found:
 +
** On the IHE Google Drive in:  IHE Documents [https://drive.google.com/drive/folders/1hsevv-tLKB8iMrM1IsAvzGvSONyO2ag9 IHE Documents > IT_Infrastructure > TF_Maintenance > CPs > 3_FinalText]
 +
 
 +
'''(2) In Github, find the files for the chapters (sections) that you are assigned to update'''
 +
* Get the HTML version of the current published Technical Framework. We will be working in a branch, not in Master.  You will find it on '''***GITHUB***''' at https://github.com/IHE/publications/tree/ITI-CP-Integration
 +
 
 +
'''(3) Make edits based on CPs to integrate'''  (Instructions assume use of Github's web UI)
 +
# In Github, navigate to the file affected by a CP, select the file name (eg. this link to [https://github.com/IHE/publications/blob/ITI-CP-Integration/ITI/TF/Volume1/ch-9.html ch-9.html] is the file for Vol 1 Sec 9 ATNA).
 +
# Select the 'edit' icon and proceed to make edits.  You are directly editing HTML to reflect the Word markup in the CP.
 +
# Use the [https://docs.google.com/spreadsheets/d/1gdr_Y8xZBvbb326J4z67cqprxOexFgtkPj_VlD3rB9E/edit?usp=sharing ITI CP TrackingSreadsheet] to find the individual CPs that apply to your Volume:
 +
## The <b>Pub{{CURRENTYEAR}}</b> tab lists the CPs that affect each document and a link to find the CP.
 +
### Note that some CPs modify multiple documents
 +
### It may help to make a local copy of the spreadsheet so you can make notes as you progress
 +
#Start with oldest (Lowest number) CPs first
 +
#Open it
 +
#Scroll down in the CP to the first set of editor instructions.  Note that editor instructions are contained in a box prior to the edited text.  What they mean:
 +
##If the instructions are just flat text, that means it is copied from the TI or TF in order to help you find the position in the document to insert the change. “Normal” text in the CP is NOT a change to the Volume or TI.
 +
##If it is <u>'''bold and underlined'''</u>, that indicates text that should be inserted
 +
##If it is <s>'''bold and strike-out'''</s>, it means delete
 +
##If it is in a “box” it is instructions for you as the editor, don’t copy the “box” in!!!
 +
#Make the first change. Make sure to check whether the change needs to be made elsewhere in the Volume or TI! (e.g.  if the instructions say: Change all instances of XY to YZ)
 +
#Repeat steps 5-7… for each change within the CP that affects the file you are editing.
 +
#Make a note in your local copy of the spreadsheet that you completed integration of that CP
 +
#Rinse, repeat at step 4, using the next CP to be integrated
 +
 
 +
'''(3.x) TBD...Editor looks at result of HTML edits...
 +
<i>*TBD... it would be good for the editor to be able to 'preview' the edits before passing on to review.  QUESTION:  Updates are not viewable in https://ihe.github.io/publications/ITI until after a commit to master, right?  What should we do??</i>
 +
 
 +
'''(4) When you finish your edits...'''
 +
*When all CPs for a chapter are fully integrated and ready for review...
 +
**'''DO NOT COMMIT NOW'''
 +
** Create a new branch and name it: eg Vol1-ATNA-2021-CPintegration
 +
** Add Comment listing CPs you integrated.  This helps reviewers who will later confirm your changes.
 +
** Click "Propose changes"
 +
** Select Assignee (on the right) and pick the reviewer for your document
 +
** Click "Create pull request"
 +
** Now the Assignee gets an email via Github.  You will also see your pull request in https://github.com/IHE/publications/pulls
 +
 
 +
'''(5) Notify the project manager of your accomplishment!'''
 +
*Send an email to Lynn Felhofer and let her know that your Volume and/or TI is ready for the reviewer to check that the CPs have been correctly integrated.  (She will follow up with the reviewer)
 +
 
 +
'''(6) Notes:'''
 +
*  In some cases, there is a sequence of editors, so one editor completes an integration first, and then passes it on to the next editor.  This happens when profiles move from TI to FT, or when a CP modifies multiple documents.  If this is the case, it will be noted on the Dashboard, and Lynn will inform the next editor.
 +
*  In the rare case that your CP has a diagram that is saved in a separate file (ie not integrated into the documentation, please put it on the FTP once the documentation and diagrams are final.  The diagrams are archived here: 
 +
** On the IHE FTP site in: /DocumentPublication/NonStandardDiagrams/ITI
 +
** (after June 2020) On the IHE Google Drive in:  [https://drive.google.com/drive/folders/1wCwyfWatwYfHUwPXpJ5tknoPGAqKXNg0 DocumentPublication > NonStandardDiagrams > ITI]
 +
 
 +
Caveats
 +
 
 +
*If CPs overlap, or if you find a conflict with a previous CP, try to solve it.  When in doubt, ask for help. (Cochairs should know who to reach out to.)
 +
*If there is a problem with figures that are impossible to update, or that you are unable to update, reach out to the cochairs for help as well
 +
*If the headers or “normal” text used to position the you so you can find where to insert changes within the TF is different than what you find in the TF – check the date when the CP was last updated. If the CP is significantly older (more than 1 year) than the TF, chances are the TF content has since changed and you do not need to change it back to what is in the CP.
 +
*If you run into any other problems… reach out to the co-chairs.
 +
 
 +
== REVIEWERS:  To check CPs integrated into Final Text Volumes (HTML format) using Github ==
 +
 +
'''Why:'''  Integrating CPs into Final Text volumes and TI supplements is a task requiring attention to detail.  It is beneficial for someone to check the integration work prior to delivering updated docs to the Documentation Specialist.  This provides a "second set of eyes" on the documentation updates, and may prevent a future CP.
 +
 
 +
'''When:'''  After CP integration is complete, before submitting a document for publication.
 +
 
 +
'''Who:'''  Ideally, someone other than the editor who did the integration.  Domain co-chairs assign this task to members of the Technical Committee.
 +
 
 +
'''How:'''
 +
 
 +
'''(1) In GitHub,...
 +
# tbd

Latest revision as of 10:30, 16 May 2022

CP ADMINISTRATOR: To prepare Github for CP integration into TI Supps (Word, not HTML)

(1) Get the Word documents for the Currently Published Final Text volumes and TI Supplements:

  • Go to the location where Mary stores currently published IHE framework documents:
  • Download a local copy of the Word document(s) that will be updated by CPs. Each of the file names will end with a version and a date, for example: IHE_ITI_Suppl_mCSD_Rev3-1_TI_2019-03-06.docx or IHE_ITI_TF_Rev16-0_Vol1_FT_2019-07-12.docx
  • Update the filenames to remove the date, eg IHE_ITI_Suppl_mCSD_Rev3-1_TI.docx or IHE_ITI_TF_Rev16-0_Vol1_FT.docx

(2) Upload the CurrentPublished Word documents into Gitub:

Note: These instructions assume the user is using the web UI for Github.

  • Go to: https://github.com/IHE/IT-Infrastructure/tree/master/ForPublication
  • First, delete all files in the directory (leftover from last year's work) except for the README.
    • One by one, select each file (click on the file name), then select the delete icon to remove the file.
  • Next, you will add this year's copy of the Word docs (from previous step):
    • Select the "Upload Files" button
    • Select and upload all Word files that you prepared in the previous step.
  • On the bottom of the UI in the 'Commit Changes' section, add a comment that describes this step, e.g., "CurrentPublished version to start 2020 CP integration"
  • Select the "Commit changes" button

(3) Create a branch in the Publications repo in Github

This is where editors do their integration work...

EDITORS: To Integrate CPs into TI Supps (Word, not HTML) using Github

(1) To prepare...

(2) In Github, find the document that you are assigned to update

(3) Make edits based on CPs to integrate

  1. Turn on track changes in the Word document and proceed to make edits...
  2. Use the ITI CP TrackingSreadsheet to find the individual CPs that apply to your Volume or TI:
    1. The Pub2024 tab lists the CPs that affect each document and a link to find the CP.
      1. Note that some CPs modify multiple documents
      2. It may help to make a local copy of the spreadsheet so you can make notes as you progress
  3. Start with oldest (Lowest number) CPs first
  4. Open it
  5. Scroll down in the CP to the first set of editor instructions. Note that editor instructions are contained in a box prior to the edited text. What they mean:
    1. If the instructions are just flat text, that means it is copied from the TI or TF in order to help you find the position in the document to insert the change. “Normal” text in the CP is NOT a change to the Volume or TI.
    2. If it is bold and underlined, that indicates text that should be inserted
      1. To insert use “paste special” and insert “only unformatted text”. DO NOT INSERT FORMATTING STYLES FROM OTHER DOCUMENTS or it will add to the template list of styles and this is a major problem for publication.
      2. If you need to re-apply bullets, use the format-painter to re-apply the bullets OR use the style-pulldown menu to find the pre-set style from the template.
    3. If it is bold and strike-out, it means delete
    4. If it is in a “box” it is instructions for you as the editor, don’t copy the “box” in!!!
  6. Make the first change. Make sure to check whether the change needs to be made elsewhere in the Volume or TI! (e.g. if the instructions say: Change all instances of XY to YZ)
  7. When you make an edit due to the CP, add a Word comment that includes the CP number that the change came from. This helps reviewers who will later confirm your changes.
  8. Repeat steps 5-7… for each change within the CP until the CP is completely integrated into the Volume or TI
  9. Make a note in your local copy of the spreadsheet that you completed integration of that CP
  10. Rinse, repeat at step 4, using the next CP to be integrated

(4) Put your updated document back into Github

  • When all CPs for your Volume or TI are fully integrated, upload the updated to ***GITHUB***:
    • Go here: https://github.com/IHE/IT-Infrastructure/tree/master/ForPublication
    • Select "Upload files", and upload the file you just edited (remember, you have not changed the file name)
    • DO NOT COMMIT NOW
    • Add Comment listing CPs you integrated
    • Create a new branch and name it: eg APPC-2021-CPintegration
    • Click "Propose changes"
    • Select Assignee (on the right) and pick the reviewer for your document
    • Click "Create pull request"
    • Now the Assignee gets an email via Github. You will also see your pull request in https://github.com/IHE/IT-Infrastructure on the 'Pull requests' tab

(5) Notify the project manager of your accomplishment!

  • Send an email to Lynn Felhofer and let her know that your Volume and/or TI is ready for the reviewer to check that the CPs have been correctly integrated. (She will follow up with the reviewer)

(6) Notes:

  • In some cases, there is a sequence of editors, so one editor completes an integration first, and then passes it on to the next editor. This happens when profiles move from TI to FT, or when a CP modifies multiple documents. If this is the case, it will be noted on the Dashboard, and Lynn will inform the next editor.
  • In the rare case that your CP has a diagram that is saved in a separate file (ie not integrated into the documentation, please put it on the FTP once the documentation and diagrams are final. The diagrams are archived here:

Caveats

  • If CPs overlap, or if you find a conflict with a previous CP, try to solve it. When in doubt, ask for help. (Cochairs should know who to reach out to.)
  • If there is a problem with figures that are impossible to update, or that you are unable to update, reach out to the cochairs for help as well
  • If the headers or “normal” text used to position the you so you can find where to insert changes within the TF is different than what you find in the TF – check the date when the CP was last updated. If the CP is significantly older (more than 1 year) than the TF, chances are the TF content has since changed and you do not need to change it back to what is in the CP.
  • If you run into any other problems… reach out to the co-chairs.

REVIEWERS: To check CPs integrated into TI Supps (Word, not HTML) using Github

Why: Integrating CPs into Final Text volumes and TI supplements is a task requiring attention to detail. It is beneficial for someone to check the integration work prior to delivering updated docs to the Documentation Specialist. This provides a "second set of eyes" on the documentation updates, and may prevent a future CP.

When: After CP integration is complete, before submitting a document for publication.

Who: Ideally, someone other than the editor who did the integration. Domain co-chairs assign this task to members of the Technical Committee.

How:

(1) In GitHub, find the document you are assigned to verify

  • After the editor did the CP integration, he/she uploaded the updated document into GitHub and then created a "Pull request" with you (the reviewer) as an Assignee.
  • Then, GitHub sends an email to you to indicate the document is 'ready' for you to verify.
  • Pull request are found here: https://github.com/IHE/IT-Infrastructure/pulls
  • Find your pull request on the list, and click on the entry to see the details.
  • Within the pull request, select the "Files changed" tab". Download the document to make a local copy.

(2) Identify the CPs approved for Final Text

(3) (if applicable) Find a TI Supplement that will be integrated into Final Text

Sometimes, a TI Supplement is approved to be integrated into a Final Text Volume. If this applies:

(4) Verify the integration

  • Open the document you are verifying and a CP (or TI Suppl) affecting the document.
  • Ensure that "Tracked changes" is set to "Final showing markup" so you can easily see the editor's updates.
  • In the CP, the changes are included beneath the CP's rationale. Interpret the editor's instructions as follows:

a. Editors instructions are included in a 'box'. This guides the editor to find the location in the document to make a change.

b. If the text in the CP just flat text (regular font), that means it has been copied from the TI or TF in order to help you find the position in the document where the change occurs. “Regular font” text in the CP is NOT a change to the Volume or TI.

c. If text is bold and underlined font, that indicates text that should be inserted (Note: a somewhat common integration mistake to watch for is when the editor adds the bold/underline text but forgets to remove the bold/underline font)

d. If text is bold and strike-out font, it means delete the text

  • Repeat until you have checked all CPs affecting the document you are verifying

(4a) If you find issue with the CP integration... else, go to (5)

  • (This can happen because an editor missed something in the CP, or perhaps interpreted the intended change differently than you did.)
  • Ensure "Track changes" is set to "On" in the document you are verifying.
  • Fix the text to the way you think the CP should be applied.
  • Save the updated document
  • Send an email to the document editor indicating that you have made a change; cc the CP Manager (Lynn). The purpose of this email exchange is for the editor to review your change and come to resolution on any issues.

(4b) Upload your updated document into the same branch...

  • In GITHUB: https://github.com/IHE/IT-Infrastructure
  • On the <>Code tab, find the grey box with the "Branch: XXXX", and select the branch for the document you are reviewing
  • Navigate to the ForPublication directory in the GitHub web UI
  • Use Upload file to upload your revised version of the doc you reviewed and corrected.
  • At this point you have added your changes to the same branch. You will then approve the branch

(5) Approve the branch (You are finished with the review & have found no issues, or you have uploaded a revised doc to the same branch)

  • go to the Pull Request. You should see a green "Merge pull request" button on this web page. (This is the page you were directed to in emails)
  • Underneath the Merge pull request" button is a place to "Leave a comment". Please indicate as your comment the review that you did. Could be as simple as "Reviewed and found as Okay.", or "Reviewed and updated as needed."
  • Select the green "Merge pull request" button
  • Once the Merge is done, there will be a "Delete branch" button
  • Select the "Delete branch" button, this will cleanup and the pull request will be gone.


(6) Finally, the CP Manager accept all changes will upload the document w/ CPs correctly edited to:

  • (for committee archives)...
  • (and notify Mary)...

EDITORS: To Integrate CPs into Final Text Volumes (HTML format) using Github

(1) To prepare...

(2) In Github, find the files for the chapters (sections) that you are assigned to update

(3) Make edits based on CPs to integrate (Instructions assume use of Github's web UI)

  1. In Github, navigate to the file affected by a CP, select the file name (eg. this link to ch-9.html is the file for Vol 1 Sec 9 ATNA).
  2. Select the 'edit' icon and proceed to make edits. You are directly editing HTML to reflect the Word markup in the CP.
  3. Use the ITI CP TrackingSreadsheet to find the individual CPs that apply to your Volume:
    1. The Pub2024 tab lists the CPs that affect each document and a link to find the CP.
      1. Note that some CPs modify multiple documents
      2. It may help to make a local copy of the spreadsheet so you can make notes as you progress
  4. Start with oldest (Lowest number) CPs first
  5. Open it
  6. Scroll down in the CP to the first set of editor instructions. Note that editor instructions are contained in a box prior to the edited text. What they mean:
    1. If the instructions are just flat text, that means it is copied from the TI or TF in order to help you find the position in the document to insert the change. “Normal” text in the CP is NOT a change to the Volume or TI.
    2. If it is bold and underlined, that indicates text that should be inserted
    3. If it is bold and strike-out, it means delete
    4. If it is in a “box” it is instructions for you as the editor, don’t copy the “box” in!!!
  7. Make the first change. Make sure to check whether the change needs to be made elsewhere in the Volume or TI! (e.g. if the instructions say: Change all instances of XY to YZ)
  8. Repeat steps 5-7… for each change within the CP that affects the file you are editing.
  9. Make a note in your local copy of the spreadsheet that you completed integration of that CP
  10. Rinse, repeat at step 4, using the next CP to be integrated

(3.x) TBD...Editor looks at result of HTML edits... *TBD... it would be good for the editor to be able to 'preview' the edits before passing on to review. QUESTION: Updates are not viewable in https://ihe.github.io/publications/ITI until after a commit to master, right? What should we do??

(4) When you finish your edits...

  • When all CPs for a chapter are fully integrated and ready for review...
    • DO NOT COMMIT NOW
    • Create a new branch and name it: eg Vol1-ATNA-2021-CPintegration
    • Add Comment listing CPs you integrated. This helps reviewers who will later confirm your changes.
    • Click "Propose changes"
    • Select Assignee (on the right) and pick the reviewer for your document
    • Click "Create pull request"
    • Now the Assignee gets an email via Github. You will also see your pull request in https://github.com/IHE/publications/pulls

(5) Notify the project manager of your accomplishment!

  • Send an email to Lynn Felhofer and let her know that your Volume and/or TI is ready for the reviewer to check that the CPs have been correctly integrated. (She will follow up with the reviewer)

(6) Notes:

  • In some cases, there is a sequence of editors, so one editor completes an integration first, and then passes it on to the next editor. This happens when profiles move from TI to FT, or when a CP modifies multiple documents. If this is the case, it will be noted on the Dashboard, and Lynn will inform the next editor.
  • In the rare case that your CP has a diagram that is saved in a separate file (ie not integrated into the documentation, please put it on the FTP once the documentation and diagrams are final. The diagrams are archived here:

Caveats

  • If CPs overlap, or if you find a conflict with a previous CP, try to solve it. When in doubt, ask for help. (Cochairs should know who to reach out to.)
  • If there is a problem with figures that are impossible to update, or that you are unable to update, reach out to the cochairs for help as well
  • If the headers or “normal” text used to position the you so you can find where to insert changes within the TF is different than what you find in the TF – check the date when the CP was last updated. If the CP is significantly older (more than 1 year) than the TF, chances are the TF content has since changed and you do not need to change it back to what is in the CP.
  • If you run into any other problems… reach out to the co-chairs.

REVIEWERS: To check CPs integrated into Final Text Volumes (HTML format) using Github

Why: Integrating CPs into Final Text volumes and TI supplements is a task requiring attention to detail. It is beneficial for someone to check the integration work prior to delivering updated docs to the Documentation Specialist. This provides a "second set of eyes" on the documentation updates, and may prevent a future CP.

When: After CP integration is complete, before submitting a document for publication.

Who: Ideally, someone other than the editor who did the integration. Domain co-chairs assign this task to members of the Technical Committee.

How:

(1) In GitHub,...

  1. tbd
Retrieved from "http://wiki.ihe.net/index.php?title=ITI_CP_Integration_Process&oldid=128320"