This repo contains the IPsec documentation.
In this README:
The main branch is the tree-trunk, so always make changes you want carried forward in this branch. This includes:
- Unreleased features
- Doc bug fixes
- Doc reorganization or enhancement
Then, if necessary, immediately cherry-pick/copy any changes that you want to push immediately to production into the appropriate branches listed below:
Branch name | Use for… |
---|---|
master | doc in development, publishes to https://docs-staging.vmware.com/en/draft/IPsec-for-VMware-Tanzu/1.10/documentation/GUID-index.html |
1.9 | live doc, publishes to https://docs-staging.vmware.com/en/IPsec-for-VMware-Tanzu/1.9/documentation/GUID-index.html on stage and https://docs.vmware.com/en/IPsec-for-VMware-Tanzu/1.9/documentation/GUID-index.html on live site. |
1.8 | NOT IN USE (Published as PDF at https://docs.pivotal.io/archives/addon-ipsec-1.8.pdf) |
1.7 | NOT IN USE (Published as PDF at https://docs.pivotal.io/archives/addon-ipsec-1.7.pdf) |
1.6 | NOT IN USE (Published as PDF at https://docs.pivotal.io/archives/addon-ipsec-1.6.pdf) |
1.5 | NOT IN USE (Published as PDF at https://docs.pivotal.io/archives/addon-ipsec-1.5.pdf) |
Because main is the latest and greatest documentation, the process would be to cut a x.x branch for the version that main was targeting during that time.
After this point, main will then be the target for the next version of the IPsec product.
Cross-product partials (if any) for IPsec are single sourced from the Docs Partials repository.
If there is some documentation to add for an unreleased patch version of IPsec then create a branch off of the live branch you intend to modify and create a pull request against that branch. After the version that change is targeting is released, the pull request can be merged and will be live the next time a documentation deployment occurs.
If the documentation is meant to be target several released versions, then you will need to:
- create a pull request for each individual minor version
- or ask the technical writer to cherry-pick to particular branches/versions.
For instructions on how to create a pull request on a branch and instructions on how to create a pull request using a fork, see Creating a PR in the documentation team wiki.
- docworks is the main tool for managing docs used by writers.
- docsdash is a deployment UI which manages the promotion from staging to pre-prod to production. The process below describes how to upload our docs to staging, replacing the publication with the same version.
- Markdown files live in this repo.
- Images should live in an
images
directory at the same level and linked with a relative link. - Each page requires an entry in config/toc.md for the table of contents.
- Variables live in config/template_variables.yml.
-
Wait about 1 minute for processing to complete after uploading.
-
Go to https://docsdash.vmware.com/deployment-stage
There should be an entry with a blue link which says
Documentation
and points to staging.
Prerequisite Needs additional privileges - reach out to a manager on the docs team #tanzu-docs or ask a writer to do this step for you.
-
Go to Staging publications in docsdash
https://docsdash.vmware.com/deployment-stage -
Select a publication (make sure it's the latest version)
-
Click "Deploy selected to Pre-Prod" and wait for the pop to turn green (refresh if necessary after about 10s)
-
Go to Pre-Prod list
https://docsdash.vmware.com/deployment-pre-prod -
Select a publication
-
Click "Sign off for Release"
-
Wait for your username to show up in the "Signed off by" column
-
Select the publication again
-
Click "Deploy selected to Prod"
Problem | List displays as a paragraph |
---|---|
Symptom: | Bulleted or numbered lists look fine on GitHub but display as a single paragraph in HTML. |
Solution: | Add a blank line after the stem sentence and before the first item in the list. |
Problem | List numbering is broken: every item is 1. |
---|---|
Symptom: | Each numbered item in a list is a 1. instead of 1. , 2. , 3. , etc |
Solution: | Try removing any blank newlines within each step. |
Problem | Code boxes not showing |
---|---|
Symptom: | VMware publishing system doesn't accept code tags after the three back ticks. |
Solution: | Make sure you're not using shell or bash or console or yaml after back ticks. |
This is a word list for terminology and word usage specific to the IPsec docs.