ocp-ci-docs

Scenario onboarding documentation for OpenShift CI created by the CSPI team

Contributing

Best Practices

• Ensure any new document is linked properly in the docs/SUMMARY.md file. This is how GitBook will present documents in the generated webpage.
• All pull requests into the main branch of this repository should come from a branch in your personal fork of the repository.
• Do NOT push any changes to the main branch of this repository. Any changes to this branch must go through the pull request process.

Pull Requests

• All pull requests must be reviewed by another member of the team before being merged.
• Do not merge your own pull request. Ask a reviewer who performed a final review of your changes to merge your pull request when you are ready.
• All pull requests must pass linting before being merged. This check will occur when a pull request is created in GitHub actions.

Linting

• This repository uses markdownlint-cli2 as its linter.
• The rules used for linting can be found in the .markdownlint.json file.
• All pull requests are required to pass linting. The GitHub action that enforces that rule can be found at .github/workflows/pull_request.yml.
• To test linting in your local environment prior to creating a pull request (recommended), use the pre-commit hook:
  1. Install pre-commit, if you haven't already.
  2. Execute pre-commit run --all-files in the root of your local copy of this repository.
  3. Fix any errors reported by that command.

Markdown Resources

Documentation

• Official Markdown Documentation
• Mermaid Documentation
  • Used to dynamically generate flowcharts and other diagrams within Markdown

Editors

• Visual Studio Code (Recommended)
• PyCharm
• Obsidian
• Remarkable

Plugins

NOTE: These plugins are specific to Visual Studio Code, our recommended editor

• Markdown All In One
• Markdown Preview Mermaid Support
• Code Spell Checker