Improve doc!

[pmorie]

We should have:

• goals
• how to develop
• how to rebase!

[carolynvs]

Previously I had copied the files from this repo into my existing one. Now I am starting over, with the idea that I will rebase to keep in sync. Quickly realized that rebase isn't going to work with my own project goals because I wanted to:

• Change the name of the cmd/servicebroker directory to cmd/
• Change the package name to match my project's name
• Tweak image/Dockerfile with a different base image (alpine) and again change the binary name
• I don't use openshift, not sure if keeping it is helpful for someone who wants to use this on openshift? If that's the case, I'd want to change the name of all the resources in that manifest to something other than "osb-starter-pack"
• Completely different README, along with changes to travis.yaml, Gopkg.* and makefile, etc

I think with the amount of files that I'd be changing/renaming, it would be easier to consume upstream changes with merges instead. My gut says that will be less work for me to manage the inevitable conflicts that arise, better tracking of renames, etc. I'll update this comment with how that goes and share what workflow ends up working for me. 😀

[carolynvs]

Alternatively, have you considered making this a library + a starter repo? That way you could make all sorts of changes to the library without worrying about merge conflicts, and people could continue to use the starter repo as a jumping off point, but there would be no expectation that they would avoid modifying any of the files in that starter repo.

[lilic]

Alternatively, have you considered making this a library + a starter repo?

@carolynvs Yes, it was something I was thinking about as well. We could, if possible have the rest and broker pkgs in a separate repo, and leave all the other things in this repo as an example in a similar way as they do in the k8s sample-controller.

There needs to be one small change to separate the user dependancy in the rest pkg, but that is easy enough, see here -> e909008.

@pmorie If you agree with the above, could those pkgs be something that could be incorporated into the go-open-service-broker-client?

[pmorie]

I would rather not put tools for building a broker directly into the client, how about layering into a broker library and then consuming that here? Is that getting too complex? Maybe I should think about this a little further.

[lilic]

how about layering into a broker library and then consuming that here?

That sgtm as well. Think having a broker lib will make it easier to change things, as @carolynvs mentioned above.