Skip to content

Commit

Permalink
Add missing rebase step & cleanup create_or_edit_content
Browse files Browse the repository at this point in the history
  • Loading branch information
@adellape
adellape committed Dec 9, 2015
1 parent e7ea761 commit 625c62f
Showing 1 changed file with 100 additions and 33 deletions.
133 changes: 100 additions & 33 deletions contributing_to_docs/create_or_edit_content.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,14 +10,21 @@ toc::[]
== Before you begin
Before you proceed, we recommend that you have completed the following:

* Read and reviewed the link:contributing.adoc[Contribute to OpenShift documentation] topic to understand some basics
* link:tools_and_setup.adoc[Installed and set up the tools and software] required to contribute
* Read and reviewed the link:doc_guidelines.adoc[Documentation guidelines] topic to understand the basic guidelines for consistency
* Read and reviewed the link:contributing.adoc[Contribute to OpenShift
documentation] topic to understand some basics
* link:tools_and_setup.adoc[Installed and set up the tools and software]
required to contribute
* Read and reviewed 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 `master` 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.
Before you create a local working branch, it is good practice to ensure that
your local `master` 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.

1. From your local repository, make sure you have the `master` branch checked out:
1. From your local repository, make sure you have the `master` branch checked
out:
+
----
$ git checkout master
Expand All @@ -29,81 +36,120 @@ $ git checkout master
$ git fetch upstream
----

3. Push the latest updates to your forked repository so that it is also in sync with the remote:
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 new topics 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.
== Add new topics 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 and checks it out automatically. Be sure to replace <working_branch> with a suitable name.
The following command creates a new local branch and checks it out
automatically. Be sure to replace `<working_branch>` with a suitable name.

----
$ 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.
====
This command creates a new specified branch and also checks it out, so you will
automatically switch to the new branch.
====

*Step 2:* Create new 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.
With the local branch created and checked out, you can now edit any content, or
start adding new content.

If you are creating a new topic, it is best to use the topic templates so that all of the required metadata is included:
If you are creating a new topic, it is best to use the topic templates so that
all of the required metadata is included:

* For an Overview topic, use the https://github.com/openshift/openshift-docs/blob/master/contributing_to_docs/templates/overview_topic_template.adoc[Overview topic template].
* For revision history topics, use the https://github.com/openshift/openshift-docs/blob/master/contributing_to_docs/templates/rev_history.adoc[Revision History Template].
* For all other topics, use the https://github.com/openshift/openshift-docs/blob/master/contributing_to_docs/templates/topic_template.adoc[normal topic template].
* For an Overview topic, use the
https://github.com/openshift/openshift-docs/blob/master/contributing_to_docs/templates/overview_topic_template.adoc[Overview
topic template].
* For revision history topics, use the
https://github.com/openshift/openshift-docs/blob/master/contributing_to_docs/templates/rev_history.adoc[Revision
History Template].
* For all other topics, use the
https://github.com/openshift/openshift-docs/blob/master/contributing_to_docs/templates/topic_template.adoc[normal
topic template].

Otherwise, ensure that any new topic contains the required metadata as described in the link:doc_guidelines.adoc[documentation guidelines] topic, including naming and title conventions.
Otherwise, ensure that any new topic 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, and have tested the updated or new content, the following command adds those changes to a pending commit.
When you are finished making all of your changes, and have tested the updated or
new content, the following command adds those changes to a pending commit:

----
$ git add .
----

*Step 4:* Commit your changes

After adding your changes to a pending commit, the following command commits those changes locally.
After adding your changes to a pending commit, the following command commits
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

If you fetched the latest changes from `master` before you created your local branch, this step may not be necessary. However, it is good practice to fetch the latest changes from `master` and rebase those onto your working branch.
If you fetched the latest changes from `master` before you created your local
branch, this step may not be necessary. However, it is good practice to fetch
the latest changes from `master` and rebase those onto your working 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

when 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.
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, will advise of any further changes that may or may not be required, and finally 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 may or may not be 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.
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.

== 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.
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:
+
Expand All @@ -117,33 +163,55 @@ $ git checkout master
$ git fetch upstream
----

3. Push the latest changes, including your work, to your GitHub account:
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. A PR can contain multiple commits, and we strive to preserve the review history and all discussions that occur around those commits. 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:
In some cases you might have to make changes to a PR that you have already
submitted. A PR can contain multiple commits, and we strive to preserve the
review history and all discussions that occur around those commits. 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. To keep the Git history clean, you may be asked to 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: https://github.com/edx/edx-platform/wiki/How-to-Rebase-a-Pull-Request
2. To keep the Git history clean, you may be asked to 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:
https://github.com/edx/edx-platform/wiki/How-to-Rebase-a-Pull-Request

3. When you have rebased, push the latest updates to the local working branch to your GitHub account.
3. After you have rebased, 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 the browser may be required.
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.
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.
+
Expand All @@ -156,4 +224,3 @@ $ git branch -D <working_branch>
----
$ git push origin :<working_branch>
----

0 comments on commit 625c62f

Please sign in to comment.