Skip to content

Latest commit

 

History

History
119 lines (92 loc) · 4.31 KB

README.md

File metadata and controls

119 lines (92 loc) · 4.31 KB

Devfile 2.0 website and documentation.

The generated JSON Schema documentation for the Devfile 2.x is available here: https://devfile.github.io/.

Devfile 2.0 documentation

Devfile 2.1 development documentation

Contributing

To build the documentation locally you need Antora, node v10.12 or higher and yarn. Then from the root of this repository run:

yarn install; yarn run generate-api-reference
antora antora-playbook.yml

These commands will generate the html documentation in folder build/site. Open build/site/index.html in the browser.

Additionally, when pushing to a branch or working on a PR, the site is built by a GH action and made available in a ZIP file as a GH action build artifact, and can be tested locally.

  • Updates to the documentation for the Devfile version under development should be merged into the master branch.
  • Updates to the documentation for previously released Devfile versions should be merged into the braach for the release version, for example v2.0.x.

Issue tracking repo

https://github.com/devfile/api with label area/documentation

Release process

Each release a new git release, tag and branch will be created. The tag marks the initial release documentation and the branch is used for any post release updates. Next release work then continues on the master branch. To enable this the following release process must be followed:

Changes for the new release branch

Set the new branch to be specific to the release version. For example, if the release version is 2.0.0:

  1. Prior to this process the api repo is updated to copy a final version of the schema to a directory for that version. For example: `docs/modules/user-guide/attachments/jsonschemas/2.0.0/devfile.json
  2. Create the new branch for the tag: git fetch --all git checkout -b v2.0.x v2.0.0
  3. Modify docs/antora.yaml:
    1. Set the correct title and version.
    2. Remove the pre-release attribute.
    3. Set .asciidoc .attributes .prod-ver for the release
    4. For example if release is 2.0.0 
      name: devfile
nav: 
  - modules/user-guide/nav.adoc
start_page: user-guide:index.adoc
title: Devfile User Guide v2.0.0
version: '2.0.0'
asciidoc:
  attributes:
    prod-ver: 2.0
  4. Modify .gitignore to not ignore the doc generated from the schema for the release: 
    docs/modules/user-guide/attachments/api-reference/next
docs/modules/user-guide/attachments/api-reference/stable
docs/modules/user-guide/examples/api-reference/next
docs/modules/user-guide/examples/api-reference/stable
  5. Modify docs/modules/user-guide/partials/ref_api-reference.adoc to pull the iframe and link from the newly generated directories. 
    [id="ref_api-reference_{context}"]
 = API Reference

 This section describes the devfile API.

 ++++
 <iframe src="./_attachments/api-reference/2.0.0/index.html" style="border:none;width: 100%;min-height:50em;height:-webkit-fill-available;"></iframe>
 ++++

 .Additional resources

 * link:{attachmentsdir}/jsonschemas/2.0.0/devfile.json[Download the current JSON Schema]```
  6. Build the docs and verify all looks good.
  7. Add the changes, commit the branch and push directly to the docs repo. (There is no merge required for this branch).

Changes to the master branch

Now the master branch can be updated for the next release and to link the previous release docs from the newly created v.2.0.x branch.

  1. Modify 'docs/antora.yaml' to set the correct title,version,pre-release and prod-ver. For example: 
    asciidoc:
   attributes:
     prod-ver: 2.1
name: devfile
nav:
  - modules/user-guide/nav.adoc
start_page: user-guide:index.adoc
title: Devfile User Guide 2.1.0
version: '2.1.0'
prerelease: -alpha
  2. Modify antora-playbook.yaml to add content for the new release created: 
    content:
  sources:
    - branches: HEAD
      start_path: docs
      url: ./
    - branches: v2.0.x
      start_path: docs
      url: ./
  3. Build, test, commit and merge the changes