How should we handle changes that need to be reflected on the printed cards?

[jameshupp]

Question originally asked by @jenniferthibault in #27:

suggestions for a good way to make changes on the site & the printed cards, without losing track? Keeping the print cards up to date is definitely important, but it takes ~20 min each time we need to re-export and upload, so minimizing the number of times we do that would be 👍

My initial responses (with a few adjustments from the original):

• Apply a tag like, say, card copy to any PRs that include language updates that affect the cards.
• Specify in each PR exactly which methods are affected. The file changes themselves will show it, but this way it may be easier to see when multiple PRs affect the same method. A small language change on one method will usually not be worth re-exporting, but six or seven small changes on the same method might be.
• Establish a regular update schedule for non-urgent changes to the cards. What's a good frequency?
• Make sure 18F staff know how to find the INDD files so other designers can address if/when such issues arise.

What do people think? Other ideas? Problems with the above?

[jenniferthibault]

Definitely think that a tag would be helpful. Maybe copy edit though to be more specific? That could mean any type of content on the card has been edited.

Today, I used the "Files changed" feature within the PR to see which methods were changed, but bulleting them out in the PR changes would be very helpful to use as a cross-check.

On frequency, how do we feel about weekly to start, then moving to every two weeks if edits arise? Flexibility for testing periods that need the most recent cards, or for glaring errors that should be corrected immediately. I could set a calendar reminder for that every Friday.

After each export, I could move a copy to a location on Google Drive for project staff to access if there's an emergency. I would however like to avoid the practice of PR-ing the design files, since there is no commit tracking or version control built in, and in a large document, it can be impossible to track what was changed.

Also, whatever we decide would be really good to add to contributing! This conversation has some good examples of projects that frame feedback on visual design elements. 18F/open-source-guide#15

[jameshupp]

Weekly seems to be frequent enough at this point. Today we got an ask offline about a copy discrepancy that is already accurate, technically, but just reads a little odd. We got one a couple days ago that is a question of accuracy, but it's minor and doesn't affect how people would use the card. We'll see if we get more urgent issues or requests, but for now, I don't see any reason to go more regularly.

I see what you mean about PRing the files. Is there a better way? I know we've done it via PR and via direct update to the staging branch. Doesn't seem like it makes much difference if we're not seeing diffs.

[colinpmacarthur]

@jenniferthibault and @jameshupp: Have we come to a conclusion on the process for keeping the files updated? How about the process James suggested, but with a couple minor additions? Additions in italics.

• Apply the "card copy" tag to any PRs that include language updates that affect the printed version of the cards.
• Changes to methods cards copy start as PRs to the "staging" branch. After review, they're merged into staging. Specify in each PR exactly which methods are affected. The file changes themselves will show it, but this way it may be easier to see when multiple PRs affect the same method. A small language change on one method will usually not be worth re-exporting, but six or seven small changes on the same method might be.
• *@jenniferthibault updates the printed versions of the methods card to match the staging branch every Friday. She commits the updated design files directly to the staging branch. She then opens a PR to merge the staging branch into the master branch (our production branch). Someone else looks over and merges into production. Then we follow the nice open source practice of merging into production at the end of every sprint. 👍 *
• Make sure 18F staff know how to find the INDD files so other designers can address if/when such issues arise. When Jen updates the design files, she puts them in a folder within the Google Drive folder for the methods cards.

Thoughts?

[jenniferthibault]

Works for me! Thanks for the great clarifications @colinpmacarthur

[colinpmacarthur]

Should we leave issues open until they are integrated into the final set of cards? Or should Jen just compare staging and master when deciding what changes to me? @jenniferthibault @jameshupp?

[jameshupp]

I'd leave the issue open until it's merged into the cards. The cards are a set of files to be changed in the repo and I think our process is not to close an issue until we've made the changes in the repo that respond to that issue.

[jenniferthibault]

Last clarification: the issue should be closed when the change has been made on staging? Or when staging with that issue is merged to production?

[jameshupp]

Interesting question. I'm inclined to say staging.

The issues we see here are likely to be substantive, whether about design, code, or content. The merge from staging to master will either work seamlessly and be a standard step for all the changes we've made to staging (as Colin says, at the end of every sprint), or it will fail a test. If it fails a test, though, the problem has nothing to do with whether we've addressed the substantive issue.

[jenniferthibault]

Sounds right to me. I also like that it will show we're addressing the issue earlier—as long as we link to the staging PR or commit when we close the issue.

[jameshupp]

Yeah, we should always include something to the effect of "Addresses #[issue number]" in the PR notes. Anyone who looks at the issue can then see the PR and what its status is.

[colinpmacarthur]

Great! In conclusion, it sounds like our process is:

When someone opens an issue suggesting copy edits:

1. The "Github issue manager of the week" labels it "copy edit" and facilitates conversation about it.
2. If we decide to change the copy, someone opens a PR to the staging branch with the change. She labels that PR "copy edit" and says "Addresses #[issue number]" in the comments. Leave the original issue open.
3. Others review the PR and merge it into staging.
4. Every Friday, @jenniferthibault
   • makes all the copy changes found in outstanding issues labeled "copy edit" to the design files
   • commits the new files directly (without a PR) to the staging branch
   • opens a PR to merge staging into master (our production branch)
   • closes the open issues labeled "copy edit" (that have beed addressed by the changes in the open PR)
5. After Jen submits her PR on Friday, another member of the team looks it over and merges it to master.

Sound right @jenniferthibault and @jameshupp? If so, should we put this in the wiki, @jameshupp?

[jameshupp]

👍 and 👍

[jenniferthibault]

What James said :)

[colinpmacarthur]

Fantastic! @jameshupp, why don't we leave the issue open until you add the process to the wiki? Close it when the process is documented there?

[colinpmacarthur]

@jameshupp: Is this ready to be closed?

[jameshupp]

Yes!