Open questions around additional packages

[theacodes]

#137 introduced our second additional package. This raises some questions.

1. Should we continue to host them in this repo?

I think there is value in keeping these packages in this repository, but I can see argument for separating them into their own repositories. This would allow separate CI and simplify the release process for these libraries.

2. How should documentation be handled?

If we keep them here, should we roll-up their documentation into a special section in the google-auth documentation?

3. How should we handle releases?

If the packages stay here, how should we handle releases?

@dhermes I'd really like your input here, as you tackled a similar set of problems with google-cloud-python.

[theacodes]

(this is not a 1.0.0 blocker)

[dhermes]

I have found it both convenient and cumbersome to manage multiple packages in one place. For this set of packages, I see value in having them documented all at once.

As for releases, we just use tag names like pkgname-x.y.z and then manually parse the pkgname and the version x.y.z before upload. This isn't so bad, given you've already decided to host them in this repo. However, it completely hoses the concept of "stable" docs as far as RTD is concerned.

[theacodes]

I see value in having them documented all at once.

We can still do that if we separate the repositories with some sphinx magic. Also, intersphinx is pretty powerful, and the documentation around oauthlib is already well separated.

The tag stuff sounds reasonable, but I'm wondering if it's just more reasonable to have a separate repo.

We could also just have a google-auth-extras or google-auth-contrib package and that might simplify things, but that would force users to pull in the whole kitchen sync.

[dhermes]

I don't actually have a preference, though ISTM the most cogent argument for "one repo" is to have a single issue tracker.

[theacodes]

ISTM the most cogent argument for "one repo" is to have a single issue tracker.

Ah, I'm seeing that as an argument against one repo. I don't necessarily think I want issues related to httplib2 and oauthlib integration in this repo.

@lukesneeringer any thoughts?

[lukesneeringer]

I think there is value in keeping these packages in this repository, but I can see argument for separating them into their own repositories. This would allow separate CI and simplify the release process for these libraries.

I really (really, really, really) dislike the one-repository situation in google-cloud-python:

• It makes CI cumbersome.
  • CI has to test everything if anything is changed (there are advantages to this, too, but on the whole it just makes CI take longer and become less useful).
  • In order to make CI complete reasonably, we maintain short-circuiting logic which mostly makes CI behave as if it would in separate repos, except not as well.
• It makes installing development releases more difficult. pip install http://github.com/x/y/releases/master.zip no longer works. Right now, distributing private or public-but-unreleased code is a huge "problem we must solve", whereas if we had separate repositories it would be stupid simple.
• The single issue tracker is a hindrance, not a benefit. It is harder to find things in a sea of unrelated issues. Filtering helps but it would be better for them to be logically separate.

There are a few other reasons. My general advice is, "1:1 repos:packages". I wish I could change this on google-cloud-python (it would be an insane amount of work so I am hoping my CI changes are "good enough").

[theacodes]

Cool, looks like it's settled. I'll make separate repos. :)

[dhermes]

👍