Workflow

[m-clark]

We have that Yihui stuff and thanks for pushing that up. However that repo is ancient with few updates, and didn't have some things typical of modern bookdown/r/qmd (like any yaml, css), so I'm looking at recent CRC books like this, and more are at bookdown.org. I'm trying to assess a proper workflow to satisfy pdf (ffs) vs. electronic. It might be worth it to message Yihui directly for advice or something. The last thing I want to do is spend 50% of the time on the book screwing around with latex issues for the print version.

[saberry]

Ah...hadn't even paid attention time since update on those. Seems like that Modern Dive has a pretty easy workflow to replicate.

[m-clark]

Returning to this now that we've made a bit of progress. Here is a proposal:

• Create branch with name of content for chapters, possibly subchapters within (not numbers)
• The only thing to merge to main from a branch will be the qmd file
  • Alter .gitignore for that branch as needed if it helps to keep potential commit clutter low (but do not merge the .gitignore to main)
  • Alter .quarto for that branch or only render that file, but again, do not merge it
  • Alter scss similarly, but actual changes should be made on main (or maybe we should create a style branch for quarto and css changes)
• Commit daily if both of us are working on the same chapter
  • Commits should reflect a working html/pdf render
• When chapter is 'ready', create a PR
  • Other person will review and suggest changes
  • 'ready' could mean a working outline of all content + various (an earlier merge will allow book to take shape earlier)
  • Merge can be made at that point after changes
  • Work can continue on that branch, but consider merging main back into branch if it's been some time and/or other merges to main have been made
• Post PR
  • After a PR has been merged, you may want to discard changes/delete the non-merged files (e..g. _book) to avoid future entanglements when merging main back into it at a later date (can also use stash approach, see below)
  • If it is the first merge for a chapter, update at least the quarto.yml on main to reflect it in the order
  • Render the book on main

[m-clark]

One way to update config changes that you may ultimately want to keep while working in a chapter branch is to do the following. Let's say while working on chapter x you add some css or want to add something to the setup.R script.

1. Save and Stash your current chapter file
2. Switch to main, commit/push changes to quarto.yml, css etc.
3. Switch back to chapter branch
4. Pop stash

In this way, the main only has config/total book changes, and chapters can ultimately merge only those relevant chapter.qmd files.

[m-clark]

@saberry In an effort to further keep things in line on main vs. chapter development, I'm going to suggest that each chapter have its own folder. This folder would include functions used, references specific to that chapter, and possibly chapter specific objects (e.g. model pickle/RData) the only thing outside of the folder would be the chapter.qmd. I'm trying to avoid issues where slight changes might overwrite an object, when switching between branches/main, and make it easier to merge one branch into another if needed (e.g. I'll probably be merging lm into estimation regularly, you may need lm into lm extensions, etc.). I also think this might be helpful, e.g. to more easily find functions/references/data. At the end we can do a bigger reorg/cleanup, which we're going to do anyway.