Record what an update follows and the installed commit in `.quarto-source.yml`

Open
#1,178 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
55/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
rust, yaml
Domain
cli

Research direction

Start by finding the code that reads and writes .quarto-source.yml records and the schema for version 1; the issue does not name specific files or tests. Check how install sources determine the tracking mode and commit, including @<sha> installs. Done means records can include optional track and commit keys while existing records without them remain accepted.

Written by the indexing model from the issue text.

Description

Description
Context

The record has source, kind, and an optional ref.
ref is what the user typed, not what was installed.
A plain owner/repo installs the head of the default branch.
The record doesn't say which commit that was, nor whether a later update should follow the branch or the latest release.
A future q2 update can't tell whether the branch has moved.

Other tools need the same two facts.
The development version of Quarto Wizard keeps them for now in its own quarto-wizard: block, and would move to keys that q2 defines.

Proposal

Add two optional keys to schema version 1 of the record:

version: 1
source: acme/demo
kind: github
track: branch   # tag | branch: what an update follows
commit: 3f2a9c1e5b7d4a60918c2d4e6f8a0b1c3d5e7f90   # full SHA of what is installed
files:
  _extension.yml: <sha256>
  filter.lua: <sha256>

Both are optional, so the readers of today still accept the file.
q2 writes commit when it knows it, for example for an @<sha> install, and track from how the user installed.

Why

What an update follows and what is installed both describe the install, and the record is where q2 keeps that.

Benefits

q2 update can tell from the record alone whether a branch has moved.
A committed record shows exactly which commit a project uses.
Other tools, such as Quarto Wizard or a future official q2 extension for Positron and VS Code, can read the same keys instead of keeping their own.

Related:

Dominant language
Rust
Stars
302
Forks
22
Avg merge
5h 2m
Merged PRs (30d)
213

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from quarto-dev/q2

All issues in quarto-dev/q2

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.