Difference between revisions of "ITI CP Integration Process"

Revision as of 13:47, 10 May 2019

EDITORS: To Integrate CPs using Github (NEW process for 2019)

To prepare, refer to the Dashboard showing docs being published this year. It identifies editors and reviewers for each document:. See the Pub2024 tab on the ITI CP Tracking Spreadsheet (1) Find the document you are assigned to verify

Get the Word version of the current published doc. You will find it on ***GITHUB*** at https://github.com/IHE/IT-Infrastructure/tree/master/Docs_Update_by_CPs (Note that these were retrieved from Mary's archive at ftp://ftp.ihe.net/DocumentPublication/CurrentPublished/ITInfrastructure/)
Select the document you want, then Download a local copy.
Do not change the file name.

(2) Make edits based on CPs to integrate

Turn on track changes in the Word document and proceed to make edits...
Use the ITI CP TrackingSreadsheet to find the individual CPs that apply to your Volume or TI:

- The Pub2024 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 bold and underlined, 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 ~~bold and strike-out~~, 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 7-9… 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
Review the affected profiles' wiki pages for potential impact of the CP and update the wiki page if needed.
Rinse, repeat at step 5, using the next CP to be integrated

(3) 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/Docs_Update_by_CPs
- 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 DEN-2019-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

(4) 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 and co-chairs).

** Note: 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: ftp://ftp.ihe.net/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 integrated CPs using Github (NEW process for 2019)

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) Find the document you are assigned to verify

The editor who did the CP integration upload the updated document into Gitub and then create a "Pull request" with you (the reviewer) as an Assignee. Then, Github will send an email to you to indicate the document is 'ready' for you to verify

(2) Identify the CPs approved for Final Text

Access the [https://docs.google.com/spreadsheets/d/1gdr_Y8xZBvbb326J4z67cqprxOexFgtkPj_VlD3rB9E/edit?usp=sharing CP status ** ** The Pub2019 tab lists the CPs that affect each document
- Find links to each CP on the Approved CPs tab
  - Note that some CPs modify multiple documents

The spreadsheet contains one row for each Final Text CP. The columns in the spreadsheet are:
- Year integrated
- CP number
- profile
- Doc affected
- Title
- Ballot
- File location on ftp site

(3) Identify the Final Text CPs that affect the document you are verifying

In the spreadsheet, examine the "Vol/Supp affected" column to identify the CPs you need. Notice that some CPs affect more than one document

(4) Verify the integration

In ***GITHUB*** https://github.com/IHE/IT-Infrastructure, find the "Pull requests" tab and select the entry for your Pull request.
Find the updated document on the "Files changed" tab
Click on the like to download the document locally.
Review it.
- TO APPROVE W/ NO CHANGES:
  - Select the "Review changes" buttonAdd a comment, then Merge Pull Request

- IF THE REVIEWER FINDS a change
Merge Pull Request
- Make the edit to fix the problem
- Go to IT-Infrastructure/Doc_Updated_by_CPs
- Find the Branch name in the Pull Request
- Upload the updated file
- add a comment,
- Commit changes into the existing branch (do not create a new branch)
- Merge Pull Request
- Confirm

Open the document to verify and a CP 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

(5) Repeat Step (4)

...until you have checked all CPs affecting the document you are verifying

(5a) Extra credit (nice, but not a required step)

It is also beneficial to check to ensure there are not changes in the document that were *not* from a CP. If you notice an unexpected update that shows up in Change Tracking, you may inquire with the editor about the source of the change.

(6) If you find no errors in CP integration...

Send an email to the CP Manager (Lynn) and the document editor indicating that you are done and that the integration was flawless.

(7) If you find an error in CP integration...

(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 with a new name; append your initials to the existing file name, eg ITI_TF_Vol_2a_201xmmdd_draft_<yourinitials>.doc
Upload the updated document to the ftp site in the same directory where you got it from: ftp://ftp.ihe.net/IT_Infrastructure/TF_Maintenance/PrePublication_TFDocsUpdatedByCPs/
Send an email to the CP Manager (Lynn) and the document editor indicating that you have made a change

(7a) The editor will then...

Check your update and resolve any associated issues.
- If you make additional edits, upload the new version back to: ftp://ftp.ihe.net/IT_Infrastructure/TF_Maintenance/PrePublication_TFDocsUpdatedByCPs/
Email the ITI Tech Committee co-chairs & CP Manager to indicate that the CP integration is complete and the document is uploaded & ready to be submitted to Mary

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

ftp://ftp.ihe.net/IT_Infrastructure/TF_Maintenance/PrePublication_TFDocsUpdatedByCPs/ChangesReviewedAndChangesAccepted/ (for committee archives)
ftp://ftp.ihe.net/IT_Infrastructure/TF_Maintenance/PrePublication_TFDocsUpdatedByCPs/ChangesReviewedAndChangesAccepted/ (and notify Mary)

(legacy process used 2018 and earlier) EDITORS: To Integrate CPs using the IHE FTP site

Refer to the Dashboard showing docs being published this year. It identifies editors and reviewers for each document:. See the "Pub2024" tab on : https://docs.google.com/spreadsheets/d/1gdr_Y8xZBvbb326J4z67cqprxOexFgtkPj_VlD3rB9E/edit?usp=sharing
The most important task is to start editing the right document. To get the document that you will edit...
1. Get the final text Word document from last year. You will find it at ftp://ftp.ihe.net/DocumentPublication/CurrentPublished/ITInfrastructure
2. In some cases, there is a sequence of editors (noted on the Dashboard), 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
Turn on track changes in the Word document.
Access the CP status spreadsheet to find the CPs that apply to your Volume or TI:
1. The Pub2018 tab lists the CPs that affect each document
2. Find links to each CP on the Approved CPs tab
  1. Note that some CPs modify multiple documents
3. 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:
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 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!!!
Make the first change. Make sure to check if the change needs to be made elsewhere in the Volume or TI! (e.g. 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 7-9… 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
Review the affected profiles' wiki pages for potential impact of the CP and update the wiki page if needed.
Rinse, repeat from step 5
When all CPs for your Volume or TI are fully integrated, upload the updated volume/TI to ftp://ftp.ihe.net/IT_Infrastructure/TF_Maintenance/PrePublication_TFDocsUpdatedByCPs/2018-June-updates/
Send your updated spreadsheet 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
1. cc co-chairs Mauro and Elliot on this email
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. They go here: ftp://ftp.ihe.net/DocumentPublication/NonStandardDiagrams/ITI/

Caveats:

If CPs overlap, or conflict with a previous CP, try to solve it or 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 cochairs.

(legacy process used 2018 and earlier) REVIEWERS: To check integrated CPs