Contributing to the Site

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.

Prerequisites

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

Regular 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. If your update is related to a monolith release (i.e. it should not go out until a specific version of Monolith is released) then mark it with the "docs release" Label in GitHub.

6. Get your PR reviewed. If you are a developer updating an API Reference page, have someone else from your team approve your PR. All PRs should also tag the okta/developerdocs team as a Reviewer.

In case of problems with publication

If anything goes awry with publication, contact DevEx EEP.

Release-Related Content (Dev Doc Team only)

Use these steps to as part of a Monolith-related doc 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

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

2. Create a working branch from the release branch.

  [okta-developer-docs branch]$ git checkout -b working-branch-name

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

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