Skip to content

Contributing to the Site

Jump to bottom
Rob A edited this page Oct 15, 2019 · 10 revisions

Changes are automatically deployed when they are merged into the master branch. We use a release branch to collect doc PRs that can't be pushed until the next release. If you have changes that don't need to wait until the next release, use the All Other Content process.

Note: All changes must be merged into the master branch to be published.

Prerequisites

The following instructions assume that you have already installed all of the required software.

Release-Related Content

Use these steps to add your changes related to a scheduled Monolith release.

Create a Release Branch

Note: These steps assume that a release branch has not already been created. If it has, skip to step Create a Working Branch off of the Release Branch.

Create a new branch for the release using the Monthly Release Plan Calendar to name the release. For example, a monthly release branch might be named release-2019.04.0 and a weekly release branch might be named release-2019.04.1.

Note: Make sure that there isn't an existing release branch already.

  1. Ensure that your local master branch is up-to-date with remote:
  [okta-developer-docs branch]$ git checkout master
  [okta-developer-docs master]$ git pull origin master
  1. Create the release branch:
   [okta-developer-docs master]$ git checkout -b release-branch-name

Create a Working Branch off of the Release Branch

Next you need to create your working branch for the changes that you want included in the release.

  1. In the terminal, switch to the release branch if you aren't already there and make sure that you are up-to-date:
  [okta-developer-docs branch]$ git checkout release-branch-name
  [okta-developer-docs branch]$ git pull
  1. Create a working branch from the release branch.
  [okta-developer-docs branch]$ git checkout -b working-branch-name

  1. Make your changes inside the packages/@okta/vuepress-site/ directory.

  2. Confirm that VuePress builds a local version of the site by running yarn dev and then navigating to http://localhost:8080/docs/. Check your changes.

   [okta-developer-docs branch]$ yarn dev

Push the Working Branch to GitHub

After you are finished with your changes and confirmed that all is working and looking the way that it should locally, push your branch.

   [okta-developer-docs branch]$ git add .
   [okta-developer-docs branch]$ git status (make sure only what you changed is included in your commit)
   [okta-developer-docs branch]$ git commit -m "what you did"
   [okta-developer-docs branch]$ git push -u origin working-branch-name

Create a PR Against the Release Branch in GitHub

In GitHub, create a PR against the release branch.

  1. Click New Pull Request or Create Pull Request.
  2. Select base: release-branch-name and then compare: working-branch-name.
  3. Add your reviewers to the pull request.
  4. Assign the doc release label.
  5. Click Create PR.
  6. Confirm that you only see the expected changes and that all the tests pass.

All Other Content

Content not related to a release is merged in to the master branch. About fifteen minutes after it's merged, it's live on developer.okta.com (deployed via CI).

  1. Fetch latest from origin and create a new topic branch off of master:

    [okta-developer-docs branch]$ git checkout master
[okta-developer-docs master]$ git fetch origin
[okta-developer-docs master]$ git merge origin/master
[okta-developer-docs master]$ git checkout -b my-branch

  2. Make your changes inside the packages/@okta/vuepress-site/ directory.

  3. Confirm that VuePress builds a local version of the site by running yarn dev and then navigating to http://localhost:8080/docs/. Check your changes.

  4. After you are happy with your changes, commit them, push the branch.

    [okta-developer-docs branch]$ git push -u origin my-branch

  5. Create a new Pull Request. Leave the base branch as master.

  6. Get it reviewed. When it passes the Travis test and is approved, it can be merged.

In case of problems with publication

If anything goes awry with publication, contact DevEx EEP.

Clone this wiki locally