Update documentation to reflect default branch changes and GoPkg.in usage #13
Conversation
README.md
Outdated
| @@ -39,7 +61,7 @@ giving us both centralized and local logs. (Redundancy is nice). | |||
|
|
|||
| import ( | |||
| "flag" | |||
| "github.com/Graylog2/go-gelf/gelf" | |||
| gelf "gopkg.in/Graylog2/go-gelf/gelf.v1/gelf" | |||
There was a problem hiding this comment.
You should not need the gelf at the beginning as the last part of the path is gelf.
There was a problem hiding this comment.
As @0cjs mentioned, it should be gopkg.in/Graylog2/go-gelf.v1/gelf
|
The paths used here seem rather different from the [gopkg.in example(https://labix.org/gopkg.in): Especially, we have the part with the version number in the middle, and |
|
I've done a bit more poking around and found a list of the allegedly most popular "package management" tools for Go. (This doesn't cover anywhere near all of them, though.) The top five of these, godep, govendor, Glide, gvt and git-submodule, are all systems for "vendoring" dependencies using The survey doesn't mention the tool gopkg.in. But it seems whether gopkg.in or a vendor subdirectory (or something else) is used is completely the choice of the client of this library, right? So if we simply set up the sensible semantic-versioning branch names, we automatically offer support for both gopkg.in and these other tools. Is this correct? (Oh, and as an interesting side note to my research, it seems that packages that get imported by someone else should never have a vendor directory. This applies to us and I guess should be kept in mind if we ever introduce a dependency on another package.) |
|
I have updated the import path. @0cjs, you are right, supporting gopkg.in only involves using semantic-versioning branch or tag names. The other tools would already work as is. |
|
Thanks everyone! |
This PR changes the documentation to reflect changes to the branching strategy and GoPkg.in usage to enable versionning of the package. With some testing this morning, I was able to determine that we will have to use major version numbers whenever we change the public API, due to the behaviour of GoPkg.in.
GoPkg.in lets you only target a single number version (v1, v2, v3...) and that will target the latest version number in that specific major release. If you have v1.0.0 and v1.1.0, getting v1 from GoPkg.in will yield v1.1.0.
Once this PR is merged, we should immediately create a v1 branch from master, and update the project to use that as its default branch. This will let us merge PR #9 on master and then tag or branch that to v2.
After some time, I would suggest putting master back as the default branch, but doing that will break clients that have not migrated to the GoPkg.in import path, so we will probably have to wait a while.