Explain the status of the project

[dlsniper]

What does this do / why do we need it?

Following the discussion #1070 (comment)
"Agreed, dep cannot currently be trusted to not make changes after the importers are run.
The issue which tracks that is #908.", it is clear that the maintainers of
the tool do not see it as a reliable project.

As such, the users should be correctly informed about the status of the
project and what are the goals in order to make it a production ready one.

What should your reviewer look out for in this PR?

Correctly set the expectations of users in case I'm not aware of any further milestones.

[dlsniper]

To further explain the PR.

I do not wish to diminish the efforts of the team behind this project. However, production safe sets certain expectations for users, especially for non-native English speakers (like myself). Based on my experience with dep on the first serious usage session, I've found that I cannot reliably import an existing project due to a bug which is not classified as a bug (and imho it should be a major one) but I cannot also get it to work with other projects such as https://gobuffalo.io

As such, I think that it's important for people to have a clear/correct picture of the status quo and as soon as the situation changes, that should also be reflected in the Readme.

Thank you.

[sdboyer]

We do see dep as a reliable, production-ready project, as we view that as mostly being a product of the main paths that people encounter in everyday use. Those paths are on dep ensure, not dep init, and are generally safe and stable. We have to pick some definition for "safe for production use" (because "has no bugs" isn't a feasible), and that's the one we've picked, because once you're over the hump of dep init, use of the tool is generally quite smooth.

dep init is incrementally chipping away on a herculean task - perform automated conversion of all the existing tools. dep has a strongly-opinionated model about what constitutes a workable depgraph. The other tools do, too. We can't always make them fit together nicely. It's unfortunate that this is also the first thing that people encounter, as dep init can leave a poor impression about dep's overall behavior and stability. to that end:

"Agreed, dep cannot currently be trusted to not make changes after the importers are run.
The issue which tracks that is #908.", it is clear that the maintainers of the tool do not see it as a reliable project.

"currently be trusted" here may be a bit misleading. While we currently don't know why dep didn't use the rev you originally had there (using -v would have told us), it is not and cannot be a design goal of dep to honor all the exact depgraphs that other tools might have created. As #908 notes, sometimes the best we can do is inform the user that a change has happened, and why.

All that said, i've pushed a change to the README that acknowledges the issues with dep init in particular. Let me know how it strikes you.

[sdboyer]

@ScottMansfield which part of that frustrates you?

[ScottMansfield]

First impressions are hard to shake, so I think your approach of defining "production ready" as dep ensure only is not the right one.

[sdboyer]

indeed, they are hard to shake.

we could consider making dep init's default behavior not use the tool importers, so that people have to opt in to using them. that might at least help by implying that folks will understand the tool import behavior to be an additive convenience (which is really what it is), rather than viewing it as a core behavior.

there's a line to walk here, though. right now, it looks like there's a bug/regression that's caused the mismatch in this particular case - #1070 (comment). maybe we just need to be a little more cautious with the importers. but these things happen, especially if you're riding HEAD - which is why we're trying to move away from recommending that, in favor of the released versions in #996. but, most importantly, it's not always a bug if the input from the tool can't be directly converted.

either way, the gist of this PR is that an unfortunate combination of expectations and bugs came together and caused a poor experience for @dlsniper, within the specific, narrow span of time in which dep init is part of the workflow. that really sucks, but the solution there is "address these specific bugs," not "decide dep isn't production ready."