openshift-docs/contributing_to_docs/create_or_edit_content.adoc

[id="contributing-to-docs-create-or-edit-content"]
= Create content or edit existing content
:icons:
:toc: macro
:toc-title:
:toclevels: 1
:description: Create working branch to contribute new content or updates

toc::[]

== Before you begin
Before you create or edit content:

* Read and review the link:contributing.adoc[Contribute to OpenShift documentation]
topic to understand some basics
* link:tools_and_setup.adoc[Install and set up the tools and software]
required to contribute
* Read and review the link:doc_guidelines.adoc[Documentation guidelines] topic
to understand the basic guidelines for consistency

== Ensure your local repository is in sync with the remote
Before you create a local working 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 `master`
branch, the following process always uses `master` 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 `master`
====

1. From your local repository, make sure you have the `master` branch checked
out:
+
----
$ git checkout master
----

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/master
----

4. Push the latest updates to your forked repository so that it is also in sync
with the remote:
+
----
$ git push origin master
----

== 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 working branch where you will make all your updates, or create
any new content.

*Step 1:* Create local branch

The following command creates a new local branch from the branch that you are currently on, and checks it out
automatically. Be sure to replace `<working_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 <working_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 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 link:doc_guidelines.adoc[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 `master` into your working branch

Remember that you must rebase against the branch that you created this working
branch from. In most cases, it will be the master branch.

----
$ git rebase upstream/master
----

[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 working branch to
your GitHub repository:

----
$ git push origin <working_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 `master` 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 local branch that includes all of your work.
2. Click on *Pull Request* to submit the PR against the `master` branch of the
`openshift-docs` repository.
3. 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 these.
4. Tag the documentation team with @openshift/team-documentation.

== Confirm your changes have been merged
When your PR has been merged into the `master` branch, you should confirm and
then sync your local and GitHub repositories with the `master` branch.

1. On your workstation, switch to the `master` branch:
+
----
$ git checkout master
----

2. Pull the latest changes from `master`:
+
----
$ git fetch upstream
----

3. Incorporate the commits from the remote repository, in this case
`openshift/openshift-docs`, into your local repository:
+
----
$ git rebase upstream/master
----

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 master
----

== 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 working 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
working branch to your GitHub account.
+
----
$ git push origin <working_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 working branch
When you have confirmed that all of your changes have been accepted and merged,
and you have pulled the latest changes on `master` and pushed them to your
GitHub account, you can delete the local working branch. Ensure you are in your
local repository before proceeding.

1. Delete the local working branch from your workstation.
+
----
$ git branch -D <working_branch>
----

2. Delete the working branch from your GitHub account:
+
----
$ git push origin :<working_branch>
----