Should I use `package:` import when importing my own package's library in Dart?

Question

I'm little bit confused about which style of import should I use when importing implementation libraries (code under src/lib) from another libraries (and tests) in my own package?

The docs recommends the opposite options.

In pub docs, it says:

When you use libraries from within your own package, even code in src, you can (and should) still use package: to import them.

But in "Effective Dart", it says:

When referencing a library inside your package’s lib directory from another library in that same package, use a relative URI, not an explicit package: URI.

In the end, which style should I use in such cases:

• import implementation library (under lib/src/) from with public library (under just lib/)?
• import implementation library (lib/src/foo.dart) from within its test (test/src(?)/foo_test.dart)?
• import public library (lib/foo.dart) from within its test (test/foo_test.dart)?

Britain

You found what's clearly a bug in the documentation, so filing a bug seems like the best course for clarifying the recommendation. – Sovran

That said, if you look at the git history for those two parts of the documentation, you'll see that that part of the pub docs was written 4 years ago, whereas that part of Effective Dart was written 4 months ago, so the Effective Dart recommendation is more likely to be current. In general, as a centralized source for recommendations, Effective Dart is more visible and is more likely to follow currently recommended practices. – Sovran

github.com/dart-lang/site-www/issues/2606 – Britain

IMO, reading documentation shouldn't require user to mess around git commits history in order to just know that documentation is outdated. It should be marked directly in documentation itself using big red title: "This is outdated!" – Britain

I never claimed that looking at Git history is required; I'm just using that to provide supporting evidence. The pub documentation isn't supposed to be outdated. The documentation authors can't mark something with "This is outdated!" if they don't already know that it's outdated (and if they knew that, they could fix it or remove it instead). Accidental oversights happen, especially when there's a lot of documentation and when some things are documented in multiple places. And if some things weren't documented in multiple places, then information would be harder to find. – Sovran

If you see an error in the documentation, your best course of action is to file a bug to get it corrected. – Sovran