openshift-docs/scripts/prow

= Creating Prow jobs for openshift-docs branches

Use the `add-new-prow-config.sh` script to populate the `$HOME/release/ci-operator/config/openshift/openshift-docs` directory with a new Prow job branch configuration.
The script uses the `./openshift-openshift-docs-BRANCH.yaml` template file to create the new job config.
After you create the job config, you run the CI make jobs to create the Prow jobs.
Then, open a pull request against the https://github.com/openshift/release repository to make the Prow job live for that branch.

To add a new job to Prow CI, do the following:

. Install link:https://podman.io/docs/installation[Podman].

. Fork and clone the https://github.com/openshift/release repository to `$HOME/release`.
+
[NOTE]
====
If you have already forked the repository, make sure it is it is up to date.
Run the following commands:

[source,terminal]
----
cd $HOME/release
git remote add upstream git@github.com:openshift/release.git
git checkout master
git fetch upstream
git rebase upstream/master
git checkout <your_new_branch> <1>
----
<1> Replace `<your_new_branch>` with an appropriate branch name.
====

. Create the new branch config by running the `add-new-prow-config.sh` script passing the `$VERSION`, `$BRANCH` and `$DISTROS` variables.
Open a shell prompt in the `openshift-docs/` directory, and run the script passing in the required variables, for example:
+
[source,terminal]
----
./scripts/prow/add-new-prow-config.sh 4.15 enterprise-4.15 "openshift-enterprise openshift-rosa openshift-dedicated microshift"
----
+
[NOTE]
====
Quote multiple distros to include them as a single item in the build config.
====
+
The script copies the new job YAML to the ci-operator config folder in the `$HOME/release` directory.
+
[IMPORTANT]
====
`openshift-rosa` and `openshift-osd` distros should be included in main, current, and future enterprise branch builds only.
When you add a new enterprise branch, remember to remove `openshift-rosa` and `openshift-osd` distros from the most recent enterprise branch.

For example, when the current version is 4.15, and you create a enterprise-4.16 branch, remove `openshift-rosa` and `openshift-osd` distros from the enterprise-4.15 branch build.
====
+
[NOTE]
====
You can optionally add an `openshift-docs-vale-review` and `openshift-docs-jira-links` test step to the `validate-asciidoc` job.
For more information, see link:https://steps.ci.openshift.org/job?org=openshift&repo=openshift-docs&branch=main&test=validate-asciidoc[openshift-docs test steps].
====

. Change to the `$HOME/release` directory and verify that the new build config has been added.
+
[source,text]
----
$HOME/release/ci-operator/config/openshift/openshift-docs/openshift-openshift-docs-enterprise-4.15.yaml
----

. Run the following commands from the root of the `$HOME/release` repository to generate the rest of the Prow build configuration:
+
[source,terminal]
----
make prow-config CONTAINER_ENGINE=podman WHAT=openshift/openshift-docs

make CONTAINER_ENGINE=podman ci-operator-config WHAT=openshift/openshift-docs

make jobs CONTAINER_ENGINE=podman WHAT=openshift/openshift-docs
----
+
Ensure that the `make` build target succeeds.

. Open a PR against the link:https://github.com/openshift/release[openshift/release] `master` branch.
Ensure that all Prow CI tests pass. Add a `/pj-rehearse` comment in the pull request to verify the new build.

. Get an `/lgtm` approval from someone in the openshift-docs link:https://github.com/openshift/release/blob/master/ci-operator/config/openshift/openshift-docs/OWNERS[OWNERS] file.

. When you want to schedule the job for merge, add a `/pj-rehearse ack` comment to the pull request.
The PR is merged automatically when all required approvals are provided and the PR passes all the required CI jobs.
When the PR is merged, the job goes live on the relevant openshift-docs branch PRs.
+
[NOTE]
====
Rebase often on the release branch when you open a pull request.
The repository is very busy and the underlying infrastructure changes daily.
Every time you rebase, rerun the CI make jobs.
====

For more information, see: link:https://docs.ci.openshift.org/docs/how-tos/contributing-openshift-release/[Contributing CI configuration to the openshift/release repository]