Expand example Gopkg.toml text; always add on init #462

sdboyer · 2017-04-26T04:52:46Z

This expands the example text we add to Gopkg.toml to cover all valid values for the file.

It also changes the behavior of dep init to write out the example data unconditionally to the bottom of Gopkg.toml, rather than doing so only if nothing was to populate the manifest.

I'm not sure this latter part is the best idea, but being that there will be precious few situations under which we'd have an empty manifest (once init changes are done, #277), it seems worth being more aggressive about writing out these examples.

We could also add a flag to init that allows the user to suppress writing out the examples.

zellyn

lgtm

zellyn · 2017-04-26T17:23:07Z

cmd/dep/testdata/harness_tests/ensure/empty/case1/final/Gopkg.toml

 # revision = "abc123"
+
+## Overrides have the same structure as [[dependencies]], but supercede all


hah, no kidding 😛

zellyn · 2017-04-26T17:28:29Z

cmd/dep/testdata/harness_tests/ensure/empty/case1/final/Gopkg.toml

+##
+## Overrides are a sledgehammer, and should be used only as a last resort.
+# [[overrides]]
+## Required: the root import path of the project being constrained


Perhaps just note that they have the same format, rather than repeating everything?

Yeah, that'll help cut down on length, 👍

zellyn · 2017-04-26T17:28:57Z

cmd/dep/testdata/harness_tests/ensure/empty/case1/final/Gopkg.toml

+## can be used to require "main" packages.
+# required = ["github.com/user/thing/cmd/thing"]
+
+## "ignored" lists a set of packages (not projects) that are ignored when


s/ignored when/ignored completely when/

fortytw2 · 2017-04-26T18:56:00Z

cmd/dep/testdata/harness_tests/ensure/empty/case1/final/Gopkg.toml

+## Optional: an alternate location (URL or import path) for the project's source
+# source = "https://github.com/myfork/package.git"
+## Optional, but recommended: the version constraint to enforce for the project.
+## Only one of "branch", "version" or "revision" can be specified.
 # version = "1.0.0"


is this a constraint string like ">=0.4.0, <1.0.0" or a specific version it has to be? Might be helpful to briefly describe these in here, or add a second line to make this behavior clear

It can be either (though note that when #225 goes in, 1.0.0 will be interpreted as ^1.0.0). It can also specify an entirely non-semver tag for a literal match.

We need a more formal writeup of all of these rules. The examples here should really just be terse, and point to said writeup.

Injecting the comments at the bottom is suboptimal, as it means that additional dependencies injected by later `dep ensure` calls (under the new spec) will be separated from the original `init` set. This seems slightly annoying now, but once we add a flag to allow bypassing example injection, it'll be less of a problem.

adg · 2017-04-28T03:19:02Z

txn_writer.go

+const exampleTOML = `
+## EXAMPLES & DOCS - safe to delete!
+#
+## Dependencies define constraints on how dependent projects should be


Dependencies define constraints on dependent projects. The bit about Gopkg.lock is a bit jargony and I don't think it adds anything.

yeah that's fair, i was trying to make more of a distinction than we really needed

adg · 2017-04-28T03:19:25Z

txn_writer.go

-const exampleToml = `
-# Example:
+const exampleTOML = `
+## EXAMPLES & DOCS - safe to delete!


Example (these lines may be deleted)

adg · 2017-04-28T03:20:49Z

txn_writer.go

 # source = "https://github.com/myfork/package.git"
+## Optional, but recommended: the version constraint to enforce for the project.


Put the optional but recommended one above the optional one?

adg · 2017-04-28T03:21:20Z

txn_writer.go

 # branch = "master"
-# name = "github.com/vendor/package"
-# Note: revision will depend on your repository type, i.e git, svc, bzr etc...
+## Note: revision will depend on your repository type; git and hg have SHA1s,


This note is unnecessary IMO

adg · 2017-04-28T03:22:36Z

txn_writer.go

+#
+## Dependencies define constraints on how dependent projects should be
+## incorporated into Gopkg.lock. They are respected by dep whether
+## this project is the current project, or if it's a dependency.
 # [[dependencies]]


Perhaps each line should precede its documentation. It might be clearer that way.

# [[dependencies]] ## The dependencies section defines constraints ... # name = "..." ## The required name field specifies the root...

adg · 2017-04-28T03:24:47Z

txn_writer.go

 # revision = "abc123"
-# version = "1.0.0"
+#
+## [[overrides]] follow the exact same structure as [[dependencies]], but supercede


# [[overrides]]

??

yeah, restructuring this. I dropped the section overall because it's duplicative of [[dependencies]], but i'm re-adding it because the comment text should actually be different.

sdboyer · 2017-04-28T03:52:22Z

Reorganized and fleshed out the text a bit more. Had to put the required and ignored elements up top, or they're actually being grouped in with the previous table array elem.

adg · 2017-04-28T04:02:52Z

txn_writer.go

-const exampleToml = `
-# Example:
+const exampleTOML = `
+## EXAMPLE (these lines may be deleted)


Can we please not shout? :-)

adg · 2017-04-28T04:03:26Z

txn_writer.go

+## project. Use it when your project needs a package it doesn't explicitly import -
+## including "main" packages.
+# required = ["github.com/user/thing/cmd/thing"]
+#


single blank please

Heh, I introduced these to try to visually delineate between the groups of items, but now that their ordering is actually correct, can just rely on...yknow, TOML's rules 😄

adg · 2017-04-28T04:06:44Z

txn_writer.go

+const exampleTOML = `
+## EXAMPLE (these lines may be deleted)
+#
+## "required" lists a set of packages (not projects) that must be included in


What I was suggesting in the previous round of comments was that the docs should be after the thing they document, which I know is different to how it works in Go code, but in this case we're looking at a config example so I think it makes some kind of sense.

I can see how that makes sense with the [[dependencies]], where it looks more or less like a section header. But with I think it'd be more confusing to do that on individual values. I can't think of a commented config file I've seen that puts descriptive docs below the values they describe.

adg · 2017-04-28T04:07:22Z

txn_writer.go

+## Dependencies define constraints on dependent projects. They are respected by
+## dep whether coming from the Gopkg.toml of the current project or a dependency.
+#
+## Required: the root import path of the project being constrained.


It's easier to read if this is just an actual sentence.

The required name field specifies the root import path...

Fair point - I'll see if I can rework the others, then. Mostly, I care about consistency

sdboyer · 2017-04-28T12:54:13Z

@adg @fortytw2 @zellyn thanks for review!

Expand example Gopkg.toml text; always add on init

googlebot added the cla: yes label Apr 26, 2017

Expand example Gopkg.toml text; always add on init

ad41001

sdboyer force-pushed the expand-examples branch from f3da373 to ad41001 Compare April 26, 2017 05:13

sdboyer mentioned this pull request Apr 26, 2017

Generate initial manifest with examples #343

Closed

zellyn approved these changes Apr 26, 2017

View reviewed changes

zellyn reviewed Apr 26, 2017

View reviewed changes

fortytw2 reviewed Apr 26, 2017

View reviewed changes

sdboyer force-pushed the expand-examples branch from 3be598e to 1b707ca Compare April 28, 2017 01:58

Trim out/tighten up examples text

f4079c9

sdboyer force-pushed the expand-examples branch from 1b707ca to f4079c9 Compare April 28, 2017 02:00

sdboyer mentioned this pull request Apr 28, 2017

Add -no-examples flag to init #472

Closed

adg reviewed Apr 28, 2017

View reviewed changes

Polish text some more

99f7861

adg reviewed Apr 28, 2017

View reviewed changes

More tweaks based on review

f861939

sdboyer force-pushed the expand-examples branch from bec2f35 to f861939 Compare April 28, 2017 05:15

adg approved these changes Apr 28, 2017

View reviewed changes

sdboyer merged commit 11b52a3 into golang:master Apr 28, 2017

carolynvs mentioned this pull request May 5, 2017

Remove unused function #524

Merged

ibrasho pushed a commit to ibrasho-forks/dep that referenced this pull request May 10, 2017

Merge pull request golang#462 from sdboyer/expand-examples

b00ab96

Expand example Gopkg.toml text; always add on init

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Expand example Gopkg.toml text; always add on init #462

Expand example Gopkg.toml text; always add on init #462

sdboyer commented Apr 26, 2017

zellyn left a comment

zellyn Apr 26, 2017

sdboyer Apr 26, 2017

zellyn Apr 26, 2017

sdboyer Apr 26, 2017

zellyn Apr 26, 2017

fortytw2 Apr 26, 2017

sdboyer Apr 26, 2017

adg Apr 28, 2017

sdboyer Apr 28, 2017

adg Apr 28, 2017

adg Apr 28, 2017

sdboyer Apr 28, 2017

adg Apr 28, 2017

sdboyer Apr 28, 2017

adg Apr 28, 2017

adg Apr 28, 2017

sdboyer Apr 28, 2017

sdboyer commented Apr 28, 2017 •

edited

Loading

adg Apr 28, 2017

adg Apr 28, 2017

sdboyer Apr 28, 2017

adg Apr 28, 2017

sdboyer Apr 28, 2017

adg Apr 28, 2017

sdboyer Apr 28, 2017

sdboyer commented Apr 28, 2017

		# revision = "abc123"

		## Overrides have the same structure as [[dependencies]], but supercede all

		# source = "https://github.com/myfork/package.git"
		## Optional, but recommended: the version constraint to enforce for the project.

Expand example Gopkg.toml text; always add on init #462

Expand example Gopkg.toml text; always add on init #462

Conversation

sdboyer commented Apr 26, 2017

zellyn left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Example (these lines may be deleted)

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sdboyer commented Apr 28, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sdboyer commented Apr 28, 2017

sdboyer commented Apr 28, 2017 •

edited

Loading