Making CLI interface to the UPDATING file

A quick note: currently I am concerned with the /usr/ports/UPDATING, but may be eventually /usr/src/UPDATING will also come into the game.

There is already pkg_updating(1) utility, but is just displays UPDATING entries for the given or all installed ports regardless of their versions. It also lacks processing of shell-like globs in package names inside AFFECTS.

Project phases


Users tend to forget to read /usr/ports/UPDATING. Current tools like portupgrade or portmaster have no support for showing UPDATING entries to their users. Obviously, it is better to have the tool that will be able to query the UPDATING document programmatically (via CLI) and thus all port-management tools that deal with upgrades will get the ability to present the relevant UPDATING entries for their users at the right time.

Survey of current UPDATING

TBD. I should examine all current entries and determine how they are used.

Design of the tool

Minimally, the tool should be able to

Output formats:

Tool distribution:

Design of the data format

Representation of a source UPDATING format

Available options:

Representation of a cooked UPDATING format

By "cooked" I mean the format of the date that is fed to the CLI utility as the input.



Data delivery to the end-user

Ideally, nothing should be changed: user invokes his preferred procedure to update the ports and he received UPDATING as the part of the process.

What format, source or cooked, should be delivered?

I'd vote for the source delivery, but this has some implications for the XML/JSON/othername formats -- will need the tools for them, so, most likely, utility will be a port.

Metadata contents and its semantics

There are at least two cases:

Type-"a" entries should have port name and version in the metadata; user should see such entries if he upgrades the port X from version < N to the version >= N.

Entries of type "b" tend to say the following: "if you had ports A, B, C, ... installed before the date Z, then you should do so-and-so to upgrade them without troubles". So, user should see such entries if either A, B, C, ... are upgraded and old version of ports being upgraded were built before the date Z.

Additionally, any entry can have the flags that will tell one if this entry is applicable to the pre-upgrade phase, post-upgrade phase or both.

When to present the data to user

Our CLI should not mess with this question: it is up the tool consumers to choose the right place and time. However, in order to make the consumers happy, we should design the metadata


That's all for now, folks!

EygeneRyabinkin/PortsUpdatingNg (last edited 2010-12-29T15:44:50+0000 by EygeneRyabinkin)