From cacf5ae519caccc0a39d521d2352ec605be6216d Mon Sep 17 00:00:00 2001 From: Brendan Burns Date: Tue, 8 Sep 2015 11:16:14 -0700 Subject: [PATCH] Add some documentation describing out developer/repository automation. --- docs/devel/README.md | 2 + docs/devel/automation.md | 138 ++++++++++++++++++++++++++++++++++++ docs/devel/pull-requests.md | 6 ++ 3 files changed, 146 insertions(+) create mode 100644 docs/devel/automation.md diff --git a/docs/devel/README.md b/docs/devel/README.md index 267bca238a..756846ce0a 100644 --- a/docs/devel/README.md +++ b/docs/devel/README.md @@ -51,6 +51,8 @@ Guide](../admin/README.md). * **Getting Recent Builds** ([getting-builds.md](getting-builds.md)): How to get recent builds including the latest builds that pass CI. +* **Automated Tools** ([automation.md](automation.md)): Descriptions of the automation that is running on our github repository. + ## Setting up your dev environment, coding, and debugging diff --git a/docs/devel/automation.md b/docs/devel/automation.md new file mode 100644 index 0000000000..eb36cc6375 --- /dev/null +++ b/docs/devel/automation.md @@ -0,0 +1,138 @@ + + + + +WARNING +WARNING +WARNING +WARNING +WARNING + +

PLEASE NOTE: This document applies to the HEAD of the source tree

+ +If you are using a released version of Kubernetes, you should +refer to the docs that go with that version. + + +The latest 1.0.x release of this document can be found +[here](http://releases.k8s.io/release-1.0/docs/devel/automation.md). + +Documentation for other releases can be found at +[releases.k8s.io](http://releases.k8s.io). + +-- + + + + + +# Kubernetes Development Automation + +## Overview + +Kubernetes uses a variety of automated tools in an attempt to relieve developers of repeptitive, low +brain power work. This document attempts to describe these processes. + + +## Submit Queue + +In an effort to + * reduce load on core developers + * maintain e2e stability + * load test githubs label feature + +We have added an automated [submit-queue](https://github.com/kubernetes/contrib/tree/master/submit-queue) +for kubernetes. + +The submit-queue does the following: + +```go +for _, pr := range readyToMergePRs() { + if testsAreStable() { + mergePR(pr) + } +} +``` + +The status of the submit-queue is [online.](http://submit-queue.k8s.io/) + +### Ready to merge status + +A PR is considered "ready for merging" if it matches the following: + * it has the `lgtm` label, and that `lgtm` is newer than the latest commit + * it has passed the cla pre-submit and has the `cla:yes` label + * it has passed the travis and shippable pre-submit tests + * one (or all) of + * its author is in kubernetes/contrib/submit-queue/whitelist.txt + * its author is in contributors.txt via the github API. + * the PR has the `ok-to-merge` label + * One (or both of) + * it has passed the Jenkins e2e test + * it has the `e2e-not-required` label + +Note that the combined whitelist/committer list is available at [submit-queue.k8s.io](http://submit-queue.k8s.io) + +### Merge process + +Merges _only_ occur when the `critical builds` (Jenkins e2e for gce, gke, scalability, upgrade) are passing. +We're open to including more builds here, let us know... + +Merges are serialized, so only a single PR is merged at a time, to ensure against races. + +If the PR has the `e2e-not-required` label, it is simply merged. +If the PR does not have this label, e2e tests are re-run, if these new tests pass, the PR is merged. + +If e2e flakes or is currently buggy, the PR will not be merged, but it will be re-run on the following +pass. + +## Github Munger + +We also run a [github "munger"](https://github.com/kubernetes/contrib/tree/master/mungegithub) + +This runs repeatedly over github pulls and issues and runs modular "mungers" similar to "mungedocs" + +Currently this runs: + * blunderbuss - Tries to automatically find an owner for a PR without an owner, uses mapping file here: + https://github.com/kubernetes/contrib/blob/master/mungegithub/blunderbuss.yml + * needs-rebase - Adds `needs-rebase` to PRs that aren't currently mergeable, and removes it from those that are. + * size - Adds `size/xs` - `size/xxl` labels to PRs + * ok-to-test - Adds the `ok-to-test` message to PRs that have an `lgtm` but the e2e-builder would otherwise not test due to whitelist + * ping-ci - Attempts to ping the ci systems (Travis/Shippable) if they are missing from a PR. + * lgtm-after-commit - Removes the `lgtm` label from PRs where there are commits that are newer than the `lgtm` label + +In the works: + * issue-detector - machine learning for determining if an issue that has been filed is a `support` issue, `bug` or `feature` + +Please feel free to unleash your creativity on this tool, send us new mungers that you think will help support the Kubernetes development process. + +## PR builder + +We also run a robotic PR builder that attempts to run e2e tests for each PR. + +Before a PR from an unknown user is run, the PR builder bot (`k8s-bot`) asks to a message from a +contributor that a PR is "ok to test", the contributor replies with that message. Contributors can also +add users to the whitelist by replying with the message "add to whitelist" ("please" is optional, but +remember to treat your robots with kindness...) + +If a PR is approved for testing, and tests either haven't run, or need to be re-run, you can ask the +PR builder to re-run the tests. To do this, reply to the PR with a message that begins with `@k8s-bot test this`, this should trigger a re-build/re-test. + + +## FAQ: + +#### How can I ask my PR to be tested again for Jenkins failures? + +Right now you have to ask a contributor (this may be you!) to re-run the test with "@k8s-bot test this" + +### How can I kick Shippable to re-test on a failure? + +Right now the easiest way is to close and then immediately re-open the PR. + + +[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/devel/automation.md?pixel)]() + diff --git a/docs/devel/pull-requests.md b/docs/devel/pull-requests.md index a81c01c57d..a187920e9d 100644 --- a/docs/devel/pull-requests.md +++ b/docs/devel/pull-requests.md @@ -61,6 +61,12 @@ There are several requirements for the submit queue to work: Additionally, for infrequent or new contributors, we require the on call to apply the "ok-to-merge" label manually. This is gated by the [whitelist](https://github.com/kubernetes/contrib/tree/master/submit-queue/whitelist.txt). +Automation +---------- + +We use a variety of automation to manage pull requests. This automation is described in detail +[elsewhere.](automation.md) + [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/devel/pull-requests.md?pixel)]()