Better name for [[dependencies]]

[sdboyer]

The [[dependencies]] field name in Gopkg.toml is misleading and problematic. Most people see it and assume that it works in the same way other language package managers do - you have to declare dependencies in Gopkg.toml for dep to pull them in at all.

But that's not how dep works - import statements in the code itself are the bit that define what code is required. Gopkg.toml just applies rules and constraints to control how those imports are satisfied.

The key should be renamed accordingly. The two possibilities I can immediately think of are constraints or rules, though I don't especially love either. Here are some relevant considerations:

1. Remember that overrides also exist, and supercede what we today call dependencies. While the name needn't necessarily reflect this relationship, it should at least not be contrary to it.
2. Each dependencies item can specify an alternate source - not just the version constraint.

[spenczar]

I vote for [[ constraints ]]. It makes it clear that, if left unset, dep will handle things on its own, since constraints are only things that limit the solution space. I think the most important thing in the naming is that it communicates the intent to the user, which constraints does well.

I don't mind that the [[ constraints ]] items could specify alternate sources. It seems constraint-ish to say "You should only fetch this dependency in this way." It's maybe just slightly off, but I think the benefit of clarity for the common case (that you would use this to specify version constraints) outweighs that.

[sdboyer]

@spenczar thanks for weighing in 😄 i've had similar thoughts about using [[constraints]]. If we can get at least some informal indications that this matches other peoples' intuitions, I'm happy to go that direction.

Alternate suggestions still welcome too, of course!

[davecheney]

[[requirements]] ? (Maybe easy_install was on to something)

…

On 4 May 2017, at 02:00, sam boyer ***@***.***> wrote: @spenczar thanks for weighing in 😄 i've had similar thoughts about using [[constraints]]. If we can get at least some informal indications that this matches other peoples' intuitions, I'm happy to go that direction. Alternate suggestions still welcome too, of course! — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or mute the thread.

[ghost]

(requirements is easier to pronounce than constraints 😄)

[davecheney]

Possible slight improvement [[requires]]

…

On 4 May 2017, at 17:51, cwgt ***@***.***> wrote: (requirements is easier to pronounce than constraints 😄) — You are receiving this because you commented. Reply to this email directly, view it on GitHub, or mute the thread.

[spenczar]

Oh, I'd like to switch my vote to [[ requirements ]]. I like that a little more than constraints. It accomodates the alternate-source-thing, and it has prior art through its use in Python-land.

I like requirements more than requires because its a list of values, so the name of the list should be a plural noun. requires is a verb, which leads to weird phrasings like "I tried to add it to my requires, but I didn't know what version to use."

[sdboyer]

Hmm, interesting. so, i'd considered [[requirements]] before. In fact, i have formed the exact same sentence in my head that @davecheney wrote - "maybe easy_install was on to something". However, i didn't include it on this list because there's already a required field in Gopkg.toml.

Now, we could rename that too - but it's named that way because of this larger issue that "required" seems to me to be ambiguous between:

1. The dependency's code MUST be present, AND the rules must be met, vs.
2. IF the code is in imports statements/ the required field, THEN these rules must be met.

We get a lot of questions about this as it is (I should make an FAQ item for it, right now it's only referenced obliquely); people are often surprised, especially coming from other language systems, that Gopkg.toml's list of dependencies are merely constraints, rather than being full-blown statements of requirement.

Part of my goal with renaming this is to help clarify this distinction. It seems like calling it [[requirements]] would take us away from that, but it's hard for me to know how other people make sense of the system.

[anjmao]

Hi, I'm new here. Sorry for silly questions:

1. Can it be in singular form [[requirement]] ?
2. If yes, can it be named just [[package]] because all is about go packages vendoring right?

In any way I can pick this one as first PR :)

[carolynvs]

I should make an FAQ item for it, right now it's only referenced obliquely

@sdboyer Challenge accepted! #516

[spenczar]

@sdboyer, you make some really excellent points there. I didn't remember that required already exists, and I lost sight a bit of the fact that constraints is excellent at signalling that it's just additional rules.

I think I'm maybe back to Team Constraints, but I'm confident that the bike shed will be a lovely color, whatever it gets painted as. :)

[carolynvs]

I prefer constraints because as @spenczar said it better reveals the intent, constraining discovered packages, instead of acting as the "one true list" of dependencies/requirements. #TeamConstraints

[sdboyer]

@anjmao hi, welcome! 😄

Can it be in singular form

Yeah, since we're using TOML, singular seems like a much better idea - each time you see [[<word>]], it'll be another single instance of it.

If yes, can it be named just [[package]] because all is about go packages vendoring right?

It's pretty different from that, actually. These values are rules that are applied to projects - trees of packages with a root that's almost always the repository root, e.g. github.com/golang/dep.

In any way I can pick this one as first PR :)

That'd be awesome, once we settle on what to do 😄

[kevingo]

I both love [[ constraints ]] and [[ package ]]. The [[ constraints ]] clearly reveal its intent. And for other popular dependency management tools, such as Glide and govendor, the [[ package ]] naming are popular used.

[ibrasho]

I agree with the opinion that [[dependencies]], [[packages]] or their singular forms might be misleading since the effect in dep is different. I even think [[ requirements ]] has the same issue.

[[constraint]], [[condition]] or [[specification]] (just [[spec]]?) seems like a better idea.

EDIT: I was just reading the dep: updated command spec document, and noticed that the dep ensure usage was documented as:

dep ensure [-update | -add] [<specs>...]

🙄

[sdboyer]

@ibrasho and spec doesn't even map quite directly - while there's a general, long form of it (which is actually more than what can be specified in Gopkg.toml), not all variations on the form are always allowed, depending on whether -add or -update (or neither) are passed. So it's not even quite 1:1.

At this point, it looks like [[constraint]] is the way we should go.

[sdboyer]

Yeah, OK, let's move ahead with [[constraint]] as the name. @anjmao, did you still want to take this on as your first PR? 😄

Some notes/guidelines for this:

1. This is the last stop before providing backwards compatibility, so no need to care about compatibility with existing files.
2. The element in the file should be [[constraint]], per the discussion above, but the name of the property on dep.Manifest should be plural - Constraints.
3. A whole ton of test fixtures will, of course, need to change. go test -update will do that for you, once you're happy with the implementation.
4. Don't forget to update the example text that's injected into Gopkg.toml (see txn_writer.go).
5. I'm likely to delay merging the PR until all of these final changes we're looking to make are ready, so that there's a single, clean break for users.
6. In my most ideal world, the PR will be ready by the end of this week 😄 😄

[felipeweb]

@sdboyer If still got this issue to solve, I can get it. Has anyone caught it?

[sdboyer]

@felipeweb sweet! go for it 😄 🎉

[anjmao]

@sdboyer Ah, too late :D I will look for another one :)