[FR] Add update_template() for existing article drafts

[cderv]

Problem

rmarkdown::draft() creates a new article directory from an rticles skeleton, but it cannot update an existing draft. When a bundled publisher template changes, users currently have to create a fresh draft and manually determine which class files and runtime assets should be copied, which obsolete files may be removed, and which YAML fields require attention.

This came up in #613 / #608 while updating LIPIcs from lipics-v2019.cls to lipics-v2021.cls. Backward compatibility lets an old draft continue to render, but rticles has no safe, actionable migration path beyond a warning.

This is related to, but distinct from:

• Pinning tex template version ? (Self-contained mode ?) #359, which discusses copying/pinning a Pandoc template for reproducibility;
• Improve LaTeX template update #529, which discusses how rticles maintainers update and modularize bundled Pandoc templates.

This proposal concerns package-managed files already copied into a user's article directory.

Minimal API

update_template(
  template,
  path = ".",
  dry_run = TRUE,
  remove_obsolete = FALSE
)

• template: an rticles template name, initially only "lipics".
• path: an existing article directory.
• dry_run: when TRUE (the default), compute and display the migration plan without changing files.
• remove_obsolete: when TRUE, allow manifest-declared obsolete files to be removed after their replacement is present. This should have no effect during a dry run and should default to FALSE.

The function should invisibly return a structured plan with at least path, action, status, and reason. Expected actions/statuses include add, replace, remove, manual, skip, and conflict, so callers and tests do not need to parse console text.

Example:

update_template("lipics", "my-article")
update_template("lipics", "my-article", dry_run = FALSE)
update_template(
  "lipics",
  "my-article",
  dry_run = FALSE,
  remove_obsolete = TRUE
)

Safety rules

The helper should be conservative and non-interactive:

1. Never rewrite the article .Rmd, YAML metadata, bibliography, or other user-authored content. Report those as manual migration steps.
2. Add a managed file when it is absent.
3. Replace a managed file only when its checksum matches a package-known historical version. If the checksum is unknown, report a conflict and leave the file unchanged.
4. Never remove a file unless it is declared obsolete by the manifest, its replacement is present, and remove_obsolete = TRUE was supplied explicitly.
5. Copy resources from the installed rticles package and use atomic file replacement where practical.
6. Do not infer that a project was updated merely because old and current files coexist; rmarkdown::draft() creates a new directory and does not update an existing one.

A first implementation does not need interactive conflict resolution, arbitrary three-way merging, or automatic YAML rewriting.

Template migration manifest

Keep migration policy beside the template rather than hard-coding it in update_template(), for example:

inst/rmarkdown/templates/lipics/migration.yaml

A minimal schema could be:

target: v2021.1.3

managed_files:
  - path: lipics-v2021.cls
    source: skeleton/lipics-v2021.cls
    add_if_missing: true

  - path: cc-by.pdf
    source: skeleton/cc-by.pdf
    replace_known_versions: true

  - path: lipics-logo-bw.pdf
    source: skeleton/lipics-logo-bw.pdf
    replace_known_versions: true

  - path: orcid.pdf
    source: skeleton/orcid.pdf
    replace_known_versions: true

obsolete_files:
  - path: lipics-v2019.cls
    replacement: lipics-v2021.cls
    removal: explicit

manual_steps:
  - Review the current skeleton YAML metadata and migrate fields as needed.
  - Review the current citation and bibliography guidance.

The implemented schema should record SHA-256 values for known historical package-managed files and current sources. The illustrative replace_known_versions field above may instead be represented by an explicit list of known hashes. Checksums should be derived from tagged publisher resources or rticles history and covered by tests.

The LIPIcs bibliography and .Rmd skeleton must not be managed automatically because users are expected to edit them.

LIPIcs behavior

For an untouched legacy draft containing only lipics-v2019.cls, the dry-run plan should propose adding the current class and refreshing recognized publisher runtime PDFs, while reporting YAML review as manual. Applying the plan should leave the old class in place unless remove_obsolete = TRUE is explicitly requested.

If both class files are present, the plan should report that the current rticles template selects lipics-v2021.cls and that lipics-v2019.cls is removable. It should not claim that rmarkdown::draft() performed the update.

If a managed asset has an unknown checksum, the plan should report a conflict and preserve it.

Acceptance criteria

• update_template("lipics", path) produces a deterministic dry-run plan and makes no changes.
• dry_run = FALSE adds missing managed resources and replaces only recognized historical versions.
• User-authored or checksum-unknown files are never overwritten.
• Obsolete files are removed only with remove_obsolete = TRUE and only after verifying the replacement.
• The returned plan is testable independently of printed messages.
• Unit tests cover legacy-only, current-only, both-class, unknown-checksum, dry-run, apply, and explicit-removal cases.
• Documentation explains that rmarkdown::draft() creates new scaffolds rather than updating existing drafts.

The initial implementation may support only LIPIcs; generalizing to other templates should require adding manifests rather than format-specific branches to the updater.