New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Better name for [[dependencies]] #509

Closed
sdboyer opened this Issue May 3, 2017 · 19 comments

Comments

Projects
None yet
8 participants
@sdboyer
Copy link
Member

sdboyer commented May 3, 2017

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

This comment has been minimized.

Copy link
Contributor

spenczar commented May 3, 2017

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

This comment has been minimized.

Copy link
Member

sdboyer commented May 3, 2017

@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

This comment has been minimized.

Copy link
Contributor

davecheney commented May 3, 2017

@ghost

This comment has been minimized.

Copy link

ghost commented May 4, 2017

(requirements is easier to pronounce than constraints 😄)

@davecheney

This comment has been minimized.

Copy link
Contributor

davecheney commented May 4, 2017

@spenczar

This comment has been minimized.

Copy link
Contributor

spenczar commented May 4, 2017

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

This comment has been minimized.

Copy link
Member

sdboyer commented May 4, 2017

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

This comment has been minimized.

Copy link

anjmao commented May 4, 2017

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

This comment has been minimized.

Copy link
Collaborator

carolynvs commented May 4, 2017

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

@sdboyer Challenge accepted! #516

@spenczar

This comment has been minimized.

Copy link
Contributor

spenczar commented May 4, 2017

@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

This comment has been minimized.

Copy link
Collaborator

carolynvs commented May 4, 2017

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

This comment has been minimized.

Copy link
Member

sdboyer commented May 4, 2017

@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

This comment has been minimized.

Copy link

kevingo commented May 6, 2017

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

This comment has been minimized.

Copy link
Collaborator

ibrasho commented May 7, 2017

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

This comment has been minimized.

Copy link
Member

sdboyer commented May 8, 2017

@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

This comment has been minimized.

Copy link
Member

sdboyer commented May 8, 2017

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

This comment has been minimized.

Copy link
Contributor

felipeweb commented May 9, 2017

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

@sdboyer

This comment has been minimized.

Copy link
Member

sdboyer commented May 9, 2017

@felipeweb sweet! go for it 😄 🎉

@anjmao

This comment has been minimized.

Copy link

anjmao commented May 10, 2017

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment