Site-www: [discussion]: Tweak pubspec.lock recommendations

[jonasfj]

See: https://dart.dev/guides/libraries/private-files#pubspeclock

Today, we say:

For library packages, do not commit the pubspec.lock file.
For application packages, it’s up to you whether you commit the pubspec.lock file. Consider checking it in if you want to track the dependencies that are used for production or across a team.

I think, it would be better to say: (_or something along these lines_)

For library packages, it can be a good idea to not commit the pubspec.lock file. Committing the pubspec.lock file will not affect package consumers, they are likely to get the latest dependencies allowed by pubspec.yaml. Therefore it can be a good idea to avoid locking your dependencies and test against the latest versions of your dependencies. However, committing the pubspec.lock file may produce more consistent CI test results, and whether or not to commit it can be a matter of personal preference and workflow.

I _strongly_ think, it would be better to say: (_or something along these lines_)

For application packages, always do commit the pubspec.lock. This will lock your dependencies, so that code changes in your dependencies doesn't sneak in as your application progresses from development, to integration testing, to product release, to product support.

---

Rationale for library packages recommendations

When developing a library package the pubspec.lock will not affect the package consumers.
When pub get downloads a package it will not read the pubspec.lock from the package being downloaded. Package consumers will always get the latest dependencies compatible with the constraints in pubspec.yaml.

Hence, whether you choose to keep pubspec.lock under source control is a matter of personal preference (or workflow).

Reasons to keep pubspec.lock in git includes:

• It is easier to reproduce behavior your collaborators experience, because all developers of the library package has the same dependencies.
• Your CI results (on travis, jenkins, etc) won't break unexpectedly because some upstream package changed. Hence, your CI results are more consistent, and less intermittent.

For large teams working on a library package, locking dependencies might make sense. Because intermittent CI results can be disruptive to the workflow.

The counter argument is that you easily forget to test against latest dependencies if your CI system isn't doing it. And the package consumers will likely get the latest dependencies, so it's unfortunate that you're not testing against them.

I don't feel too strongly about recommendation we give, but making it clear that pubspec.lock won't affect package consumers seems like a good idea.

Rationale for application packages recommendations

When developing an application package the pubspec.lock specifies part of the code that makes up your application. If you don't commit the pubspec.lock file, you may inadvertently upgrade your dependencies between testing and deployment. Common scenarios include:

• Flutter deployment using tutorials for Cirrus, codemagic or bitrise.io.
• Deployment of any kind from GitHub Actions or GitLab CI/CD.
• Deploying to Platform-as-a-Service providers from git, examples includes heroku (which use git push heroku for deployment), Google Cloud Build which can deploy to AppEngine, Cloud Run, etc.
• Deployment from a different working folder (git checkout) or physical machine than was used for primary development.

Doing any of this without a pubspec.lock under source control and you may easily deploy a configuration you have not tested. And once you have deployed this untested configuration, you may have a hard time reproducing issues reported by users, because you might have different dependencies (and it's hard to guess which packages was actually deployed into production).

Therefore it is in my opinion very important that application developers keep pubspec.lock under source control.

---

CC @sigurdm, @mit-mit, @natebosch, @jakemac53, please tune-in if you have any thoughts.

[mit-mit]

I just earlier today suggested to @kwalrath in email:

for apps:

change:

**For application packages**, it's up to you whether you
commit the `pubspec.lock` file.
Consider checking it in if you want to track the dependencies that
are used for production or across a team.

to something like:

**For application packages**, we recommend that you
commit the `pubspec.lock` file.
This ensures everyone working on the app use the exact same versions.

for packages:

change:

**For library packages**, do **not** commit the `pubspec.lock` file.

to something like:

**For library packages**, do **not** commit the `pubspec.lock` file.
This ensures you test your package against the latest compatible versions
of its dependencies.

[natebosch]

This ensures you test your package against the latest compatible versions
of its dependencies.

"Ensures" is a strong word - there are other misconfigurations that could change this. I'd go with "This allows you to test your package..."

[jonasfj]

"Ensures" is a strong word - there are other misconfigurations that could change this. I'd go with "This allows you to test your package..."

Agreed. I often have a local pubspec.lock that is really old, because I forget to updated. But on travis I'll usually test against latest dependencies.

---

I mostly care that we: Strongly recommend _application packages_ do commit pubspec.lock.
(to mitigate dependency changes between dev, test, QA and production deployments).

I argue in the rationale above that: for _library packages_ whether or not to commit pubspec.lock is a matter of personal preference. But I care less if we emphasize this, people will do what they want anyways :)
(still it might be nice to point out, that if pubspec.lock is committed it won't affect package consumers)