Merge pull request #30 from rog-golang-buddies/gen-docs

Add mkdocs-material docs gen and include CI docs (review)

Author: shukra-in-spirit

.github/workflows/mkdocs.yml

@@ -0,0 +1,16 @@
+name: gen-docs
+on:
+  push:
+    branches:
+      - master
+      - main
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v2
+        with:
+          python-version: 3.x
+      - run: pip install mkdocs-material
+      - run: mkdocs gh-deploy --force

docs/.DS_Store

@@ -0,0 +1,32 @@
+# gitleaks
+
+## What
+
+[gitleaks](https://github.com/zricethezav/gitleak) is a SAST tool for detecting and preventing hardcoded secrets like passwords, api keys, and tokens in git repos. Gitleaks is an easy-to-use, all-in-one solution for detecting secrets, past or present, in your code.
+
+## Why
+
+Raise security incidents early by detecting secret leaks and raising Github security code scanning alerts.
+
+## How
+
+The mechanism to detect secrets and protect (undo commit with a secret) is described [here](https://github.com/zricethezav/gitleaks#commands).
+
+## CI setup
+
+!!! summary
+
+    No configuration required.
+
+
+A `gitleaks detect` command is run via a gitleaks Github workflow in `.github/workflows/gitleaks.yml`.
+
+!!! info
+
+    The [gitleaks Github action](https://github.com/marketplace/actions/gitleaks) has a paid license restriction, therefore a custom workflow has been setup instead. It will fail the secret scan if secrets are detected and push alerts to Github security.
+
+## Local setup
+
+!!! done
+
+    This is already configured for you via [pre-commit](pre-commit.md#local-setup).

docs/continuous-integration/gitleaks.md

@@ -0,0 +1,36 @@
+# golangci-lint
+
+## What
+
+[golangci-lint](https://golangci-lint.run/) is a Go linters aggregator. It runs linters in parallel, uses caching, supports yaml config, has integrations with all major IDE and has dozens of linters included.
+
+## Why
+
+Provides Secure Application Security Testing, error, style etc. checks for your codebase.
+
+!!! tip
+
+    See supported linters [here](https://golangci-lint.run/usage/linters).
+
+## How
+
+Linters can be configured via command-line options or  a [configuration file](https://golangci-lint.run/usage/configuration/#config-file).
+
+
+## CI setup
+
+!!! summary
+
+    No configuration required.
+
+`golangci-lint` will be executed via the pre-commit Github workflow in `.github/workflows/pre-commit.yml`.
+
+## Local setup
+
+!!! done
+
+    This is already configured for you via [pre-commit](pre-commit.md#local-setup).
+
+For custom configurations to modify how `golangci-lint` runs see the [configuration guide](https://golangci-lint.run/usage/configuration/).
+
+You may want to disable linters that might be too strict (e.g: [exhaustivestruct](https://github.com/mbilski/exhaustivestruct)) or add some rules around how it should behave. This can be done via [linter configuration](https://golangci-lint.run/usage/linters/#linters-configuration).

docs/continuous-integration/golangci-lint.md

@@ -0,0 +1,49 @@
+# mkdocs-material
+
+## What
+
+[mkdocs-material](https://squidfunk.github.io/mkdocs-material/) provides documentation in Markdown to create a professional static site in minutes – searchable, customizable, for all devices.
+
+## Why
+
+From a developer experience perspective, it is easier to clone and have everything you need to reference locally rather than having to externally reference something i.e Github wiki, Confluence etc.
+
+This minimises context switching and aids the practice of keeping documentation updated as it is closer to the codebase.
+
+## How
+
+The repository is preconfigured with a `./docs` directory and renders all markdown files to generate a `github-pages` site.
+
+`mkdocs-material` is customizable via the `mkdocs.yml` configuration file available in the repository root directory. The configuration present is not exhaustive and can be further [customized](https://squidfunk.github.io/mkdocs-material/reference/).
+
+
+## CI setup
+
+### Github pages
+
+A gen-docs workflow is configured to automatically run on the `main` branch however it requires github-pages to be enabled in the repository settings.
+
+See the screenshot below:
+
+![gh-pages-settting](img/mkdocs-gh-pages.png)
+
+The documentation contained within the `./docs` directory will be automatically published and accessible via `<org>.github.io/<repository>.`
+
+### Site name
+
+Update `site_name` field in `./mkdocs.yml` file to set the main title for the project documentation.
+
+
+## Local setup
+
+```bash
+pip install mkdocs-material
+```
+
+For more installtion options see [here](https://squidfunk.github.io/mkdocs-material/getting-started/).
+
+Run a local server to preview docs:
+
+```bash
+mkdocs serve
+```

docs/continuous-integration/img/mkdocs-gh-pages.png

@@ -0,0 +1,52 @@
+# pre-commit
+
+## What
+
+[pre-commit](https://pre-commit.com/) is a wrapper for git hook scripts that are useful for identifying simple issues before submission to code review. Git hooks are run on every commit to automatically point out issues in code such as missing semicolons, trailing whitespace, and debug statements and integrate with a variety of third-party tooling.
+
+## Why
+
+Eliminates the effort of initializing and managing git hooks locally. `pre-commit` also integrates with a large range of (hooks)[https://pre-commit.com/hooks.html] enabling a consistent developer experience.
+
+## How
+
+A `.pre-commit-config.yaml` config file is configured with common and useful hoooks. This is available at the root of your repository. Each time you make a commit the pre-commit hooks run.  If a hook supports applying auto-fixes (e.g: hook `trailing-whitespace` support fixing trailing whitespaces), it will proceed to fix it.
+Any detected failures will abort the commit.
+
+!!! tip
+
+    See supported hooks [here](https://pre-commit.com/hooks.html).
+
+## CI setup
+
+!!! summary
+
+    No configuration required.
+
+All hooks in `.pre-commit-config.yaml` will be executed via the pre-commit Github workflow in `.github/workflows/pre-commit.yml`.
+
+## Local setup
+
+```bash
+pip install -u pre-commit
+```
+
+For more installtion options see [here](https://commitizen-tools.github.io/commitizen/#installation).
+
+Install the hooks configured in `.pre-commit-config.yaml`:
+
+```bash
+pre-commit install
+```
+
+Running against all files instead of only stages files:
+
+```
+pre-commit run --all-files
+```
+
+## FAQ
+
+1. Do I have to run `pre-commit install` everytime I clone a repository?
+
+    Yes. However, you can automatically enable `pre-commit` to run when you clone a repository via [this](https://pre-commit.com/#automatically-enabling-pre-commit-on-repositories) link.

docs/continuous-integration/mkdocs-material.md

@@ -0,0 +1,126 @@
+# semantic-release
+
+## What
+
+[semantic-release](https://github.com/semantic-release/semantic-release) automates the whole package release workflow including determining the next version number, generating the release notes, and publishing the package.
+
+semantic-release uses the commit messages to determine the consumer impact of changes in the codebase. Following formalized conventions for commit messages, `semantic-release` automatically determines the next semantic version number, generates a changelog and publishes the release.
+
+## Why
+
+Follow a well-established [commit message convention](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit) that encourages your team to have structured commits and provides the controls via commits to automatically version your codebase & publish a release.
+
+
+## How
+
+### Commit message convention
+
+The formalized convention is as follows for commit messages:
+
+```
+<type>(<scope>): <short summary>
+  │       │             │
+  │       │             └─⫸ Summary in present tense. Not capitalized. No period at the end.
+  │       │
+  │       └─⫸ Commit Scope: A scope MUST consist of a noun describing a section of the codebase surrounded by parenthesis
+  │
+  └─⫸ Commit Type: build|ci|docs|feat|fix|perf|refactor|test
+```
+
+### Example
+
+
+| Commit message                                                                                                                                                                                   | Release type               |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------- |
+| `fix(pencil): stop graphite breaking when too much pressure applied`                                                                                                                             | Fix Release      |
+| `feat(pencil): add 'graphiteWidth' option`                                                                                                                                                       | Feature Release  |
+| `perf(pencil): remove graphiteWidth option`<br><br>`BREAKING CHANGE: The graphiteWidth option has been removed.`<br>`The default graphite width of 10mm is always used for performance reasons.` | Breaking Release <br /> (Note that the `BREAKING CHANGE: ` token must be in the footer of the commit) |
+
+
+For a base version of `0.1.0`, the following will apply:
+
+| Type                      | Release type example      | Notes                                                          |
+|---------------------------|---------------------------|----------------------------------------------------------------|
+| `fix`                     | increments to   `0.1.1`   |                                                                |
+| `feat`                    | increments to   `0.1.0`   | Resets any existing patch fixes e.g:   `0.1.3` will be `0.2.0` |
+| `BREAKING CHANGE` | Increments to `1.0.0`     | Can be added to any type                                                               |
+| All others                | No version increment      |                                                                |
+
+
+## CI setup
+
+!!! warning
+
+    This section covers important implications of setting up a base tag/release version (or lack of) in your repo before using `semantic-release`.
+
+### Base release version
+
+A semantic-release workflow is configured to run on the `main` branch and technically no further setup is required. However, the semantic-release initial version is set at `v1.0.0` (with pre-release options) instead of the generally accepted version `v0.1.0`. This may not be desirable for your project so a workaround is described below.
+
+!!! info
+
+    As per the semantic versioning [spec](https://semver.org/#how-should-i-deal-with-revisions-in-the-0yz-initial-development-phase), the initial development release should be `v0.1.0`. Optionally you can set it to `v0.0.0` if there is only an initial commit in the repo.
+
+
+<u>In the Github repo page:</u>
+
+1. Click on the **Create a new release** link on the right-hand panel
+
+2. Click on **Choose a tag**, type in your base version (e.g: `v0.1.0`) and hit enter
+
+3. Enter desired release title e.g: Pre-release
+
+4. Tick **This is a pre-release** checkbox
+
+5. Click the **Publish** button
+
+If you don't want to create a release and the steps above are one too many, you can create a tag via the command line:
+
+```bash
+# Within the `main` branch in your git repo
+git tag -a v0.1.0 -m "Pre-release"
+git push origin v0.1.0
+```
+
+## Local setup
+
+### Commitizen
+
+Use [commitzen](https://commitizen-tools.github.io/commitizen/) to ease following the commit message convention described [above](semantic-release.md#how).
+
+```
+pip install -U commitizen
+```
+
+For more installtion options see [here](https://commitizen-tools.github.io/commitizen/#installation).
+
+!!! info
+
+    Stage some files in your repo and type `cz commit` and you're ready to go!
+
+
+!!! tip
+
+    Decide on the commit convention scope in advance. This will keep it consistent and provide a coherent semantic mapping.
+
+
+## FAQ
+
+1. I have many `feat` type commits to be added to `main` but I don't want to trigger a release
+
+      For a Continous Deployment methodology, it is not uncommon to release small features frequently in isolation. This will undoubtedly increment your minor version but it is acceptable as it reflects the rapid changes in your project.
+
+      Alternatively, if you wish to batch features to trigger a release here are some options:
+
+      - **Release branch (recommended)**
+
+        Create a release branch and merge multiple `feat` type commits to it. When the release branch is ready and merged to `main`, it will condense the numerous `feat` type commits to generate a singular increment in the release version/tag.
+
+      - **Non-standard commit type**
+
+        Use a custom commit type such as:
+
+        ```bash
+        # Feature no release (featnr) denotes a feature but is not release ready
+        featnr(pencil): add 'graphiteWidth' option
+        ```

docs/continuous-integration/pre-commit.md

@@ -0,0 +1,13 @@
+# Sonarqube
+
+## What
+
+## Why
+
+## How
+
+## CI setup
+
+## Local setup
+
+N/A.

docs/continuous-integration/semantic-release.md

@@ -0,0 +1,7 @@
+!!! note
+
+    This is your project's home page.
+
+!!! to-do
+
+    Update the `site_name` config in the `mkdocs.yml` file within the root directory.