diff --git a/.github/workflows/deploy-gh-pages.yaml b/.github/workflows/deploy-gh-pages.yaml new file mode 100644 index 0000000..e71cc4e --- /dev/null +++ b/.github/workflows/deploy-gh-pages.yaml @@ -0,0 +1,41 @@ +name: Deploy GH Pages +on: + push: + branches: + - main + - feature/developer-hub + paths: + - 'mkdocs.yml' + - 'docs/**' + +permissions: + contents: write + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v3 + + - name: Setup Python + uses: actions/setup-python@v4 + with: + python-version: 3.x + + - name: Set cache id + run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV + + - name: Use cache + uses: actions/cache@v3 + with: + key: mkdocs-material-${{ env.cache_id }} + path: .cache + restore-keys: | + mkdocs-material- + + - name: Install mkdocs-material and plugins + run: pip install mkdocs-material + + - name: Deploy to GH Pages + run: mkdocs gh-deploy --force diff --git a/Taskfile.yaml b/Taskfile.yaml new file mode 100644 index 0000000..29c4ed7 --- /dev/null +++ b/Taskfile.yaml @@ -0,0 +1,7 @@ +version: 3 + +tasks: + serve: + desc: Run local dev server + cmds: + - docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material diff --git a/docs/Guidelines/PDG_0_-_Changelog & Drafts/index.md b/docs/Guidelines/PDG_0_-_Changelog & Drafts/index.md new file mode 100644 index 0000000..b0faebf --- /dev/null +++ b/docs/Guidelines/PDG_0_-_Changelog & Drafts/index.md @@ -0,0 +1,5 @@ +# Changelog of Pmoscode Developer Guidelines (PDGs) + +| Created | Post-History | +|-------------|----------------------------------------------------------------------------------------------| +| 01-Sep-2023 | Initial contribution | diff --git a/docs/Guidelines/PDG_0_-_Changelog & Drafts/trg-0-template.md b/docs/Guidelines/PDG_0_-_Changelog & Drafts/trg-0-template.md new file mode 100644 index 0000000..5fefb71 --- /dev/null +++ b/docs/Guidelines/PDG_0_-_Changelog & Drafts/trg-0-template.md @@ -0,0 +1,18 @@ +# PDG 0.1 - Templates + +This is the template for new PDG's. + +| Status | Created | Post-History | +|------------|--------------|--------------------------------------------| +| Deprecated | 05-May-2023 | Deprecated it because obsolete or outdated | +| Active | 27-Feb-2023 | Mark active without limitations | +| Draft | 13-Sept-2022 | Initial contribution | + +## Why + +Here you will find the purpose of this PDG. For example, because it makes it much easier for others to use, or it's a default style convention, ... + +## Description + +Here you will find the description of the PDG. +Provides best practices: In the best case with code example or/and step-by-step guide. diff --git a/docs/Guidelines/PDG_1_-_Documentation/pdg-1-1.md b/docs/Guidelines/PDG_1_-_Documentation/pdg-1-1.md new file mode 100644 index 0000000..9b0cfad --- /dev/null +++ b/docs/Guidelines/PDG_1_-_Documentation/pdg-1-1.md @@ -0,0 +1,21 @@ +# PDG 1.1 - README.md + +| Status | Created | Post-History | +|--------|-------------|--------------| +| Active | 01-Sep-2023 | | + +## Why + +A good written `README.md` file is the entry point for everyone visiting a repository. It should contain all necessary information. + +## Description + +Each repository **must** contain a `README.md` file which **shall** cover the following topics: + +- A short introduction to the software component it offers +- Basic description of the repository and its content +- Installation instructions to get component working +- If required, additional post-installation configuration steps to finish installation +- Optional: Development / contribution instructions + +If installation instructions are too comprehensive for the `README.md`, move content to `INSTALL.md` file and reference it here. See [PDG 1.2](pdg-1-2.md). diff --git a/docs/Guidelines/PDG_1_-_Documentation/pdg-1-2.md b/docs/Guidelines/PDG_1_-_Documentation/pdg-1-2.md new file mode 100644 index 0000000..8ed1754 --- /dev/null +++ b/docs/Guidelines/PDG_1_-_Documentation/pdg-1-2.md @@ -0,0 +1,15 @@ +# PDG 1.2 - INSTALL.md + +| Status | Created | Post-History | +|--------|--------------|--------------| +| Active | 01-Sep-2023 | | + +## Why + +When a repository contains code which needs to be configured/setup or installed, the `README.md` file should cover this information. +If this is too much content, it can be moved into a `INSTALL.md` file and referenced in the README.md. + +## Description + +Create a `INSTALL.md` file in the main folder of the repository and add all installation relevant information. +Also add all post-installation configuration steps to finish installation. diff --git a/docs/Guidelines/PDG_1_-_Documentation/pdg-1-3.md b/docs/Guidelines/PDG_1_-_Documentation/pdg-1-3.md new file mode 100644 index 0000000..ddf3c4e --- /dev/null +++ b/docs/Guidelines/PDG_1_-_Documentation/pdg-1-3.md @@ -0,0 +1,19 @@ +# PDG 1.3 - CHANGELOG.md + +| Status | Created | Post-History | +|--------|-------------|--------------| +| Active | 01-Sep-2023 | | + +## Why + +Knowing of what changes have been made is very important. Getting information about features, bug and security fixes are mandatory. + +This helps everyone who is using the software to understand what version to choose or when to upgrade. + +## Description + +To track changes of releases a `CHANGELOG.md` **must** exist in repositories. The format **should** follow the [Keep A Changelog](https://keepachangelog.com/en/1.0.0/). + +The versioning of releases **must** follow [semantic versioning](https://semver.org/). + +For easy changelog creation, [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) **should** be applied to every commit. diff --git a/docs/Guidelines/PDG_2_-_GIT/pdg-2-1.md b/docs/Guidelines/PDG_2_-_GIT/pdg-2-1.md new file mode 100755 index 0000000..c249382 --- /dev/null +++ b/docs/Guidelines/PDG_2_-_GIT/pdg-2-1.md @@ -0,0 +1,13 @@ +# PDG 2.1 - Default Branch + +| Status | Created | Post-History | +|--------|-------------|--------------| +| Active | 22-Dec-2023 | | + +## Why + +This is a personal decision. But future features or requirements could demand on it. E.g.: for security scanning. + +## Description + +Default branch **must** be `main`. diff --git a/docs/Guidelines/PDG_2_-_GIT/pdg-2-2.md b/docs/Guidelines/PDG_2_-_GIT/pdg-2-2.md new file mode 100755 index 0000000..5c9caf8 --- /dev/null +++ b/docs/Guidelines/PDG_2_-_GIT/pdg-2-2.md @@ -0,0 +1,49 @@ +# PDG 2.3 - Repo structure + + +| Status | Created | Post-History | +|--------|-------------|--------------| +| Active | 22-Dec-2023 | | + +## Why + +To have a unified and common repository structure is helpful when working in more than one project. It can be adapted but should remain consistent. + +## Description + +All repositories **must** contain the following files and folders: + +```text +CONTRIBUTING.md +LICENSE +README.md +CODE_OF_CONDUCT.md +``` + +**Optional** files and folders: + +```text +AUTHORS.md +INSTALL.md +SECURITY.md +``` + +### Files + +#### README.md + +Your repository **must** contain a `README.md` file. See [PDG 1.1 - README.md](../PDG_1_-_Documentation/PDG-1-1). + +#### INSTALL.md + +Your repository **should** contain a `INSTALL.md` file. See[PDG 1.2 - INSTALL.md](../PDG_1_-_Documentation/PDG-1-2). + +#### Legal documentation + +For the following files, see [PDG 7.01](../PDG_7_-_Open_Source_Governance/PDG-7-1) + +- AUTHORS.md (optional) +- CODE_OF_CONDUCT.md +- CONTRIBUTING.md +- LICENSE +- SECURITY.md diff --git a/docs/Guidelines/index.md b/docs/Guidelines/index.md new file mode 100644 index 0000000..8232887 --- /dev/null +++ b/docs/Guidelines/index.md @@ -0,0 +1,22 @@ +# Developer Guidelines + +## Introduction + +Welcome to pmoscode developer guidelines, known as PDGs. PDG numbers — once assigned — never change, and each PDG deals with special technical topics. + +You find the overarching Changelog [here](PDG_0_-_Changelog & Drafts) to see when new PDGs have been added. + +## Goal + +This PDG's main goal is: Providing reasonable defaults for requirements, components and styles. +This shall make contribution, maintenance and running products/components as easy as possible. + +## Living documentation + +Adding new PDG's is the simplest case. Here they are just added and the history is updated. + +Once in "active" status, changing or deleting PDG's does not delete the obsolete content. Rather, these are optically "deleted" and, if necessary, supplemented with new content. + +## Contribution + +If you want to contribute to this PDG or you recognize typos or mistakes, feel free to crate a Pull Request! diff --git a/docs/assets/logo-icon-round-inverted.png b/docs/assets/logo-icon-round-inverted.png new file mode 100644 index 0000000..3b237f2 Binary files /dev/null and b/docs/assets/logo-icon-round-inverted.png differ diff --git a/docs/assets/logo-icon-round.png b/docs/assets/logo-icon-round.png new file mode 100644 index 0000000..ff0f131 Binary files /dev/null and b/docs/assets/logo-icon-round.png differ diff --git a/docs/fonts/lato/lato-v24-latin-300.ttf b/docs/fonts/lato/lato-v24-latin-300.ttf new file mode 100644 index 0000000..f49dd5c Binary files /dev/null and b/docs/fonts/lato/lato-v24-latin-300.ttf differ diff --git a/docs/fonts/lato/lato-v24-latin-300.woff2 b/docs/fonts/lato/lato-v24-latin-300.woff2 new file mode 100644 index 0000000..aad98a3 Binary files /dev/null and b/docs/fonts/lato/lato-v24-latin-300.woff2 differ diff --git a/docs/fonts/lato/lato-v24-latin-300italic.ttf b/docs/fonts/lato/lato-v24-latin-300italic.ttf new file mode 100644 index 0000000..84ea014 Binary files /dev/null and b/docs/fonts/lato/lato-v24-latin-300italic.ttf differ diff --git a/docs/fonts/lato/lato-v24-latin-300italic.woff2 b/docs/fonts/lato/lato-v24-latin-300italic.woff2 new file mode 100644 index 0000000..394b5cf Binary files /dev/null and b/docs/fonts/lato/lato-v24-latin-300italic.woff2 differ diff --git a/docs/fonts/lato/lato-v24-latin-700.ttf b/docs/fonts/lato/lato-v24-latin-700.ttf new file mode 100644 index 0000000..0dc02c9 Binary files /dev/null and b/docs/fonts/lato/lato-v24-latin-700.ttf differ diff --git a/docs/fonts/lato/lato-v24-latin-700.woff2 b/docs/fonts/lato/lato-v24-latin-700.woff2 new file mode 100644 index 0000000..11de83f Binary files /dev/null and b/docs/fonts/lato/lato-v24-latin-700.woff2 differ diff --git a/docs/fonts/lato/lato-v24-latin-700italic.ttf b/docs/fonts/lato/lato-v24-latin-700italic.ttf new file mode 100644 index 0000000..02a862b Binary files /dev/null and b/docs/fonts/lato/lato-v24-latin-700italic.ttf differ diff --git a/docs/fonts/lato/lato-v24-latin-700italic.woff2 b/docs/fonts/lato/lato-v24-latin-700italic.woff2 new file mode 100644 index 0000000..38df58b Binary files /dev/null and b/docs/fonts/lato/lato-v24-latin-700italic.woff2 differ diff --git a/docs/fonts/lato/lato-v24-latin-regular.ttf b/docs/fonts/lato/lato-v24-latin-regular.ttf new file mode 100644 index 0000000..85b2663 Binary files /dev/null and b/docs/fonts/lato/lato-v24-latin-regular.ttf differ diff --git a/docs/fonts/lato/lato-v24-latin-regular.woff2 b/docs/fonts/lato/lato-v24-latin-regular.woff2 new file mode 100644 index 0000000..ff60934 Binary files /dev/null and b/docs/fonts/lato/lato-v24-latin-regular.woff2 differ diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..2fa6bd5 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,13 @@ +# Introduction + +Welcome to the **Developer Hub** of pmoscode for Helm charts / Docker image repositories! + +Here you will find all the information +you need for an uncomplicated contribution in the pmoscode Helm chart organization. + +Of course, these are not always applicable in all cases. +For most cases, however, +they make it easier to process pull requests and help maintain a consolidated repository landscape. + +This makes it easier for you to understand the structure and elements of the Helm charts +and to contribute to this organization. diff --git a/docs/style/extra.css b/docs/style/extra.css new file mode 100644 index 0000000..fd7ba69 --- /dev/null +++ b/docs/style/extra.css @@ -0,0 +1,54 @@ +/* lato-300 - latin */ +@font-face { + font-display: swap; /* Check https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display for other options. */ + font-family: 'Lato'; + font-style: normal; + font-weight: 300; + src: url('/fonts/lato/lato-v24-latin-300.woff2') format('woff2'), /* Chrome 36+, Opera 23+, Firefox 39+, Safari 12+, iOS 10+ */ + url('/fonts/lato/lato-v24-latin-300.ttf') format('truetype'); /* Chrome 4+, Firefox 3.5+, IE 9+, Safari 3.1+, iOS 4.2+, Android Browser 2.2+ */ +} + +/* lato-300italic - latin */ +@font-face { + font-display: swap; /* Check https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display for other options. */ + font-family: 'Lato'; + font-style: italic; + font-weight: 300; + src: url('/fonts/lato/lato-v24-latin-300italic.woff2') format('woff2'), /* Chrome 36+, Opera 23+, Firefox 39+, Safari 12+, iOS 10+ */ + url('/fonts/lato/lato-v24-latin-300italic.ttf') format('truetype'); /* Chrome 4+, Firefox 3.5+, IE 9+, Safari 3.1+, iOS 4.2+, Android Browser 2.2+ */ +} + +/* lato-regular - latin */ +@font-face { + font-display: swap; /* Check https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display for other options. */ + font-family: 'Lato'; + font-style: normal; + font-weight: 400; + src: url('/fonts/lato/lato-v24-latin-regular.woff2') format('woff2'), /* Chrome 36+, Opera 23+, Firefox 39+, Safari 12+, iOS 10+ */ + url('/fonts/lato/lato-v24-latin-regular.ttf') format('truetype'); /* Chrome 4+, Firefox 3.5+, IE 9+, Safari 3.1+, iOS 4.2+, Android Browser 2.2+ */ +} + +/* lato-700 - latin */ +@font-face { + font-display: swap; /* Check https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display for other options. */ + font-family: 'Lato'; + font-style: normal; + font-weight: 700; + src: url('/fonts/lato/lato-v24-latin-700.woff2') format('woff2'), /* Chrome 36+, Opera 23+, Firefox 39+, Safari 12+, iOS 10+ */ + url('/fonts/lato/lato-v24-latin-700.ttf') format('truetype'); /* Chrome 4+, Firefox 3.5+, IE 9+, Safari 3.1+, iOS 4.2+, Android Browser 2.2+ */ +} + +/* lato-700italic - latin */ +@font-face { + font-display: swap; /* Check https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display for other options. */ + font-family: 'Lato'; + font-style: italic; + font-weight: 700; + src: url('/fonts/lato/lato-v24-latin-700italic.woff2') format('woff2'), /* Chrome 36+, Opera 23+, Firefox 39+, Safari 12+, iOS 10+ */ + url('/fonts/lato/lato-v24-latin-700italic.ttf') format('truetype'); /* Chrome 4+, Firefox 3.5+, IE 9+, Safari 3.1+, iOS 4.2+, Android Browser 2.2+ */ +} + + +:root { + --md-text-font: "Lato"; +} diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..e20691c --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,76 @@ +# yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json + +site_name: Developer Hub + +#custom_dir: overrides + +theme: + name: material + logo: assets/logo-icon-round-inverted.png + font: false + features: + - navigation.instant + - navigation.tracking + - navigation.indexes + - navigation.top + - search.highlight + - navigation.footer + - content.code.copy + - content.code.annotate + palette: + - scheme: default + primary: deep orange + accent: blue + toggle: + icon: material/brightness-7 + name: Switch to dark mode + - scheme: slate + primary: deep orange + accent: blue + toggle: + icon: material/brightness-4 + name: Switch to light mode + +plugins: + - search +# - privacy: +# assets: true +# assets_fetch: true +# assets_fetch_dir: assets/external + +extra_css: + - style/extra.css + +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/pmoscode + - icon: fontawesome/brands/docker + link: https://hub.docker.com/u/pmoscode + - icon: fontawesome/regular/envelope + link: mailto:info@pmoscode.de + consent: + title: Cookie consent + description: >- + We use cookies to recognize your repeated visits and preferences, as well + as to measure the effectiveness of our documentation and whether users + find what they're searching for. With your consent, you're helping us to + make our documentation better. + actions: + - accept + - reject + +copyright: > + Copyright © 2023 pmoscode – + Change cookie settings + +markdown_extensions: + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - admonition + - pymdownx.details + - pymdownx.snippets + - pymdownx.superfences