CI configuration docs cleanup

- delete obsolete docs
- link to the new contribution docs from few places
- warn about tempaltes being legacy

Author: petr-muller

ALERTS.md

@@ -1,4 +1,16 @@
-Contributing documentation is maintained [here][ci-tools-webreg] and served [here][webreg-production].
+# Contributing to `openshift/release`
 
+[Contributing documentation][openshift-release-contributing] is served (together
+with other documentation related to CI) on [steps.ci.openshift.org][steps].
+It is maintained in the [ci-tools][ci-tools-webreg] repository.
+
+## Useful shortcuts
+
+- [Pull Requests to openshift/release][orc-reviews]
+- [Adding CI Configuration for New Repositories][orc-newrepos]
+
+[openshift-release-contributing]: https://steps.ci.openshift.org/help/release
+[orc-reviews]: https://steps.ci.openshift.org/help/release#reviews
+[orc-newrepos]: https://steps.ci.openshift.org/help/release#new-repos
 [ci-tools-webreg]: https://github.com/openshift/ci-tools/blob/master/pkg/webreg
-[webreg-production]: https://steps.svc.ci.openshift.org/
+[steps]: https://steps.ci.openshift.org/

CONTRIBUTING.md

@@ -6,31 +6,30 @@ OCP.
 
 ## CI Workflow Configuration
 
-To setup a CI workflow for a new repository, use `make new-repo`.
+To setup a CI workflow for a new repository, use `make new-repo`. See the
+[Contributing CI Configuration to the openshift/release Repository](https://steps.ci.openshift.org/help/release)
+document for detailed information about how to contribute to this repository.
 
 Configuration files for CI workflows live under [`ci-operator/`](./ci-operator/)
 and are split into the following categories:
 
  - [`ci-operator/config`](./ci-operator/config/) contains configuration for the
-   `ci-operator`, detailing builds and tests for component repositories. See the
-   [contributing guide](./ci-operator/README.md) for details on how to configure
-   new repositories or tests.
+   `ci-operator`, detailing builds and tests for component repositories.
  - [`ci-operator/jobs`](./ci-operator/jobs/) contains configuration for `prow`,
-   detailing job triggers. In almost all cases, this configuration can be
+   detailing job triggers. In almost all cases, this configuration is
    generated automatically from the `ci-operator` config. For manual edits, see
-   the [upstream configuration document](https://github.com/kubernetes/test-infra/blob/master/prow/README.md#how-to-add-new-jobs)
-   for details on how to configure a job, but prefer the `ci-operator` config
-   whenever possible.
- - [`ci-operator/templates`](./ci-operator/templates/) contains black-box test
+   [this section](https://steps.ci.openshift.org/help/release#component-jobs)
+   of the contribution document and the [upstream configuration document](https://github.com/kubernetes/test-infra/blob/master/prow/README.md#how-to-add-new-jobs). Prefer the `ci-operator` config whenever possible.
+ - [`ci-operator/step-registry`](./ci-operator/step-registry/) contains the
+   registry of reusable test steps and workflows. See the documentation for
+   this content [here](https://steps.ci.openshift.org/help).
+ - **[LEGACY]** [`ci-operator/templates`](./ci-operator/templates/) contains black-box test
    workflows for use by the `ci-operator`. The parent directory's
    [README](./ci-operator#end-to-end-tests) documents how to use them. See the
    [template document](https://github.com/openshift/ci-tools/blob/master/TEMPLATES.md)
-   for general information on template tests.
- - [`ci-operator/infra`](./ci-operator/infra/) contains manifests for infrastructure
-   components used by the `ci-operator`. Contact a CI Administrator if you feel
-   like one of these should be edited. (**legacy**: do not add new services
-   here. Use [`core-services`](./core-services) or [`projects`](./projects)
-   instead.)
+   for general information on template tests. Templates are legacy and new
+   ones should not be added. Multi-stage tests using steps from the shared
+   registry should be used instead.
 
 ## Cluster and Service Configuration Manifests
 

README.md

@@ -13,7 +13,7 @@ ensure that your changes are compliant to our conventions and pass the CI tests
 that will run when you submit your changes as a PR:
 
 ```
-make jobs
+make update
 ```
 
 By default `CONTAINER_ENGINE` is set to `docker`, if preferred you can install
@@ -26,7 +26,7 @@ does not generate any new configuration.
 Conventions
 -----------
 
-Under this directory, we have three main directories:
+Under this directory, we have four main directories:
 
 *  `config/$org/$repo/$org-$repo-$branch.yaml`
    Contains your ci-operator definition which describes how the images and tests
@@ -40,16 +40,23 @@ Under this directory, we have three main directories:
    or periodically. When we branch jobs, we will copy the current master jobs into
    a release branch specific job. Each prow job calls into the appropriate subset
    of the tests defined in your ci-operator config and passes in the secrets and
-   infrastructure info specific to our CI environment
-*  `templates/*.yaml`
-   These templates are used for more complicated jobs that don't run in a single
+   infrastructure info specific to our CI environment.
+*  `step-registry`
+   Contains reusable test steps and workflows for multi-stage tests.
+*  **[LEGACY]** `templates/*.yaml`
+    These templates are used for more complicated jobs that don't run in a single
    pod. The templates are referenced by the Prow jobs and are instantiated by
    the ci-operator using parameters generated by the build (references to images
    usually).
 
+
 End-to-end tests
 ----------------
 
+> :warning: This section describes the legacy approach to end-to-end tests.
+> Whenever possible, the current *"multi-stage"* tests should be used instead.
+> You can find the documentation for multi-stage tests [here](https://steps.ci.openshift.org/help).
+
 This section describes how to configure end-to-end tests using ci-operator.  In
 this context, "end-to-end" means the functionality of the application is being
 tested on top of a Kubernetes cluster from an end-user perspective.

ci-operator/README.md

@@ -1,50 +1,3 @@
 # CI job rehearsals
 
-Pull requests to this repository that contain changes affecting Prow job setup
-trigger a so-called "rehearsal". Jobs that would be affected by a PR are
-executed as if run against a target component repository after job changes
-would be merged. This provides job config authors early feedback about how job
-config changes impact CI setup for a given repo.
-
-## How rehearsal works
-
-All pull requests trigger a `ci/prow/pj-rehearse` job, which detects the jobs
-affected by the proposed change. For each job selected for rehearsal (for
-various reasons, we are not able to rehearse all jobs), new Prowjob is
-dynamically created, reporting results via a GitHub context named with the
-`ci/rehearse/$org/$repo/$branch/$test` pattern. Both the "driver" job
-(`ci/prow/pj-rehearse`) and the actual rehearsals are optional, which means
-that their failures do not block Tide from merging the PR. The driver job waits
-for individual rehearsals to finish, and its own PASS/FAIL value depends on
-them: it will fail if at least one of the rehearsals did not succeed.
-
-## Which jobs are rehearsed
-
-At the moment, we are not able to rehearse all affected jobs for various
-reasons. Currently, we only rehearse `Presubmit` jobs affected by the
-following changes:
-
-1. Newly added presubmit jobs
-2. Presubmit jobs whose `spec:` field was changed
-3. Presubmit jobs whose `agent:` field was changed to `kubernetes` from a
-   different value
-
-These jobs are then further filtered to exclude jobs where some factor prevents
-us from reliably rehearsing them. Decisions about why a job was excluded from
-rehearsing are logged in the output of the `ci/prow/pj-rehearse` job. Most
-importantly, we are currently *not* rehearsing template-based jobs.
-
-## Rehearsal reruns
-
-It is not possible to re-run individual rehearsal jobs (they do not react to any
-trigger command themselves). Rerunning rehearsals must be always done by
-re-triggering the "driver" job (`ci/prow/pj-rehearse`), which then re-triggers
-each individual rehearsal job, including those that were passing before.
-
-## Future work
-In the near future, we would like to enlarge the set of jobs that are
-rehearsed. First, changes to several fields other that `spec:` should cause a
-rehearsal. Afterwards, we would like to enable rehearsing template-based jobs.
-Additionally, we want to consider for rehearsal even jobs that are affected by
-a change *indirectly*, e.g., by a change of an underlying ci-operator config
-file, template or other asset used by the job.
+The documentation for rehearsals was moved [here](https://steps.ci.openshift.org/help/release#rehearsals).