Store and print dependency versions

[timothymcmackin]

We've been talking about how to ensure that tutorials and tasks keep working as programs get updated. This is a sketch of how it might work:

Topics (particularly tutorials, but really any topic) can have a dependency front matter field with information about the programs it uses and the version on which it was most recently tested, as in this example:

---
title: Deploy a smart contract
authors: Tim McMackin
dependencies:
  smartpy: 0.19.0
  ligo: 1.6.0
  archetype: 1.0.26
---

The program collates these dependencies and prints the file names that may need to be tested and updated when those programs get updated as in this example:

Program: octez-client
  Version: 19
     docs/smart-contracts/multisig.md
     docs/developing/testing.md
     docs/developing/information.md
     docs/architecture/data-availability-layer.md
     docs/developing/octez-client/installing.md
     docs/architecture/tokens/FA1.2.md
  Version: 20
     docs/tutorials/smart-rollup.md

Program: taquito
  Version: 19
     docs/smart-contracts/events.md
     docs/dApps/wallets.md
     docs/dApps/taquito.md
     docs/dApps/sending-transactions.md
  Version: 20.1
     docs/tutorials/build-your-first-app.md

Note that I have put version numbers into these MD files for testing purposes and we should do a full review of version numbers before implementing this.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
docs-staging	✅ Ready (Inspect)	Visit Preview	Jan 16, 2025 2:10pm

[NicNomadic]

Very nice start! I think the output of the script should just be optimized to show only the relevant information. Could we have the current versions of each tool in some configuration file, so that the checking script can list only the files needing updates?

[timothymcmackin]

Very nice start! I think the output of the script should just be optimized to show only the relevant information. Could we have the current versions of each tool in some configuration file, so that the checking script can list only the files needing updates?

We could do that, but it introduces a dependency: the names of the tools in the config file would have to match the names of the tools in the page front matter. If we list octez in the config file and a page lists octez-client as a dependency, the script won't print the octez-client version. Same thing if someone misspelled "taquito;" the file would not appear in the results. I'll sketch out how it might work with the config file, but that flaw may cause us to miss files that need updating.

Maybe a better way is to print a summary of the results that lists every version of every tool used without individual file names. Then you could see that some files used an old version of a tool and you could search for those files.

[timothymcmackin]

As an example I added how we might check dependencies against a list of current versions, but this has some flaws as in my prior comment. The new script prints a summary of files that need to be updated like this:

***
UPDATES NEEDED
***

These pages need to be updated to the latest version of the specified tool:

Checking octez-client for which the current version is 20.1.0
  These files use version 19:
     docs/smart-contracts/multisig.md
     docs/developing/testing.md
     docs/developing/information.md
     docs/architecture/data-availability-layer.md
     docs/developing/octez-client/installing.md
     docs/architecture/tokens/FA1.2.md
  These files use version 20:
     docs/tutorials/smart-rollup.md


Checking taquito for which the current version is 20.1.0
  These files use version 19:
     docs/smart-contracts/events.md
     docs/dApps/wallets.md
     docs/dApps/taquito.md


Checking ligo for which the current version is 1.7.0
  These files use version 1.6.0:
     docs/tutorials/smart-contract.md

[NicNomadic]

Very nice start! I think the output of the script should just be optimized to show only the relevant information. Could we have the current versions of each tool in some configuration file, so that the checking script can list only the files needing updates?

We could do that, but it introduces a dependency: the names of the tools in the config file would have to match the names of the tools in the page front matter. If we list octez in the config file and a page lists octez-client as a dependency, the script won't print the octez-client version. Same thing if someone misspelled "taquito;" the file would not appear in the results. I'll sketch out how it might work with the config file, but that flaw may cause us to miss files that need updating.

Maybe a better way is to print a summary of the results that lists every version of every tool used without individual file names. Then you could see that some files used an old version of a tool and you could search for those files.

If you print all the files depending on: old tools AND tools not in the config file, then we'll be forced to maintain the config file to cover all the mentioned dependencies. For instance, we'll put both octez v21 and octez-client v21 if we see that some pages are wrongly listed as outdated because the config is not complete. Alternatively, your tool could report an error when a dependency is not in the config at all.

Would this solve your concern?

[NicNomadic]

As an example I added how we might check dependencies against a list of current versions, but this has some flaws as in my prior comment. The new script prints a summary of files that need to be updated like this:

The output is not bad, but we risk having duplicate files. It would be more scalable to list for each outdated file the list of obsolete dependencies, if any. If all dependencies are current, you don't list the file at all. If it uses any tool unknown in the config, error. Would this work for you?

[timothymcmackin]

@NicNomadic Here's a version that organizes the output by file name and prints only the files that have missing or outdated dependencies. For example:

docs/smart-contracts/multisig.md
Outdated dependencies:
For octez-client, this file uses version 19 but the current version is 20.1.

docs/tutorials/build-your-first-app.md
Missing dependencies:
This file has a dependency for vite but there is no current version for this tool in the config.

docs/tutorials/smart-contract.md
Outdated dependencies:
For smartpy, this file uses version 0.19.0 but the current version is 0.20.0.
For ligo, this file uses version 1.6.0 but the current version is 1.7.0.

docs/tutorials/smart-rollup.md
Outdated dependencies:
For octez-client, this file uses version 20 but the current version is 20.1.

Reviewed 151 files.

Not sure whether it's better to organize results by dependency or by file name. When a new version of Octez comes out we'll want to know the files that need updating, but if we keep things up to date the results won't have a lot of tools to worry about.

[NicNomadic]

The output is nice, maybe just a bit verbose. I'd truncate it like so:

docs/tutorials/smart-contract.md
uses smartpy 0.19.0 < 0.20.0
uses ligo 1.6.0 < 1.7.0.

docs/tutorials/build-your-first-app.md
error: unknown dependencies: vite

Don't worry about finding all the files depending on a specific tool, we'll filter the output for that.

Unless you may add a parameter to the command npm run check-dependencies octez-client that will only check files for this dep? The default being: check for all the deps.