Skip to content

Contribution

All contributions are welcome!

Outside Collaborators

Please open a support request in your #cloud-platform-<workload> channel to be added as a collaborator to this repository.

Fork-based pull requests are not recommended at this time.

Modify directly on GitHub

This documentation is designed to be easily modified without needing to setup a local development environment. For small fixes, adjustments, or additions, feel free to modify directly on GitHub and submitting a pull request.

Work locally

For larger changes, it is recommended to work locally, which requires git to be installed.

Clone the repository

First, clone the project repository:

git clone https://example.com/platform-eng/cloud-platform-docs.git
cd cloud-platform-docs

Directory structure

To reduce confusion and friction, the structure of the mkdocs site is automatically generated based on the folder structure within docs. There are various scripts and pre-commit hooks that streamline the process of creating new documents and inserting them into the nav. These are the rules:

  1. All markdown files must be named index.md
  2. All index.md files must be contained in a directory that matches a snake case version of the title (i.e. <h1>) of the document. For example, if the title is Amazing Document, the directory must be named amazing_document.
  3. One, and only one markdown file may exist in a directory, and it must be index.md
  4. All images and attachments used by index.md must live in the same directory and at the same level (note: git de-duplicates file contents).
  5. Any document that is the child of another document must adhere to these rules.

Local development environment

There are two supported paths for setting up a local development environment. Both paths have additional tooling prerequisites.

Prerequisites

  • VScode
  • VSCode DevContainer Extension
  • A suitable Docker container runtime (e.g. Rancher Desktop) providing both docker and docker compose
  1. Open project in VSCode
  2. Click button when prompt surfaces to Re-Open in DevContainer (You may also use the command pallet to perform this action)

Option 2: Minimal installation of Python, Mkdocs, and Pre-Commit

Prerequisites

  • Python 3.10+
  • Python virtualenv module

  1. Install Dependencies:

    python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt -c constraints.txt

  2. Install Pre-Commit Hooks:

    pre-commit install

Prepare changes

  1. Create a branch (avoid working directly on the main branch):

    git checkout -b "<my_branch_name>"

  2. To create a new document that conforms to the directory structure, run

    ./scripts/create_new_page.sh "New Doc" docs

    This will create the following folder structure docs/new_doc/index.md where index.html has the content # New Doc.

  3. Launch Mkdocs:

    This step starts Mkdocs in strict mode with mkdocs serve and hydrates the nav section of the mkdocs.yml:

    ./scripts/start_mkdocs.sh

    By default, Mkdocs hot-reloads whenever content under docs is changed. When adding new content, you must re-run the above command to ensure new pages are added to the nav.

  4. Make changes to the documentation by adding new files, updating existing files, or deleting files.

    Info

    Please review the Standards for how to best contribute to the documentation.

  5. (Optional) It may be useful to run the pre-commit hooks against all files to find potential problems before committing.

    ./scripts/pre_commit.sh

  6. Commit changes:

    git add <file1> [...]
git commit [-m <message>]

    The pre-commit hooks should run automatically. If a hook modifies any files or fails, the commit aborts, in which case, you must fix the issues and commit again.

    Info

    In the rare event you must bypass pre-commit hooks, you may do so by adding the --no-verify flag:

    git commit --no-verify [-m <message>]

  7. Push changes on your branch to GitHub

    git push origin "<my_branch_name>"

  8. When satisfied the changes on your branch are ready for review, open a pull request

Preview changes

GitHub Actions posts a comment on the pull request with a link to your changes, using the following format: https://cp-docs-dev.company.com/branch-<branch-name>

Publish changes to production

GitHub automatically requests review from an appropriate maintainer based on the CODEOWNERS file.

To merge the pull request, the following must occur:

  • The pre-commit quality checks in GitHub Actions must pass
  • A code owner must approve the pull request

When the pull request is merged, GitHub automatically publishes the changes to https://cp-docs.company.com.

Additional resources