docs: add CONVENTIONS.md

.cspell.json

@@ -41,6 +41,7 @@
   "words": [
     "BOOTLOADER",
     "BUILDGCC",
+    "CODEOWNERS",
     "CPUS",
     "GOARCH",
     "HEALTHCHECK",
@@ -90,6 +91,8 @@
     "githubaction",
     "githubactions",
     "gocyclo",
+    "gofmt",
+    "gofumpt",
     "golangci",
     "gorecurcopy",
     "goreleaser",
@@ -142,6 +145,7 @@
     "skipframes",
     "sloglint",
     "startswith",
+    "staticcheck",
     "stmsg",
     "testregex",
     "textfile",

CONTRIBUTING.md

@@ -2,30 +2,26 @@
 
 We use GitHub to host code, to track issues and feature requests, as well as accept pull requests.
 
+For coding guidelines and commit message conventions, please look into [CONVENTIONS.md](https://github.com/9elements/firmware-action/blob/main/CONVENTIONS.md).
+
 
 ## Issues
 As usual, [check if issue already exists](https://docs.github.com/en/github/searching-for-information-on-github/searching-on-github/searching-issues-and-pull-requests#search-by-the-title-body-or-comments) in GitHub issue tracker.
 
-## Commit messages
-Please conform to [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification.
-
-
-## Used tools
+Please use issue template if applicable.
 
-### Linters
 
-#### MegaLinter
-[MegaLinter](https://megalinter.io/latest/) is used in [GitHub Flow](https://docs.github.com/en/get-started/quickstart/github-flow), which checks all the source code.
+## Pull Requests / Merge Requests
 
-Can be run locally, but it is pain. See [MegaLinter Runner](https://megalinter.io/latest/mega-linter-runner/).
+We accept GitHub pull requests.
 
+Fork the project on GitHub, work in your fork and in branches, push these to your GitHub fork, and when ready, do a GitHub pull requests against [https://github.com/9elements/firmware-action](https://github.com/9elements/firmware-action).
 
-#### commitlint
-[commitlint](https://github.com/conventional-changelog/commitlint) checks if the commit message conforms to [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification.
+Organize your changes in small and meaningful commits which are easy to review. Not every commit in your pull request needs to be able to build and pass the CI tests, but the whole PR must build and pass CI all tests.
 
-To run locally, check [Tooling for Conventional Commits](https://www.conventionalcommits.org/en/about/#tooling-for-conventional-commits).
+If the pull request closes an issue please note it as: "Fixes #NNN".
 
 
-### editorconfig
-Please make sure to conform to provided [editorconfig](https://editorconfig.org/).
+## Code Reviews
 
+It is not necessary to tag anyone for review, we are using [CODEOWNERS](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) file to define individuals or teams that are responsible. They will be tagged automatically.

CONVENTIONS.md

@@ -0,0 +1,61 @@
+# Conventions
+
+
+## File formatting
+
+To maintain consistent coding styles, indentation, line length and so on we are using [.editorconfig](https://editorconfig.org/).
+
+
+## Coding style
+
+For golang code, please use `gofumpt` (a strict formatter for Go language, stricter than gofmt) before contributing. On top of that please fix all reported issues by linters such as `revive`, `go vet`, `staticcheck` and `golangci-lint` (up-to-date list of used linters is in `Taskfile.yml` in `lint` task.
+
+
+## Guidelines for writing good functional code
+
+When writing code, you MUST follow these principles:
+- Code should be easy to read and understand.
+- Keep the code as simple as possible. Avoid unnecessary complexity.
+- Use meaningful names for variables, functions, etc. Names should reveal intent.
+- Functions should be small and do one thing well. They should not exceed a few lines.
+- Function names should describe the action being performed.
+- Prefer fewer arguments in functions. Ideally, aim for no more than two or three.
+- Only use comments when necessary, as they can become outdated. Instead, strive to make the code self-explanatory.
+- When comments are used, they should add useful information that is not readily apparent from the code itself.
+- Properly handle errors and exceptions to ensure the software's robustness.
+- Consider security implications of the code. Implement security best practices to protect against vulnerabilities and attacks.
+
+
+## Commit message guidelines
+
+Please follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification.
+
+
+### Developer Sign-Off
+
+For purposes of tracking code-origination, we follow a simple sign-off process. If you can attest to the [Developer Certificate of Origin](https://developercertificate.org/) then you append in each git commit text a line such as:
+
+```
+Signed-off-by: Your Name <username@youremail.com>
+```
+
+
+### Use of AI generated content
+
+Use of purely AI generated or partially AI assisted content is permitted, however please mark it as AI generated in the commit message body by adding:
+```
+AI-Generated: true
+AI-Model: <model used>
+```
+For example:
+```
+feat(...): add new feature
+
+- adding new fun thing
+
+AI-Generated: true
+AI-Model: ChatGPT o3-mini
+Signed-off-by: ...
+```
+
+This must follow [git trailer convention](https://git-scm.com/docs/git-interpret-trailers).