Skip to main content
This guide is for internal HashiCorp employees who need to create or update documentation for a product release before it ships.
If you need to create documentation for embargoed content—including product or conference announcements—use the private web-unified-docs-internal repository instead. Contact your team’s technical writer for guidance.

​
Which workflow to use

Minor or patch release

Use the upcoming minor release workflow when preparing documentation for the next minor or patch version (e.g., v1.21.0 or v1.20.3).

Major release

Use the upcoming major release workflow when preparing documentation for the next major version (e.g., v2.0.0), which typically introduces a new version folder.

​
Before you begin

Before contributing to release documentation, make sure:

​
Upcoming minor release

Each product’s tech writer team creates an assembly branch for the upcoming minor or patch release. Most products use the <product>/<exact_release_number> format. Vault uses vault/<YYYYMM>. Check with your team for the exact branch name.
1

Clone the release branch

Clone only the upcoming minor release branch to save space and time:
$ git clone --single-branch --branch <minor_branch_name> \
    [email protected]:hashicorp/web-unified-docs.git
For example, if the upcoming Vault minor release branch is vault/202511:
$ git clone --single-branch --branch vault/202511 \
    [email protected]:hashicorp/web-unified-docs.git
2

Create your working branch

Create a local working branch, following the branch naming conventions:
$ git checkout -b <working_branch_name>
3

Make your changes

Make your changes in the current release folder. If you need to create a new page, follow the Create a New Page guide.Content should adhere to the Education style guide.
4

Preview locally (optional)

From the web-unified-docs directory, run make to build the documentation site in Docker:
$ make
Wait for both the unified-devdot-api and dev-portal containers to complete before testing. Access the preview at http://localhost:3000.To stop:
$ make clean
5

Commit and push your changes

$ git commit -a -m "<short description about the changes>"
$ git push origin <working_branch_name>
6

Open a pull request against the release branch

Create a pull request targeting the upcoming minor release branch (not main). In the GitHub web UI’s base: dropdown, select the release branch you cloned in step one.Pull requests are automatically labeled and assigned to the product’s documentation team for review.
7

Merge after approval

After a technical writer approves your PR, merge it into the release assembly branch.The product tech writer team is responsible for merging the assembly branch into main as part of the minor/patch version release process.

​
Upcoming major release

For major releases, each product’s tech writer team creates both a release branch (<product>/<exact_release_number>) and the upcoming release version folder. Check with your team for the names of both.
1

Clone the major release branch

$ git clone --single-branch --branch <major_branch_name> \
    [email protected]:hashicorp/web-unified-docs.git
For example, if the upcoming Nomad major release branch is nomad/2.0.0:
$ git clone --single-branch --branch nomad/2.0.0 \
    [email protected]:hashicorp/web-unified-docs.git
2

Create your working branch

$ git checkout -b <working_branch_name>
3

Make your changes

Make your changes in the upcoming release folder created by your tech writer team. If you need to create a new page, follow the Create a New Page guide.
4

Preview locally (optional)

$ make
Access the preview at http://localhost:3000. Run make clean to stop.
5

Commit and push your changes

$ git commit -a -m "<short description about the changes>"
$ git push origin <working_branch_name>
6

Open a pull request against the major release branch

Create a PR targeting the upcoming major release branch. In the GitHub web UI’s base: dropdown, select the major release branch.
7

Merge after approval

After approval, merge into the release assembly branch.The product tech writer team is responsible for merging the major release branch as part of the major version release process.

​
Branch naming conventions

Follow these conventions when naming your personal working branch:
Contributor typeConventionExample
Community contributors<github_username>-<product_name>-<github_issue_number>aimeeu-nomad-12345
HashiCorp employees<name_initials_or_username>-<ticket_number>aimeeu-ce1001

​
FAQ

After your PR is open, find the Vercel Previews Deployed comment in the PR and click Visit Preview to see a preview of your changes.
Reach out to one of the approvers on your pull request or contact your product’s tech writing team directly.
Content appears on the live site approximately 10 minutes after your pull request is merged into main. Release assembly branches are merged to main by the tech writer team at the time of the product release.

Build docs developers (and LLMs) love

Get started for freeTalk to us