This repo contains the On-Demand Services SDK 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 |
---|---|
main | Unreleased v0.46 |
v0.45 | Staging and Prod |
v0.44 | Staging and Prod |
v0.43.x | Staging and Prod |
v0.42.x | Staging and Prod |
v0.41.x | Out of support. PDF only |
v0.40.x | Out of support. PDF only |
v0.39.x | Out of support. PDF only |
v0.38.x | Out of support. PDF only |
v0.37.x | Out of support. PDF only |
v0.36.x | Out of support. PDF only |
v0.35.x | Out of support. PDF only |
v0.34.x | Out of support. PDF only |
v0.33.x | Out of support. PDF only |
v0.32.x | Out of support. PDF only |
v0.31.x | Out of support. PDF only |
v0.30.x | Out of support. PDF only |
v0.29.x | Out of support. PDF only |
v0.28.x | Out of support. PDF only |
v0.27.x | Out of support. PDF only |
v0.26.x | Out of support. PDF only |
v0.25.x | Out of support. PDF only |
v0.24.x | Out of support. PDF only |
v0.23.x | Out of support. PDF only |
v0.22.x | Out of support. PDF only |
v0.21.x | Out of support. PDF only |
v0.20.x | obsolete, but do not delete the branch. PDF only |
v0.19.x | obsolete, but do not delete the branch. PDF only |
v0.18.x | obsolete, but do not delete the branch. PDF only |
v0.17.x | obsolete, but do not delete the branch. PDF only |
v0.16.x | obsolete, but do not delete the branch. PDF only |
v0.15.x | obsolete, but do not delete the branch. PDF only |
v0.14.x | obsolete, but do not delete the branch |
v0.13.x | obsolete, but do not delete the branch |
v0.12.x | obsolete, but do not delete the branch |
v0.11.x | obsolete, but do not delete the branch |
v0.10.x | obsolete, but do not delete the branch |
v0.9.x | obsolete, but do not delete the branch |
Because main is the latest and greatest documentation, the process is to cut a x.x branch for the version that main was targeting during that time.
After this point, main is the target for the next version of the On-Demand Services SDK product.
Cross-product partials (if any) for On-Demand Services SDK are single sourced from the Docs Partials repository.
If there is some documentation to add for an unreleased patch version of Cloud Service Broker 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. If necessary, refresh after about 10 seconds.
-
Go to the 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 On-Demand Services SDK for docs.