add more helpful chop message

[jalehman]

Resolves #634

[jalehman]

We could be even more explicit. Instead of:

chop: nothing to do, try running roll first

We could say something to the effect of:

chop: nothing to do, try running ./path/to/pier/.run roll

[jalehman]

It also looks like there's no documentation for roll in the runtime reference, and the entry for chop is out of date.

[tinnus-napbus]

I updated the runtime reference earlier, PR just needs review/merge

[jalehman]

Great, much appreciated. The time that someone needs the runtime reference is when they're running into an issue while using vere. What do you think about adding links to documentation at the point of encounter? For example:

printf(stderr, "chop: nothing to do, try running roll first\r\n");
printf(stderr, "info: https://docs.urbit.org/manual/running/vere#chop\r\n");

[tinnus-napbus]

Conceptually it seems fine, although the structure of the docs are possibly in flux at the moment. Neil & Thomas are hashing out changes atm. Don't want a broken link

[belisarius222]

Here are the possible scenarios in which run chop will no-op, if I understand this code right:

1. There are only two epochs because roll has never been run and the user has run one Kelvin update.

• User should roll then chop again if they want to truncate.

2. There are only two epochs because the user has run roll exactly once since the last time they chopped, and the ship has been running after that roll.

• User should roll then chop again if they want to truncate.

3. There is only one epoch because the ship was booted on the latest Kelvin and has never roll'd.

• If user just rolls and chops, nothing will happen, because roll will only increase the number of epochs from one to two, and chop only chops down to the latest two epochs. User could roll, then run for a bit, then roll again, then chop. Obviously this is not ideal user experience.

4. There are two epochs because the user just ran chop, deleting all older epochs, and the ship has not been run since.

• User should stop trying. Event log is as chopped as it's going to get.

In scenarios 1 and 2, suggesting roll in the chop no-op message makes sense and is helpful for the user. In scenarios 3 and 4, it would be misleading. Suggesting roll still might be the right move if those first two scenarios are significantly more common than the last two -- and roll isn't a dangerous or destructive operation, so it's not awful even if it is misleading -- but it's not that clear to me.

Maybe we could tweak the message somehow to be more generally applicable. We might also want to consider adding some more command-line options, though, such as chop --force, or a combination of chop and roll... something along those lines so that the user can know there's something they can always run to get their pier into the desired state.

[jalehman]

Let's not let the perfect be the enemy of the good. Given that roll isn't dangerous at all, recommending it seems fine. I've had this issue myself (not knowing to roll before chop) and seen several cases of others experiencing it.

Further improvements would be great: feedback about what happened after running roll that could help the user diagnose whether or not the operation was still useful in the cases of 3 or 4; a force flag to chop to combine common operations; etc.

[tinnus-napbus]

In the case of 4, if you're unsatisfied with the size reduction, you may want to start/stop the ship, roll, start/stop the ship, roll, then chop, to maximally reduce size.

[tinnus-napbus]

updated with docs link