Add documentation on updating FTOL

docs/updating.md

@@ -0,0 +1,115 @@
+# Updating FTOL
+
+## Semantic versioning scheme
+
+FTOL uses semantic versioning as follows:
+
+- Third digit (0.0.1): change to tree but using same GenBank version as before
+- Second digit (0.1.0): new GenBank version
+- First digit (1.0.0): breaking change in format
+
+## Workflow to update FTOL
+
+1: Move `scratch` (raw genbank download) to NAS (can do this as soon as GenBank download is finished):
+
+nittalab server:
+
+```
+mv scratch /mnt/jnitta/project_data/ftol_genbank_raw/gb_release_253
+```
+
+(append GenBank version number, here `_253`).
+
+2: Run `R/comp_ftol_ages.r` to make sure age of nodes has not changed dramatically.
+
+3: Update Change Log in FigShare README (`reports/input_data_readme/input_data_readme.Rmd`) and FTOL data README (`reports/ftol_data_readme/ftol_data_readme.Rmd`) with most recent GenBank release number:
+
+```
+CHANGE LOG
+
+2023-02-16
+
+- Update to GenBank release 253
+```
+
+4: Run `bash run.sh` to build READMEs
+
+5: Download (via SFTP or rsync) `restez_sql_db_archive` (`_targets/user/data_raw/restez_sql_db.tar.gz`), `taxdmp.zip` (`_targets/user/data_raw/taxdmp.zip`), and `README.genbank` (`_targets/user/data_raw/restez/README.genbank`) to local Desktop.
+
+6: Download FigShare README (`_targets/user/results/input_data_readme.txt`) to local Desktop, rename as `README.txt`.
+
+7: Delete old README and `restez_sql_db.tar.gz` on FigShare, upload new `README.txt`, `taxdmp.zip`, `README.genbank`, and `restez_sql_db.tar.gz` (don't need to update `ref_aln.tar.gz` unless `prep_ref_seqs_plan.R` has been run).
+
+8: Make any final code commits in `ftol` repo
+
+**DO NOT commit changes in `ftol_data` manually.**
+
+9: Run `r/snapshot_ftol_data.R` in ftol container (interactive is recommended to account for checks). This will commit and push the new data files to https://github.com/fernphy/ftol_data
+
+```bash
+docker run --rm -v ${PWD}:/wd -w /wd -dt --user root joelnitta/ftol:latest
+```
+
+**DO NOT release new version of `ftol_data` manually.**
+
+10: Locally, pull `ftol_data`. Then, update the release version and notes in `release.R` in the `ftol_data` project and commit ("bump ver"), and run `release.R` to release the new version (**Requires `gh` CLI**).
+
+```
+# Specify version and release notes
+new_ver <- "v1.4.0"
+notes <- paste(
+  "Built with DNA sequences in [GenBank](https://ftp.ncbi.nlm.nih.gov/genbank/) release 253 (cutoff date 2022-12-15)"
+)
+```
+
+then run `Rscript release.R`
+
+11: Locally, change the data version in `ft_data_ver.R` of `ftolr` (https://github.com/fernphy/ftolr):
+
+```r
+ft_data_ver <- function(what = "ftol") {
+  assertthat::assert_that(
+    assertthat::is.string(what),
+    msg = "'what' must be a character vector of length 1")
+  switch(
+    what,
+    ftol = "1.4.0", # <-- THIS (must match new release number)
+    gb = "253", # <-- THIS
+    cutoff = "2022-12-15", # <-- and THIS
+    "'what' must be one of 'ftol', 'gb', or 'cutoff'"
+  )
+}
+```
+
+12: Run `data-raw/import_data.R` in `ftolr`, commit changes.
+
+**DO NOT release new version of `ftolr` manually.**
+
+13: Update release notes in `inst/release.R` in `ftolr` and run in interactive mode to release new version.
+
+14: Update ftol tree visualization (https://github.com/fernphy/ftol_vis)
+
+  - Install new ftolr with renv: `renv::install("fernphy/ftolr")` in `ftol_vis`
+  - Run `targets::tar_make()` (may need to manually empty targets cache first with `targets::tar_destroy("meta")` if new `ftolr` version is not picked up)
+
+14: Update shiny app (https://github.com/fernphy/ftol_shiny)
+
+  - Install new ftolr with renv: `renv::install("fernphy/ftolr")`, take renv snapshot and commit
+  - Check that it works: `shiny::runApp("ftol_explorer")`
+  - Deploy: `rsconnect::deployApp("ftol_explorer")`
+
+16: Update website (https://github.com/fernphy/fernphy.github.io)
+
+  - Install new ftolr with renv: `renv::install("fernphy/ftolr")`
+
+  - Downloads section: copy text from the old "current" version (be sure to update and check link).
+
+  - ![](/assets/images/2023-02-16-13-18-01.png)
+
+  - Update news
+
+  - Run `quarto render` to build all pages (`quarto preview` will only build those that have changes to the source code, so will miss changes only generated by updating `ftolr`).
+
+  - Push and website will be built by GH actions
+
+17: Post on mastodon!