Does Manifest.toml belong in the repository?

Sorry if this is a dumb question, but I could not figure this out. It seems to be generated dynamically when missing, so should I add it to the git repo?

3 Likes

The Manifest allows someone to replicate the exact version of the dependencies that was recorded in the manifest on e.g. another machine. For a package that is to be used as a library, this is not super useful because there will be some other Manifest dictating the versions of what is installed.
However, for an “application”, i.e. something at “top level” (say your julia code to do the simulations in a scientific paper) then it is likely useful to be able to replicate that exact state and the Manifest is thus useful to check in.

22 Likes

It might also be nice to have a manifest checked into package repos for a few reasons:

  1. So that you have at least one known good configuration that presumably passed tests and such.
  2. To keep the different developers of the package in sync using similar setups.

Of course, 2 cuts both ways: it’s nice that all the devs have similar setups and they can upgrade in sync, but that means that there’s less testing of the package with different setups. Benefit 1 may be better accomplished with some kind of database for recording known good/bad configurations.

1 Like

I decided not to include it for now, as I think that version bounds should be specified explicitly, and in case that does not work, that is a bug.

In any case, some guidance in the documentation about this would be useful as a starting point.

8 Likes

Related from the Rust Cargo FAQ:

https://doc.rust-lang.org/cargo/faq.html#why-do-binaries-have-cargolock-in-version-control-but-not-libraries

2 Likes

So, including the Manifest.toml provides reproduce-ability at the expense of maintaining the Manifest.

There’s nothing to maintain manually, it’s handled by julia when updating packages and adding new packages. If you want to provide a reproducible state with specific versions of packages, include it, if not, don’t.

1 Like

There’s nothing to maintain manually

Yes, I understand this.

I had a problem recently with CI failing

and was advised to delete manifest.toml from the repo. That solved my problem, but I was not sure how wise it is/was to do that. This thread has me more confused than before.

Yes, I also had a fair share of troubles with CI because of a checked-in Manifest. Note also that if you have a checked-in Manifest and bump the compat bound of a package without updating the Manifest, you still test the old version.

Also, the Manifest is specific to a Julia version, which may not play very nicely with running CI across several Julia versions in some cases

2 Likes

That’s a much clearer and more useful account of the problem than the confused version I had.

The question remains: is leaving the Manifest.toml out of the repo a good thing to do? I can’t think of an alternative.

It depends on who you ask to :slightly_smiling_face: If you ask me, I’d say it’s fine not to have the Manifest checked in the repo of a package :stuck_out_tongue: I can see why other people prefer to put it under version control, my problem with it are the troubles it causes with CI.

For a package, I would suggest that you leave it out.

For a project, including it is useful.

5 Likes

That’s what I’ve been doing. I don’t do CI on projects or applications, so having Manifest.toml around does not cause problems.

As you said upthread, some guidance about this would help.

Yes, that’s also my rule of thumb. For applications the Manifests makes very much sense and I’m very happy we have this tool, for packages I find it too limiting. Probably, if it didn’t cause problems with CI I’d be neutral about, or even in favour of, having it in the repo of a package.

1 Like

I think maybe this advice should be codified into the docs for Pkg. So far as I can tell, we have no official documentation that makes this clear and I think this is a common confusion.

4 Likes

Interesting that I just stumbled on this thread.

I recently changed one of my packages to use an unregistered package. Without a Manifest.toml, the integration tests (nor any other user if my package) would know where to find the unregistered package.