Preparing for a Package Rename

Dec 9, 2017 • Jonathan Hall

When I first wrote Kivik, I put everything into a single package. The core library, the CouchDB and PouchDB drivers, and the experimental features I was working on: A server, Memory driver, etc. This lead to quite a bloated package, with a majority of the bloat being irrelevant to most users of the package.

In August, I began the process of splitting the package into its individual components. At the same time, I created a new GitHub organization to organize all the Kivik-related packages. This transition is now nearly complete, with only one major step remaining: Moving the core Kivik library to the new organization.

I have been slow in making this transition, because I believe it stands a high chance of being painful for existing users of Kivik. Other Go projects have made similar changes in the past, sometimes with less than stellar results. I want to avoid similar problems.

To this end, the strategy I intend to employ is detailed below.

The plan

  1. The kivik package and all sub-packages will be pinned (via import comments) to the old repository name ( This step has already been completed.
  2. The kivik repo will then be renamed, to live under the new organization as At this point, GitHub will redirect requests (including from go get) for to the new package, but the import comments will continue to require that the package be referenced by the old name. I will make this change in the coming week or two.
  3. Subsequent releases of the 1.x series (to live in a new 1.x branch), if any, will retain the import comments pinning the package to the old namespace.
  4. The 2.x.x release of Kivik, which I expect to be forthcoming shortly, will replace the import comments to tag the repo to the new namespace of

This should allow me to couple the effectual package rename to the Kivik 2.x release, which will include other breaking changes.

Once the 2.x work begins, consumers of Kivik will be required to use vendoring, ideally with a semver-aware versioning tool such as dep or glide. But I think this is a reasonable assumption for any modern, production Go code.


Moving forward, users of Kivik 1.x will continue to use as their import path, even after the package rename.

Users of Kivik 2.x will use the new import path of


If there are questions or comments about this, I encourage you to send your feedback or suggestions by submitting an issue on GitHub.