feat: improve changelog documentation and linting

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,18 +1,7 @@
 <!--
-# General contribution criteria
+Read the contribution guidelines before creating a pull request.
 
-Thanks for spending some time for improving and fixing Capsule!
-
-We're still working on the outline of the contribution guidelines but we're
-following ourselves these points:
-
-- reference a previously opened issue: https://docs.github.com/en/github/writing-on-github/autolinked-references-and-urls#issues-and-pull-requests 
-- including a sentence or two in the commit description for the
-  changelog/release notes
-- splitting changes into several and documented small commits
-- limit the git subject to 50 characters and write as the continuation of the
-  sentence "If applied, this commit will ..."
-- explain what and why in the body, if more than a trivial change, wrapping at
-  72 characters
+https://github.com/projectcapsule/capsule/blob/main/CONTRIBUTING.md
 
+Thanks for spending some time for improving and fixing Capsule!
 -->

.github/workflows/check-pr.yml

@@ -0,0 +1,48 @@
+name: "Check Pull Request"
+
+on:
+  pull_request_target:
+    types:
+      - opened
+      - edited
+      - synchronize
+
+permissions:
+  pull-requests: read
+
+jobs:
+  main:
+    name: Validate PR title
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@47b15d52c5c30e94a17ec87eb8dd51ff5221fed9
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          types: |
+            chore
+            ci
+            docs
+            feat
+            fix
+            test
+            sec
+          requireScope: false  
+          scopes: |
+            all
+            chart
+            operator
+            manifest
+            website
+            e2e
+            release
+            repo
+            deps
+            make
+          wip: true
+          # If the PR only contains a single commit, the action will validate that
+          # it matches the configured pattern.
+          validateSingleCommit: true
+          # Related to `validateSingleCommit` you can opt-in to validate that the PR
+          # title matches a single commit to avoid confusion.
+          validateSingleCommitMatchesPrTitle: true

.github/workflows/helm-test.yml

@@ -43,6 +43,10 @@ jobs:
             echo -e '\033[0;32mDocumentation up to date\033[0m ✔'
           fi
 
+      - name: Run chart-testing (install)
+        run: make helm-test
+        if: steps.list-changed.outputs.changed == 'true'
+
       # ATTENTION: This is a workaround for the upcoming ApiVersion Conversions for the capsule CRDs
       # With this workflow the current docker image is build and loaded into kind, otherwise the install fails
       # In the future this must be removed and the chart-testing-action must be used

.goreleaser.yml

@@ -66,9 +66,12 @@ changelog:
     - title: '📖 Documentation updates'
       regexp: ^.*?docs(\([[:word:]]+\))??!?:.+$
       order: 400
+    - title: '🛡️ Security updates'
+      regexp: ^.*?(sec)(\([[:word:]]+\))??!?:.+$
+      order: 500
     - title: '🚀 Build process updates'
       regexp: ^.*?(build|ci)(\([[:word:]]+\))??!?:.+$
-      order: 400
+      order: 600
     - title: '📦 Other work'
       order: 9999
 sboms:

CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+Changes are published with their type and scope for each release in the release description. Changes are assigned based on their commit description. Read more on how commits should be formatted in the [Contributing](CONTRIBUTING.md#commits) guide.
+
+See the [Releases](https://github.com/projectcapsule/capsule/releases)
+
+
+## Helm Chart
+
+For the helm chart, a dedicated changelog is created based on the chart's annotations ([See](./DEVELOPMENT.md#helm-changelog)).

CONTRIBUTING.md

@@ -2,9 +2,33 @@
 
 All contributions are welcome! If you find a bug or have a feature request, please open an issue or submit a pull request.
 
+## Ways to contribute
+
+### 1. Report Issues
+
+Issues to Capsule help improve the project in multiple ways including the following:
+
+  * Report potential bugs
+  * Request a feature
+  * Request a sample policy
+
+### 2. Engagement
+Engage with the community on [Slack](https://kubernetes.slack.com/archives/C03GETTJQRL) and help new users with questions or issues they may have.
+
+### 3. Submit changes
+Submit technical changes via pull requests. New contributors may easily view all open issues labeled as [good first issues](https://github.com/projectcapsule/capsule/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) allowing you to get started in an approachable manner.
+
+Once you wish to get started contributing to the code base, please refer to our [development guide](DEVELOPMENT.md) for a how-to. **[We accept pull requests from forks only](#create-a-pull-request)**.
+
+Before creating a pull request, please ensure that your changes are tested and that the documentation is updated accordingly.
+
+When creating a pull request, please visit:
+
+  * [commits](#commits)
 
 ## Guidelines
 
+The following guidelines outline the semantics and processes which apply to technical contributions to the project.
 
 ## Supported Versions
 Versions follow [Semantic Versioning](https://semver.org/) terminology and are expressed as `x.y.z`:
@@ -19,10 +43,129 @@ Prereleases are marked as `-rc.x` (release candidate) and may refere to any type
 
 ## Pull Requests
 
+The pull request title is checked according to the described [semantics](#semantics) (pull requests don't require a scope). However pull requests are currently not used to generate the changelog. Check if your pull requests body meets the following criteria:
+
+- reference a previously opened issue: https://docs.github.com/en/github/writing-on-github/autolinked-references-and-urls#issues-and-pull-requests 
+- splitting changes into several and documented small commits
+- limit the git subject to 50 characters and write as the continuation of the
+  sentence "If applied, this commit will ..."
+- explain what and why in the body, if more than a trivial change, wrapping at
+  72 characters
+
+If your pull request in a draft state and not ready yet for review, you can prefix the title with `[WIP]`. This will indicate that work is still ongoing:
+
+    [WIP] feat(controller): new cool feature
+
+### Create a Pull Request
+
+Head over to the project repository on GitHub and click the **"Fork"** button. With the forked copy, you can try new ideas and implement changes to the project.
+
+1. **Clone the repository to your device:**
+
+Get the link of your forked repository, paste it in your device terminal and clone it using the command.
+
+```sh
+git clone https://hostname/YOUR-USERNAME/YOUR-REPOSITORY
+```
+
+2. **Create a branch:**
+
+Create a new brach and navigate to the branch using this command.
+
+```sh
+git checkout -b <new-branch>
+```
+
+3. **Stage, Commit, and Push changes:**
+
+Now that we have implemented the required changes, use the command below to stage the changes and commit them.
+
+```sh
+git add .
+```
+
+```sh
+git commit -s -m "Commit message"
+```
+
+Go ahead and push your changes to GitHub using this command.
+
+```sh
+git push
+```
 
 ## Commits
 
-Commit messages should indicate the change and it's impact. The general format for commit messages is the following:
+The commit message is checked according to the described [semantics](#semantics). Commits are used to generate the changelog and their author will be referenced in the changelog.
+
+### Reorganising commits
+
+To reorganise your commits, do the following (or use your way of doing it):
+
+
+1. Pull upstream changes
+
+```bash
+git remote add upstream git@github.com:projectcapsule/capsule.git
+git pull upstream main
+```
+
+2. Pick the current upstream HEAD (the commit is marked with `(remote/main, main)`)
+
+```bash
+git log
+....
+commit 10bbf39ac1ac3ad4f8485422e54faa9aadf03315 (remote/main, main)
+Author: Oliver Bähler <oliverbaehler@hotmail.com>
+Date:   Mon Oct 23 10:24:44 2023 +0200
+
+    docs(repo): add sbom reference
+
+    Signed-off-by: Oliver Bähler <oliverbaehler@hotmail.com>
+```
+
+3. Soft reset to the commit of the upstream HEAD
+
+```bash
+git reset --soft 10bbf39ac1ac3ad4f8485422e54faa9aadf03315
+```
+
+4. Remove staged files (if any)
+
+```bash
+git restore --staged .
+```
+
+5. Add files manually and create new [commits](#commits), until all files are included
+
+```bash
+git add charts/capsule/
+git commit -s -m "feat(chart): add nodeselector value"
+
+...
+```
+
+6. Force push the changes to your fork
+
+```bash
+git push origin main -f
+```
+
+### Sign-Off
+
+Developer Certificate of Origin (DCO) Sign off
+For contributors to certify that they wrote or otherwise have the right to submit the code they are contributing to the project, we are requiring everyone to acknowledge this by signing their work which indicates you agree to the DCO found here.
+
+To sign your work, just add a line like this at the end of your commit message:
+
+Signed-off-by: Random J Developer <random@developer.example.org>
+This can easily be done with the -s command line option to append this automatically to your commit message.
+
+    git commit -s -m 'This is my commit message'
+
+## Semantics
+
+The semantics should indicate the change and it's impact. The general format for commit messages and pull requests is the following:
 
     feat(ui): Add `Button` component
     ^    ^    ^
@@ -32,38 +175,29 @@ Commit messages should indicate the change and it's impact. The general format f
 
  The commits are checked on pull-request. If the commit message does not follow the format, the workflow will fail. See the [Types](#types) and [Scopes](#scopes) sections for more information.
 
-## Types
+### Types
 
 The following types are allowed for commits and pull requests:
 
-  * `ci` or `build`: changes to buillding process/workflows
+  * `chore`: housekeeping changes, no production code change
+  * `ci`: changes to buillding process/workflows
   * `docs`: changes to documentation
   * `feat`: new features
   * `fix`: bug fixes
+  * `test`: test related changes
+  * `sec`: security related changes
 
-## Scopes
+### Scopes
 
 The following types are allowed for commits and pull requests:
 
   * `all`: changes that affect all components
   * `chart`: changes to the Helm chart
   * `operator`: changes to the operator
-  * `docs`: changes to the documentation
+  * `manifest`: changes to the manifest installer
   * `website`: changes to the website
-  * `ci`: changes to the CI/CD workflows
-  * `build`: changes to the build process
-  * `test`: changes to the testing process
+  * `e2e`: changes to the e2e testing process
   * `release`: changes to the release process
+  * `repo`: changes to general repository files
   * `deps`: dependency updates
-
-### Sign-Off
-
-Developer Certificate of Origin (DCO) Sign off
-For contributors to certify that they wrote or otherwise have the right to submit the code they are contributing to the project, we are requiring everyone to acknowledge this by signing their work which indicates you agree to the DCO found here.
-
-To sign your work, just add a line like this at the end of your commit message:
-
-Signed-off-by: Random J Developer <random@developer.example.org>
-This can easily be done with the -s command line option to append this automatically to your commit message.
-
-git commit -s -m 'This is my commit message'
+  * `make`: changes to Makefile

DEVELOPMENT.md

@@ -0,0 +1,46 @@
+# Development
+
+In Progress!
+
+
+## Helm Chart
+
+
+### Testing
+
+You can test your changes made to the helm chart locally. They are almost identical to the checks executed in the github workflows.
+
+Run chart linting (ct lint):
+
+```bash
+make helm-lint
+```
+
+Run chart tests (ct install):
+
+```bash
+make helm-test
+```
+
+### Documentation
+
+Documentation of the chart is done with [helm-docs](https://github.com/norwoodj/helm-docs). Therefor all documentation relevant changes for the chart must be done in the [README.md.gotmpl](./charts/capsule/README.md.gotmpl) file. You can run this locally with this command (requires running docker daemon):
+
+```bash
+make helm-docs
+
+...
+
+time="2023-10-23T13:45:08Z" level=info msg="Found Chart directories [charts/capsule]"
+time="2023-10-23T13:45:08Z" level=info msg="Generating README Documentation for chart /helm-docs/charts/capsule"
+```
+
+This will update the documentation for the chart in the `README.md` file. 
+
+### Helm Changelog 
+
+The `version` of the chart does not require a bump, since it's driven by our release process. The `appVersion` of the chart is the version of the Capsule project. This is the version that should be bumped when a new Capsule version is released. This will be done by the maintainers.
+
+To create the proper changelog for the helm chart, all changes which affect the helm chart must be documented as chart annotation. See all the available [chart annotations](https://artifacthub.io/docs/topics/annotations/helm/).
+
+This annotation can be provided using two different formats: using a plain list of strings with the description of the change or using a list of objects with some extra structured information (see example below). Please feel free to use the one that better suits your needs. The UI experience will be slightly different depending on the choice. When using the list of objects option the valid supported kinds are `added`, `changed`, `deprecated`, `removed`, `fixed` and `security`.

README.md

@@ -119,6 +119,10 @@ Please, refer to the maintainers file available [here](.github/maintainers.yaml)
 
 Please, refer to the [documentation page](https://capsule.clastix.io/docs/contributing/release).
 
+### Changelog
+
+Read how we log changes [here](CHANGELOG.md)
+
 ### Software Bill of Materials
 
 All OCI release artifacts include a Software Bill of Materials (SBOM) in CycloneDX JSON format. More information on this is available [here](SECURITY.md#software-bill-of-materials-sbom)