Pkg.jl: The "Using Artifacts" example in the docs is incompatible with "immutable packages"

[helgee]

I failed to understand how to work with artifacts today and needed the help of some friendly people on Slack to grasp why I was getting nowhere. After some deliberation we have identified the following reasons:

1. It was unclear that currently Pkg only deals with tarballs (i.e. #1921) but this is documented on master.
2. The iris example seems to be incompatible with the notion of "immutable packages".

My understanding of artifacts was based on reading the stable docs and the coverage during JuliaCon. Subsequently my misconception was that the code in the aforementioned example would lead to a "usable" Artifacts.toml file, i.e. a file that is read-only and can be shipped as part of an immutable package. I did not understand that this is not the case.

These quotes from the docs seem problematic in this context:

First, it modifies the package directory, making package installation stateful, which we want to avoid. In the future, we would like to reach the point where packages can be installed completely read-only, instead of being able to modify themselves after installation.

For the specific use case of using artifacts that were previously bound, we have the shorthand notation artifact"name" which will automatically search for the Artifacts.toml file contained within the current package, look up the given artifact by name, install it if it is not yet installed, then return the path to that given artifact.

CC: @giordano

EDIT: My use case was downloading a ZIP file and making the extrated data available.

[KristofferC]

I think I've gotten similar confusion. To me, it seems that the whole bind_artifact! thing is supposed to be done in an offline phase (offline meaning just running it once locally) and the code to do that should not be committed to the repo?

Rewriting the docs into a "setup" - phase and a usage phase might make sense.