create_or_edit_content.adoc

Create content or edit existing content

• Before you begin
• Understanding the contribution workflow
• Ensure your local repository is in sync with the remote
• Add content or update existing content on local branch
• Submit PR to merge your work
• Confirm your changes have been merged
• Add changes to an existing PR, if required
• Delete the local feature branch

Before you begin

Before you create or edit content:

• Read and review the Contribute to OpenShift documentation topic to understand some basics

• Install and set up the tools and software required to contribute

• Read and review the Documentation guidelines topic to understand the basic guidelines for consistency

Understanding the contribution workflow

The following diagram outlines the steps required to add content to the OpenShift documentation:

After you have identified a documentation requirement and created a ticket, you can contribute to the documentation directly or the OpenShift Docs team can create the content.

When you contribute content directly, you must create a feature branch in a local clone of your own fork of the openshift-docs repository. After gathering stakeholder input and completing your technical testing, you can develop your documentation draft in your local feature branch. For more information about working with feature branches, see the GitHub documentation. By using AsciiBinder on your local machine, you can create a local preview to review your updates.

To submit your content for review, you must push your local feature branch to your openshift-docs fork on GitHub and create a pull request (PR). The PR is a request for the updates in your feature branch on your fork to be merged into the relevant branch in the mainstream openshift-docs repository. In the Open a pull request dialog, you can add a description, review the content updates, and create the PR. After your PR is created, the Netlify bot automatically generates a preview build and provides a preview link in a PR comment.

The OpenShift Docs team reviews the PR and the Netlify preview build. The team also requests reviews from Quality Engineering (QE), subject matter experts (SMEs), and others, depending on the content that is submitted. You can apply any suggested changes by updating the original commit in your local feature branch. If you have multiple commits in your PR, you must squash them into one commit. After you push the additional updates to your fork, the PR and the Netlify preview are updated automatically.

When all of the required approvals are in place, the OpenShift Docs team merges the PR and cherry picks the content to the relevant branches. When the PR is merged and cherry picked, the content is automatically published after a short while. The OpenShift Docs team then checks the published content, add links in the documentation ticket, and closes the ticket to complete the request.

The following sections in this document provide detailed steps to create or edit OpenShift documentation content.

Ensure your local repository is in sync with the remote

Before you create a local feature branch, it is good practice to ensure that your local source branch is in sync with the remote and that you have all the latest changes. You must also ensure that your forked repository is also in sync with the remote repository.

Note	Because most changes in this repository must be committed to the main branch, the following process uses main as the name of the source branch. If you must use another branch as the source for your change, make sure that you consistently use that branch name instead of main.

1. From your local repository, make sure you have the main branch checked out:

   $ git checkout main

2. Fetch the current state of the OpenShift documentation repository:

   $ git fetch upstream

3. Incorporate the commits from the remote repository, in this case openshift/openshift-docs, into your local repository:

   $ git rebase upstream/main

4. Push the latest updates to your forked repository so that it is also in sync with the remote:

   $ git push origin main

Add content or update existing content on local branch

With your local and forked repositories in sync with the remote, you can now create a local feature branch where you will make all your updates, or create any new content.

Step 1: Create local feature branch

The following command creates a local feature branch from the branch that you are currently on, and checks it out automatically. Be sure to replace <feature_branch> with a suitable name. Also, be sure that the changes made on this branch are closely related. You must create separate PRs for bugfix changes (for an old or current release) and enhancement changes (for an upcoming new release).

$ git checkout -b <feature_branch>

Note	This command creates a new specified branch and also checks it out, so you will automatically switch to the new branch.

Step 2: Create content or update existing content as required

With the local feature branch created and checked out, you can now edit any content or start adding new content.

Ensure that any new file contains the required metadata as described in the documentation guidelines topic, including naming and title conventions.

Step 3: Add all of your changes to a pending commit

When you are finished making all of your changes, used asciibinder to build the updated or new content, and reviewed the rendered changes, run the following command to add those changes to a pending commit:

$ git add .

Step 4: Commit your changes

After adding your changes to a pending commit, run the following command to commit those changes locally:

$ git commit -am "Detailed comments about what changes were made; for example, fixed typo"

Step 5: Rebase updates from main into your feature branch

Remember that you must rebase against the branch that you created this feature branch from. In most cases, it will be the main branch for the 4.x stream.

$ git rebase upstream/main

Note	If you find any conflicts you must fix those, and repeat steps 3 and 4.

Step 6: Push all changes to your GitHub account

After you have rebased, fixed any conflicts, and committed your changes, you can push them to your GitHub account. This command adds your local feature branch to your GitHub repository:

$ git push origin <feature_branch>

Submit PR to merge your work

When you have pushed your changes to your GitHub account, you can submit a PR to have your work from your GitHub fork to the main branch of the OpenShift documentation repository. The documentation team will review the work, advise of any further changes that are required, and finally merge your work.

1. Go to your forked GitHub repository on the GitHub website, and you should see your feature branch that includes all of your work.

2. Click on Pull Request to submit the PR against the main branch of the openshift-docs repository.

3. Fill out the information requested on the template.

   • If you know which product versions your change applies to, include a comment that specifies the minimum version that the change applies to. The docs team maintains these branches for all active and future distros and your PR will be applied to one or more of these branches.

     • PR applies to all versions after a specific version (e.g. 4.8): 4.8+

     • PR applies to the in-development version (e.g. 4.12) and future versions: 4.12+

     • PR applies only to a specific single version (e.g. 4.10): 4.10

     • PR applies to multiple specific versions (e.g. 4.8-4.10): 4.8, 4.9, 4.10

   • Provide a link to the preview. Automatic preview functionality is currently only available for some branches. For PRs that update the rendered build in any way against branches that do not create an automated preview:

     • OpenShift documentation team members (core and aligned) must include a link to a locally generated preview.

     • External contributors can request a generated preview from the OpenShift documentation team.

   • All documentation changes that impact the meaning of the docs must be verified by a QE team associate before merging.

   • Provide any other information about the change that the docs team might need to understand it.

4. Make sure that you squash to one commit before submitting your PR.

5. Ask for review from the OpenShift docs team:

   • For community authors: Request a review by tagging @openshift/team-documentation or @kalexand-rh in a GitHub comment.

   • For Red Hat associates:

     • For normal peer requests, add a comment that contains this text: /label peer-review-needed

     • For normal merge review requests, add a comment that contains this text: /label merge-review-needed

     • For urgent peer review requests, ping @peer-review-squad requesting a review in the #forum-docs-review channel (CoreOS Slack workspace) and provide the following information:

       • A link to the PR.

       • The size of the PR that the GitHub bot assigns (ex: XS, S, M, L, XL).

       • Details about how the PR is urgent.

     • For urgent merge requests, ping @merge-review-squad in the #forum-docs-review channel (CoreOS Slack workspace).

     • Except for changes that do not impact the meaning of the content, QE review is required before content is merged.

Confirm your changes have been merged

When your PR has been merged into the main branch, you should confirm and then sync your local and GitHub repositories with the main branch.

1. On your workstation, switch to the main branch:

   $ git checkout main

2. Pull the latest changes from main:

   $ git fetch upstream

3. Incorporate the commits from the remote repository, in this case openshift/openshift-docs, into your local repository:

   $ git rebase upstream/main

4. After confirming in your rebased local repository that your changes have been merged, push the latest changes, including your work, to your GitHub account:

   $ git push origin main

Add changes to an existing PR, if required

In some cases you might have to make changes to a PR that you have already submitted. The following instructions describe how to make changes to an existing PR you have already submitted.

1. Commit whatever updates you have made to the feature branch by creating a new commit:

   $ git commit -am "Detailed message as noted earlier"

2. Rebase your PR and squash multiple commits into one commit. Before you push your changes in the next step, follow the instructions here to rebase and squash: https://github.com/edx/edx-platform/wiki/How-to-Rebase-a-Pull-Request

3. After you have rebased and squashed, push the latest updates to the local feature branch to your GitHub account.

   $ git push origin <feature_branch> --force

The --force flag ignores whatever is on the remote server and replaces everything with the local copy. You should now see the new commits in the existing PR. Sometimes a refresh of your browser may be required.

Delete the local feature branch

When you have confirmed that all of your changes have been accepted and merged, and you have pulled the latest changes on main and pushed them to your GitHub account, you can delete the local feature branch. Ensure you are in your local repository before proceeding.

1. Delete the local feature branch from your workstation.

   $ git branch -D <feature_branch>

2. Delete the feature branch from your GitHub account:

   $ git push origin :<feature_branch>