From b192989d4271a0fad45cecb9c9da83d4b3814299 Mon Sep 17 00:00:00 2001 From: Matthew Wong Date: Wed, 19 Apr 2017 17:22:23 -0400 Subject: [PATCH] Add docs for contributing --- CONTRIBUTING.md | 4 +--- docs/README.md | 21 +++++++++++++++++++++ glide.lock | 4 ++-- glide.yaml | 2 ++ 4 files changed, 26 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fb8cf3e0c4b..effd3fd8590 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -21,6 +21,4 @@ Follow either of the two links above to access the appropriate CLA and instructi 1. Fork the desired repo, develop and test your code changes. 1. Submit a pull request. -### Adding dependencies - -If your patch depends on new packages, add that package with [`godep`](https://github.com/tools/godep). Follow the [instructions to add a dependency](https://github.com/kubernetes/kubernetes/blob/master/docs/devel/development.md#godep-and-dependency-management). +### See also the [Contributing](./docs/README.md#contributing) section of the docs for information on how this repo is structured, how to add a dependency, etc. diff --git a/docs/README.md b/docs/README.md index 402335060ba..85484c66dbd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,6 +6,7 @@ * [Authorizing provisioners for RBAC or OpenShift](#authorizing-provisioners-for-rbac-or-openshift) * [Running multiple provisioners and giving provisioners identities](#running-multiple-provisioners-and-giving-provisioners-identities) * [The code](../lib/controller) - being a library, the code is *supposed* to be well-documented -- if you find it insufficient, open an issue +* [Contributing](#contributing) ## Building provisioner programs and managing dependencies @@ -100,3 +101,23 @@ There is no such race to lock implementation for deleting PVs: all provisioners In some cases, the provisioner who is *responsible* for deleting a PV is also the only one *capable* of deleting a PV, in which case it's not only desirable to implement the identity idea, but necessary. This is the case with the `hostPath` provisioner example: obviously only the provisioner running on a certain host can delete the backing storage asset because the backing storage asset is local to the host. Now, actually giving provisioners identities and effectively making them pets may be the hard part. In the `hostPath` example, the sensible thing to do was tie a provisioner's identity to the node/host it runs on. In your case, maybe it makes sense to tie each provisioner to e.g. a certain member in a storage pool. And should a certain provisioner die, when it comes back it should retain its identity lest the cluster be left with dangling volumes that no running provisioner can delete. + +## Contributing + +This repository is structured such that each external provisioner gets its own directory for its code, docs, examples, yamls, etc. What they don't get is individual "vendor" directories for their respective dependencies, they must depend on the shared top-level vendor and lib directories. This helps reduce the size of the repo and forces all parts of it to stay updated, but introduces some complications for contributors. + +### Adding a provisioner + +Basically you create a directory to house everything you want to check in, add build and/or test invocations to [travis](../.travis.yml), and add dependencies to the top-level vendor directory. + +### Adding a vendor dependency + +This repository uses [glide](https://github.com/Masterminds/glide) for package management. Add the packages to [glide.yaml](../glide.yaml), run "glide up -v", then run "glide-vc --use-lock-file". + +### Updating a vendor dependency and/or contributing to the library + +Any breaking update to a vendor dependency requires an update to every external provisioner that depends on it. It follows that any breaking update to the library requires an update to every external provisioner. If the provisioners that need to be updated are not updated, they simply won't build. + +Generally, breaking vendor dependency updates won't happen often (at least every time kubernetes/client-go updates, maybe) and all the provisioners can be updated with ease, without requiring explicit approval from their respective OWNERS, unless the change is big enough or they've asked that it be required. + +As the contributor of a dependency/library update, you're usually responsible for updating the dependents so travis CI passes, as it shouldn't be harder than a find/replace. Otherwise, if it's decided that you don't need to be responsible, some other solution will be worked out to make sure everything stays in a buildable state. diff --git a/glide.lock b/glide.lock index 6467d9ff3b9..5d0f4505797 100644 --- a/glide.lock +++ b/glide.lock @@ -1,5 +1,5 @@ -hash: 953b6877593080ed4c55f894a86257de431de42ba46b31f58fa37e0afe8ff937 -updated: 2017-03-29T16:41:33.450818905-04:00 +hash: 70daa8fc9164edaf0d82d6e55256d6146bcabc78f035c49bca45ac7be5409efb +updated: 2017-04-19T16:28:08.383069633-04:00 imports: - name: github.com/aws/aws-sdk-go version: 6669bce73b4e3bc922ff5ea3a3983ede26e02b39 diff --git a/glide.yaml b/glide.yaml index 7d93de453c6..114bbde1890 100644 --- a/glide.yaml +++ b/glide.yaml @@ -1,4 +1,6 @@ package: github.com/kubernetes-incubator/external-storage +excludeDirs: +- nfs/test/e2e import: - package: github.com/aws/aws-sdk-go version: v1.7.3