Skip to content

Latest commit

 

History

History
235 lines (187 loc) · 8.16 KB

create_or_edit_content.adoc

File metadata and controls

235 lines (187 loc) · 8.16 KB
Raw

Create new content or edit existing content

Before you begin

Before you proceed, we recommend that you have completed the following:

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.

  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 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 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 and do indeed reflect that name. In particular, it is a good idea to use separate PRs for bugfix changes (for an old or current release) vs 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 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.

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

Otherwise, ensure that any new topic 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, 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:

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

Remember, that you should 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 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.

  3. Attach labels to your Pull Request to indicate to the DOCS team which branches your PR might apply to. Some requests may only apply to the origin distro (origin-only), and some may only apply to a specific version of the enterprise (branch/enterprise-3.4, branch/enterprise-3.5, branch/enterprise-3.6) or dedicated (branch/dedicated) or online (branch/online) docs. If a request applies to multiple versions of a distro, then specify the minimum version (branch/enterprise-3.5 and above, for example). 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.

If you don’t have permissions to apply labels, please make sure to leave that information as a comment.

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

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