Merge branch 'master' into contrib_pre-commit_hook

3 files changed, 140 insertions, 16 deletions

diff --git a/docs/best_practices_guide.adoc b/docs/best_practices_guide.adoc
index 7f3d85d40..dd849e87d 100644
--- a/docs/best_practices_guide.adoc
+++ b/docs/best_practices_guide.adoc
@@ -11,22 +11,6 @@ All new pull requests created against this repository MUST comply with this guid
 This guide complies with https://www.ietf.org/rfc/rfc2119.txt[RFC2119].
 
 
-== Pull Requests
-
-
-
-[[All-pull-requests-MUST-pass-the-build-bot-before-they-are-merged]]
-[cols="2v,v"]
-|===
-| <<All-pull-requests-MUST-pass-the-build-bot-before-they-are-merged, Rule>>
-| All pull requests MUST pass the build bot *before* they are merged.
-|===
-
-The purpose of this rule is to avoid cases where the build bot will fail pull requests for code modified in a previous pull request.
-
-The tooling is flexible enough that exceptions can be made so that the tool the build bot is running will ignore certain areas or certain checks, but the build bot itself must pass for the pull request to be merged.
-
-
 
 == Python
 
diff --git a/docs/pull_requests.md b/docs/pull_requests.md
new file mode 100644
index 000000000..953563fb2
--- /dev/null
+++ b/docs/pull_requests.md
@@ -0,0 +1,86 @@
+# Pull Request process
+
+Pull Requests in the `openshift-ansible` project follow a
+[Continuous](https://en.wikipedia.org/wiki/Continuous_integration)
+[Integration](https://martinfowler.com/articles/continuousIntegration.html)
+process that is similar to the process observed in other repositories such as
+[`origin`](https://github.com/openshift/origin).
+
+Whenever a
+[Pull Request is opened](../CONTRIBUTING.md#submitting-contributions), some
+automated test jobs must be successfully run before the PR can be merged.
+
+Some of these jobs are automatically triggered, e.g., Travis and Coveralls.
+Other jobs need to be manually triggered by a member of the
+[Team OpenShift Ansible Contributors](https://github.com/orgs/openshift/teams/team-openshift-ansible-contributors).
+
+## Triggering tests
+
+We have two different Jenkins infrastructures, and, while that holds true, there
+are two commands that trigger a different set of test jobs. We are working on
+simplifying the workflow towards a single infrastructure in the future.
+
+- **Test jobs on the older infrastructure**
+
+  Members of the [OpenShift organization](https://github.com/orgs/openshift/people)
+  can trigger the set of test jobs in the older infrastructure by writing a
+  comment with the exact text `aos-ci-test` and nothing else.
+
+  The Jenkins host is not publicly accessible. Test results are posted to S3
+  buckets when complete, and links are available both at the bottom of the Pull
+  Request page and as comments posted by
+  [@openshift-bot](https://github.com/openshift-bot).
+
+- **Test jobs on the newer infrastructure**
+
+  Members of the
+  [Team OpenShift Ansible Contributors](https://github.com/orgs/openshift/teams/team-openshift-ansible-contributors)
+  can trigger the set of test jobs in the newer infrastructure by writing a
+  comment containing `[test]` anywhere in the comment body.
+
+  The [Jenkins host](https://ci.openshift.redhat.com/jenkins/job/test_pull_request_openshift_ansible/)
+  is publicly accessible. Like for the older infrastructure, the result of each
+  job is also posted to the Pull Request as comments and summarized at the
+  bottom of the Pull Request page.
+
+## Triggering merge
+
+After a PR is properly reviewed and a set of
+[required jobs](https://github.com/openshift/aos-cd-jobs/blob/master/sjb/test_status_config.yml)
+reported successfully, it can be tagged for merge by a member of the
+[Team OpenShift Ansible Contributors](https://github.com/orgs/openshift/teams/team-openshift-ansible-contributors)
+by writing a comment containing `[merge]` anywhere in the comment body.
+
+Tagging a Pull Request for merge puts it in an automated merge queue. The
+[@openshift-bot](https://github.com/openshift-bot) monitors the queue and merges
+PRs that pass all of the required tests.
+
+### Manual merges
+
+The normal process described above should be followed: `aos-ci-test` and
+`[test]` / `[merge]`.
+
+In exceptional cases, such as when known problems with the merge queue prevent
+PRs from being merged, a PR may be manually merged if _all_ of these conditions
+are true:
+
+- [ ] Travis job must have passed (as enforced by GitHub)
+- [ ] Must have passed `aos-ci-test` (as enforced by GitHub)
+- [ ] Must have a positive review (as enforced by GitHub)
+- [ ] Must have failed the `[merge]` queue with a reported flake at least twice
+- [ ] Must have [issues labeled kind/test-flake](https://github.com/openshift/origin/issues?q=is%3Aopen+is%3Aissue+label%3Akind%2Ftest-flake) in [Origin](https://github.com/openshift/origin) linked in comments for the failures
+- [ ] Content must not have changed since all of the above conditions have been met (no rebases, no new commits)
+
+This exception is temporary and should be completely removed in the future once
+the merge queue has become more stable.
+
+Only members of the
+[Team OpenShift Ansible Committers](https://github.com/orgs/openshift/teams/team-openshift-ansible-committers)
+can perform manual merges.
+
+## Useful links
+
+- Repository containing Jenkins job definitions: https://github.com/openshift/aos-cd-jobs
+- List of required successful jobs before merge: https://github.com/openshift/aos-cd-jobs/blob/master/sjb/test_status_config.yml
+- Source code of the bot responsible for testing and merging PRs: https://github.com/openshift/test-pull-requests/
+- Trend of the time taken by merge jobs: https://ci.openshift.redhat.com/jenkins/job/merge_pull_request_openshift_ansible/buildTimeTrend
diff --git a/docs/repo_structure.md b/docs/repo_structure.md
new file mode 100644
index 000000000..693837fba
--- /dev/null
+++ b/docs/repo_structure.md
@@ -0,0 +1,54 @@
+# Repository structure
+
+### Ansible
+
+```
+.
+├── inventory           Contains dynamic inventory scripts, and examples of
+│                       Ansible inventories.
+├── library             Contains Python modules used by the playbooks.
+├── playbooks           Contains Ansible playbooks targeting multiple use cases.
+└── roles               Contains Ansible roles, units of shared behavior among
+                        playbooks.
+```
+
+#### Ansible plugins
+
+These are plugins used in playbooks and roles:
+
+```
+.
+├── ansible-profile
+├── callback_plugins
+├── filter_plugins
+└── lookup_plugins
+```
+
+### Scripts
+
+```
+.
+├── bin                 [DEPRECATED] Contains the `bin/cluster` script, a
+│                       wrapper around the Ansible playbooks that ensures proper
+│                       configuration, and facilitates installing, updating,
+│                       destroying and configuring OpenShift clusters.
+│                       Note: this tool is kept in the repository for legacy
+│                       reasons and will be removed at some point.
+└── utils               Contains the `atomic-openshift-installer` command, an
+                        interactive CLI utility to install OpenShift across a
+                        set of hosts.
+```
+
+### Documentation
+
+```
+.
+└── docs                Contains documentation for this repository.
+```
+
+### Tests
+
+```
+.
+└── test                Contains tests.
+```