Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

[FR] Add update_template() for existing article drafts

Aperta
  • Qualcosa non va?
#614 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
35/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
latex, r
Ambito
tooling

Direzione di ricerca

Inizia esaminando come rmarkdown::draft() gestisce lo scheletro LIPIcs e usa inst/rmarkdown/templates/lipics/migration.yaml come punto di ingresso per la policy di migrazione. Definisci il piano deterministico e il comportamento di sicurezza relativo a quel manifest, quindi aggiungi test per i casi elencati di legacy, current, checksum, dry-run, apply e rimozione. Il lavoro è completato quando cambiano solo i file gestiti riconosciuti, le rimozioni esplicite sono protette e i contenuti creati dall’utente vengono segnalati per la revisione manuale.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

feature

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:

  • #359, which discusses copying/pinning a Pandoc template for reproducibility;
  • #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.

Lingua principale
TeX
Stelle
1.5k
Fork
516
Nessuna PR unita negli ultimi 30g

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di rstudio/rticles

Tutte le issue di rstudio/rticles

Issue simili

Altre issue su DevTools

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.