Update documentation to explain when cleaning the cache might be necessary

[daniwelter]

Would it be possible to either update release_diff to run with the -B option as standard, or update the usage notes in the commands reference at the bottom of the Makefile to explicitly state to use the option?

For context, the Makefile currently suggests under "Tricks": * Add -B to the end of your command to force re-running it even if nothing has changed

As a "lay" user, I assumed this didn't apply to release_diff, since things clearly had changed and the current release would be dynamically pulled in every time I ran the command. I was therefore surprised to find that every time I ran the command before a release, the diff was against an older version of the ontology, so I always had to run a manual robot diff instead until @matentzn pointed me in the right direction.

Please either refactor the Makefile for release_diff to pull in current_release.owl each time it is run rather than using the cached version, or update the usage notes to make it clear that the -B option is required and appropriate in this scenario.

[gouttegd]

No. The Makefile is working as designed, and we cache files for a reason.

If you do not want the result of a workflow (be it release_diff or any other ODK workflow) to be impaired by cached files, the proper solution is to clear the cache (make clean), not to force Make to ignore every existing files and build everything from scratch.

[matentzn]

I think most people won't know what "cache" means, and that you may have to invalidate it. I asked @daniwelter to make an issue (thanks for that Dani) to see if we can improve the documentation to that extend?

[gouttegd]

I think most people won't know what "cache" means, and that you may have to invalidate it

Even if that were true, the proper solution in that case is to explain what the cache is, and that sometimes you may need to clear it. Not to suggest to users that they should always bypass the cache with -B, or worse, to refactor the Makefile to hardcode the use of -B and therefore systematically bypass the cache – what would even be the point of having a cache then?

There should be almost never any legitimate reason to use -B. Valid reasons to use -B should be exceedingly rare. If you find yourself in a situation where the only way to get Make to build what must be built is to use -B, most likely it is a bug in the Makefile.

[matentzn]

Yes we are in agreement. The specific case is if the dependency is a file to be downloaded, for which we have developed quite a complex workaround.

This may not always be available. I think this is best done with some nice user guide "Getting started with ODK" with a sentence on caching, maybe in obook!

[gouttegd]

The specific case is if the dependency is a file to be downloaded, for which we have developed quite a complex workaround.

Only for some cases (the mirror files used to generate the import modules, and also I believe the externally sourced components). There are quite a few other cases where the dependency is a file to download, and where we do not do anything special (the downloading of the current release in order to produce the “release diff” is one of them).

This is one of the things I want to review at some point (but not sure if it will be for 1.6 or later). I’d like a standard way of downloading a remote dependency, instead of having several independent ad-hoc rules.