From version 0.6.0, orderly
supports the concept of a
“changelog”. This turns out to be somewhat more complicated than
expected, so the details are explained here.
From the user perspective, the changelog functionality should be
fairly simple. Alongside any orderly.yml
file, one can have
a changelog.txt
file, which will contain description of
changes. This file will look like:
[public]
Started working with new version of the data. This includes
everything sent up to 2018-10-10
[internal]
Fixed incorrect plotting
The short strings within [
and ]
are a
label - everything between a label and the next label or the
end of file is a value (these can span multiple lines, contain
blank lines, etc).
Over time, the changelog is prepended, i.e., new information is added to the top of the changelog. Existing entries must be left unaltered.
Messages can be provided to orderly_run
(or
orderly run
on the command line) and these are required to
be in the format [label] value
.
Once a report is run (via orderly::orderly_run()
, or via
orderly run
on the command line), the given changelog,
along with any message, is compared with the last committed version of
this report, and entries that are introduced on this round are
identified. We add the report id to the entries, and a randomly
generated unique id to each new entry. This is saved in
orderly_run.rds
along with other report metadata.
Dear intrepid reader, you can stop reading now unless you are interested in the details of how we have implemented the changelog - this turned out to be a bit fiddly and this section documents some of the issues.
There are a few complications here
message
argument)This section documents the logic involved in making this work.
When preparing to run an orderly report:
from_file
of FALSE
orderly_run.rds
file.
Alternatively we can use a remote copy of orderly via the interface here
(not implemented yet).from_file = FALSE
entries and confirm that our new
changelog can be prepended to the previousid
to the “new” entries and prepend this - save
the resulting data into the new report’s
orderly_run.yml
For checking against the API, we will use
GET reports/:name/versions/version/latest/changelog/
with
the current report name as :name
.