Skip to content

Completing the Confluence Migration

Getting started

We strongly recommend for you to use Dev Container Setup in order to get started on development.

Note

Pre-commit checks are used as required checks in CICD for allowing your PR to be merged. These checks ensure the integrity of the site and its navigation as well as set an automated quality bar. It is therefore highly advisable to use the dev container, which is set up to run them, or to install them yourself if working directly on your laptop. This helps avoid unnecessary trips through CICD in order to get the triggers all to pass.

Also, please review this introduction to the directory structure. This will help you understand the tree you are working in.

Document transformation

  • Ensure offsite links are functional and correct any that are broken.
  • Ensure absolute paths are used to link to other documents.
  • Consider renaming images and attachments.
  • Some documents present a list of attachments/images at the bottom. It may make sense to move these into context, within the body of the document; otherwise, remove them.
  • Properly cleanup the documents.
    • We've automated document processing, but it's left a significant amount of unnecessary white spacing. Please clean it up to enhance source readability.
  • Utilize code blocks where appropriate.
  • Incorporate headings to ensure sections are displayed as Table of Contents on right hand side.
    • To achieve this, use headers notated like # My Header (as opposed to using Bold to indicate headers e.g. **My Header**).

Incorporate MkDocs features

MkDocs provides a good amount of features to make your document more reader-friendly.

Find complete feature documentation here.

e.g.: Here's an admonition feature.

!!! Note
    This is an admonition.

Note

This is an admonition.

Running pre-commit

On attempting to run git commit, all the pre-commit hooks will run, and may prevent the commit from completing. Again these checks will also be run by the CICD as required checks for merging PRs, so running and passing pre-commit is essential.

Some changes might be made to the staged files, in which case you must re-stage the such files in order for pre-commit to see the updates on the next attempt.

To run an individual pre-commit hook and avoid the overhead of running all the hooks, do this:

% hook_name=cspell # for example
% pre-commit run $hook_name # checks staged files only, using the identified trigger $hook_name

To get more help, type pre-commit --help.

Pre-commit errors & troubleshooting

Pre-commit may find warnings in the following areas:

[INFO] Stashing unstaged files to /home/skrishnasanka/.cache/pre-commit/patch1710529235-858666.
Check spelling...........................................................Failed
- hook id: cspell
- exit code: 1

./docs/contribution/completing_the_confluence_migration/index.md:16:57     - Unknown word (devex)      -- notated platform-eng-devex like `# My Header` as
        Suggestions: [desex, dexe, dave, deed, deem]

If the word is valid according to your terminology, go ahead and add it under /.github/workflows/config/custom-dictionary.txt

Tip

The spellchecker ignores code in backticks.

To get strict mode to PASS, you will need to look at the WARNING line and fix those links. It's possible that one of the relative path of the file declaration might've been wrong.

Most of the other errors out there are generally self-explanatory. They check a variety of things including but not limited to integrity of links, proper directory structure, markdown formatting, etc.

Tip

Again, some pre-commit hooks alter the content of the files. You will need to re-stage those files in order to get the pre-commit passing.