Skip to content

docs: clarify documentation workflow #6739

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
abdollahShahid wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs: clarify documentation workflow #6739

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 12 additions & 12 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,31 +1,31 @@
# Documentation

The source files for the documentation is placing in [content](https://github.com/pipe-cd/pipecd/tree/master/docs/content) directory.
The source files for the PipeCD documentation are placed in the [docs/content](https://github.com/pipe-cd/pipecd/tree/master/docs/content) directory.

# Website

The PipeCD documentation website is built with [hugo](https://gohugo.io/) and published at https://pipecd.dev
The PipeCD documentation website is built with [Hugo](https://gohugo.io/) and published at https://pipecd.dev.

# Docs and workaround with docs
# Docs contribution workflow

PipeCD official site contains multiple versions of documentation, all placed under the `/docs/content/en` directory, which are:
- `/docs-dev`: experimental version docs, contains docs for not yet released features or changes.
- `/docs-v0.x.x`: contains docs for specified version family (a version family is all versions which in the same major release).
The PipeCD official site contains multiple versions of documentation under `docs/content/en`, including:
- `docs-dev`: experimental documentation for unreleased features or changes.
- `docs-vX.Y.x`: contains docs for a specific released version family.

Here are the flow of docs contribution regard some known scenarios:
Use the following workflow for common documentation contribution scenarios:
1. Update docs that are related to a specified version (which is not the latest released version):
In such case, update the docs under `/docs-v0.x.x` is enough.
In this case, update the docs under `docs-vX.Y.x`.
2. Update docs for not yet released features or changes:
In such case, update the docs under `/docs-dev` is enough.
In this case, update the docs under `docs-dev`.
3. Update docs that are related to the latest released docs version:
Change the docs' content that fixes the issue under `/docs-dev` and `/docs-v0.x.x`, they share the same file structure so you should find the right files in both directories.
In this case, update the corresponding files under `docs-dev` and `docs-vX.Y.x`.

If you find any issues related to the docs, we're happy to accept your help.

# How to run website locally

## Prerequisite
- [Hugo 0.92.1+extended](https://gohugo.io/)
- [Hugo Extended 0.92.1+](https://gohugo.io/)

## Commands
Run `make run/site` at the root directory of the repository and then access http://localhost:1313
Run `make run/site` at the repository root, and then access http://localhost:1313.
Loading