= 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.

.Prerequisites

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

. Fork and clone the https://github.com/openshift/release repository to `$HOME/release` and create a new branch.
+
[NOTE]
====
If you have already forked the repository, make sure 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 main
git fetch upstream
git rebase upstream/main
git checkout <your_new_branch> <1>
----
<1> Replace `<your_new_branch>` with an appropriate branch name.
====
. On MacOS, you must install the `gettext` package.
+
[source,terminal]
----
brew install gettext
brew link --force gettext
----

.Procedure

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

. Switch to you `openshift-docs` directory.

. Check out the `main` branch, fetch from upstream, and rebase against upstream.

. Create the new branch config by running the `add-new-prow-config.sh` script passing the `$VERSION`, `$BRANCH` and `$DISTROS` variables, for example:
+
[source,terminal]
----
./scripts/prow/add-new-prow-config.sh 4.15 enterprise-4.15 "openshift-enterprise openshift-rosa openshift-rosa-hcp 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`, `openshift-rosa-hcp`, 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`, `openshift-rosa-hcp`, 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] `main` 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/main/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]
