Update references to 1.2 spec, re-ordering, content updates

[a-mile]

This branch updates the tutorial to reference the 1.2 spec. It also addresses suggestions for updating content in preparation for the upcoming ACM Rep conference. These include:

• Re-ordered lessons so that root data entity comes before metadata entity
• Moved "Add an additional type" from cross references to root (seemed to make more sense there)
• Added some abbreviations
• Fleshed out the cross references lesson a bit more
• Updated contextual entities to use instrument as an example as opposed to license. If this doesn't make sense I can change it back, it just seems a little clearer as an example of a context entity (since license can be data or context.)
• Took out section to override the license
• Added common pitfalls lesson
• Extended next steps
• Fixed a few typos

[github-actions]

Thank you!

Thank you for your pull request 😃

🤖 This automated message can help you check the rendered files in your submission for clarity. If you have any questions, please feel free to open an issue in {sandpaper}.

If you have files that automatically render output (e.g. R Markdown), then you should check for the following:

• 🎯 correct output
• 🖼️ correct figures
• ❓ new warnings
• ‼️ new errors

Rendered Changes

🔍 Inspect the changes: https://github.com/ResearchObject/packaging_data_with_ro-crate/compare/md-outputs..md-outputs-PR-9

The following changes were observed in the rendered markdown documents:

 01-introduction.md                          |  23 +++--
 02-folder-as-crate-root.md                  |  11 ++-
 03-metadata-descriptor.md                   |  30 +++++--
 04-root.md                                  |  56 ++++++++-----
 05-root-metadata.md                         |  11 +--
 06-cross-references.md                      |  85 ++++++++++---------
 07-data-entities.md                         |  12 ++-
 08-contextual-entities.md                   |  53 ++++++++++--
 09-authorship.md                            |   6 +-
 10-validating.md                            |   9 +-
 11-triples.md                               |   4 +-
 12-html-preview.md                          |  27 ++----
 13-complete.md                              |  27 +++---
 14-next-steps.md                            |  23 +++--
 15-common-pitfalls.md (new)                 | 125 ++++++++++++++++++++++++++++
 CODE_OF_CONDUCT.md                          |   4 +
 LICENSE.md                                  |   2 +-
 config.yaml                                 |   3 +-
 files/rainfall-1.2.1/index.html             |   6 +-
 files/rainfall-1.2.1/ro-crate-metadata.json |   6 +-
 files/rainfall-1.2.1/ro-crate-preview.html  |   6 +-
 index.md                                    |   2 +-
 md5sum.txt                                  |  37 ++++----
 23 files changed, 379 insertions(+), 189 deletions(-)

What does this mean?

If you have source files that require output and figures to be generated (e.g. R Markdown), then it is important to make sure the generated figures and output are reproducible.

This output provides a way for you to inspect the output in a diff-friendly manner so that it's easy to see the changes that occur due to new software versions or randomisation.

⏱️ Updated at 2025-07-25 08:52:06 +0000

[a-mile]

There is a validation failure in the new lesson file that my local build isn't picking up, I will get back to it tomorrow morning to troubleshoot.

[elichad]

Thanks for these updates @a-mile ! I've made some suggestions for clarity and such but on the whole these look like good changes.

[elichad]

I think you renamed these three the wrong way round - this one should have become 04-root.md and so on (the content no longer matches the filename). I'll fix that and then merge

[elichad]

I missed this first time through, but I think we should move this section to where we add the metadata descriptor.

[elichad]

I made a commit for this, hopefully it is not contentious :)

[elichad]

I'm happy with this now, thanks again @a-mile !

[elichad]

Merging now so we have plenty of time to check that all the changes show up correctly on the website