Trice Maintenance

Contents

1. Trice Project structure (Files and Folders)
2. 📁 The .github Folder — Purpose and Contents
3. Trice Reference Manual Maintenance (or any *.md file)
4. Cleaning the Sources

1. Trice Project structure (Files and Folders)

Trice Root Folder File	Details
.clang-format	See GitHub Action clang-format.yml - Check C Code Formatting
.clang-format-ignore	See GitHub Action clang-format.yml - Check C Code Formatting
.code_snippets	Some legacy helper code for copying where to use
.editorconfig	See GitHub Action clang-format.yml - Check C Code Formatting
`.git/`	Git repository metadata (exists locally after cloning; not part of the repository content)
.gitattributes	See GitHub Action clang-format.yml - Check C Code Formatting
.github/	📁 The .github Folder — Purpose and Contents
.gitignore	git ignores these files
.goreleaser.yaml	goreleaser configuration
.idea/	GoLand settings
lychee.toml	GitHub Action link-check.yml - Broken Links Check
.markdownlint.yaml	Cleaning the Sources
.markdownlintignore	Cleaning the Sources
.vscode/	VS Code settings
AUTHORS.md	contributors
CHANGELOG.md	History
CODE_OF_CONDUCT.md	How to communicate
CONTRIBUTING.md	Helper
LICENSE.md	MIT
README.md	GitHub first page
_config.yml	jekyll configuration
_test	automatic target code tests
scripts/buildTriceTool.sh	Build Trice tool from Go sources
scripts/_150_setup_build_environment.sh	see inside
scripts/_280_format_c_code.sh	See GitHub Action clang-format.yml - Check C Code Formatting
scripts/_300_clean_dsstore.sh	Run to remove macOS artifacts
`temp/log/coverage.out`	Go test coverage output
cmd/clang-filter	ReadMe
cmd/trice	Trice tool command Go sources
`demoLI.json`	locally generated location information; see LI initialization
demoTIL.json	Trice ID list example
`dist/`	local distribution files folder created by GoReleaser
docs	Guide, User Manual, Reference Manual, and supporting material; start with the Trice Guide
examples/	example target projects
scripts/_310_refresh_trice_user_manual.sh	Trice Reference Manual Maintenance (or any `*.md` file)
scripts/gitAddWorktreeFromGitLogLineData.sh	helper to get easy a git worktree folder from any git hash for easy folder compare, see inside
scripts/gitAddWorktreesBetween.sh	helper to get easy git worktree folders from any time range
scripts/gitLogWithBranches.sh	helper to get easy a history view
go.mod	Go modules file
go.sum	Go modules sums
index.md	Jekyll index site for README.md
internal/	Trice tool internal Go packages
pkg/	Trice tool common Go packages
scripts/_330_renew_ids_and_refresh_tests.sh	deliberate legacy ID re-seeding and CGO harness refresh; see Target Tests
src/	C sources for trice instrumentation -> Add to target project
`temp/`	ignored local workspace for binary logfiles and other runtime artifacts like `scripts/testAll.sh` helper files under `./temp/log`
`testAll.log`	ignored local output of the last `./scripts/testAll.sh` run
scripts/testAll.sh	run all tests
third_party/	external components
trice_bindIDs_in_examples_and_test_folder.sh	run the canonical Trice Bind workflow
scripts/_240_legacy_clean_ids.sh	Cleaning the Sources Activating the Trice Cache
scripts/_120_setup_trice_environment.sh	Cleaning the Sources Activating the Trice Cache
scripts/_230_legacy_insert_ids.sh	Cleaning the Sources Activating the Trice Cache

(back to top)

2. 📁 The .github Folder — Purpose and Contents

GitHub automatically recognizes and uses everything contained inside the .github/ directory. This folder defines how the project behaves on GitHub: issue templates, automated workflows, labels, code scanning, greetings, and release automation. Details:

2.1. 📁 `.github` Root

It contains issue templates, labels, workflow automation, code scanning, linting, and the CI/CD release pipeline.

ISSUE_TEMPLATE/ Used to create structured bug reports and feature requests.
FUNDING.yml Enables the GitHub “Sponsor” button.
labeler.yml configuration file consumed by actions/labeler. It defines the labeling rules.
- Because labeler.yml is configuration and not an executable workflow, it is placed directly under .github/, not under .github/workflows/.
- The actions/labeler action expects .github/labeler.yml as the default configuration path, which is why this layout is standard and correct.
- This is intentional and follows GitHub Actions conventions.
  - .github/workflows/label.yml is a workflow. It defines when and how the GitHub Action runs (triggers, permissions, runner, action reference).
  - .github/labeler.yml is not a workflow. It is a configuration file consumed by actions/labeler. It defines the labeling rules.
.github/workflows/ Contains GitHub Actions automation

2.2. 📂 `.github/workflows` — GitHub Actions Workflows

The .github/workflows/ folder contains YAML descriptions for various actions, which will be triggered automatically on certain events or are started manually. Every yml file in this directory defines an automated process. These processes run on GitHub’s servers (CI/CD).

README.md: Documentation specifically for the /workflows folder.
- Can be useful for contributors who want to understand or modify CI behaviors. Each workflow defines its own triggers and permissions in its YAML file. Depending on the workflow, it runs on pushes, pull requests, a schedule, a manual request, or a call from another workflow. The directory contains no separate icon or properties metadata for configuring these workflows.

GitHub Action	About
clang-format.yml	GitHub Action clang-format.yml - Check C Code Formatting
codeql.yml	GitHub Action codeql.yml - Static Code Analysis
coverage.yml	GitHub Action coverage.yml - Test Coverage and Coveralls Integration
go.yml	GitHub Action go.yml - Building and Testing Go Code
goreleaser.yml	GitHub Action goreleaser.yml - Build & Pack Trice Distribution
label.yml	GitHub Action label.yml - Automatic Labeling Rules
link-check.yml	GitHub Action link-check.yml - Broken Links Check
shellcheck.yml	GitHub Action shellcheck.yml - Catching Common Bash Scripts Bugs
shfmt.yml	GitHub Action shfmt.yml - Ensure Consistent Shell Scripts Formatting
stale.yml	GitHub Action stale.yml - Automatic Stale Issue Handling
superlinter.ym	GitHub Action superlinter.yml - Ensure Consistent YAML and Markdown Formatting
pages.yml	GitHub Action pages.yml - Creates The Trice GitHub Pages

2.3. GitHub Action clang-format.yml - Check C Code Formatting

Local Action (developer machine): ./scripts/_280_format_c_code.sh - adjust all C files excluding .clang-format-ignore according rule set in .clang-format.
The file ./scripts/_280_format_c_code.sh is used to auto-format the Trice code.

File .clang-format

Contributor: @Sazerac4

Sazerac4 commented Aug 29, 2024: I have a code formatter when I make changes to my application but I would like to keep the style of the library when modifying. I couldn’t find a code formatter, is there a tool used? If not, I propose this to provide one as an example by using clang-format.
```
## I have created a default style :
clang-format -style=llvm -dump-config > .clang-format
## Then format the code:
find ./src  -name '*.c' -o  -name '*.h'| xargs clang-format-18 -style=file -i
```
The style of the example does not correspond to the original one. Configurations are necessary for this to be the case. Tags can be placed to prevent certain macros from being formatted
```
int formatted_code;
// clang-format off
    void    unformatted_code  ;
// clang-format on
void formatted_code_again;
```
I have tuned some settings for clang-format :
```
* IndentWidth: 4  // original code size indentation
* ColumnLimit: 0  // avoid breaking long line (like macros)
* PointerAlignment: Left  // like original files (mostly)
```
With preprocessor indentation, the result is a bit strange in some cases. It’s possible with the option IndentPPDirectives (doc).

Staying as close as possible to a default version (LLVM in this case) makes it easier to regenerate the style if necessary.

See also: https://github.com/rokath/trice/pull/487#issuecomment-2318003072

File .clang-format-ignore:

Contributor: @Sazerac4

Sazerac4 commented Aug 30, 2024: I have added .clang-format-ignore to ignore formatting for specific files

File .editorconfig:

Contributor: @Sazerac4

The.editorconfig file allows to better identify the basic style for every files. (endline, charset, …). It is a file accepted by a wide list of IDEs and editors : link This addition is motivated by forgetting the end of line in the .gitattributes file.

File .gitattributes

Contributor: @Sazerac4

With the.gitattributes file avoid problems with “diff” and end of lines. Here is an article that presents the problem.

To fill the.gitattributes, I used the command below to view all the extensions currently used.
```
git ls-tree -r HEAD --name-only | perl -ne 'print $1 if m/\.([^.\/]+)$/' | sort -u
```
GitHub Action (Continuous Integration): .github/workflows/clang-format.yml does not format, it only checks.

2.4. GitHub Action codeql.yml - Static Code Analysis

This workflow runs CodeQL, GitHub’s static code analysis tool. Purpose:
- scan the codebase for potential security vulnerabilities
- detect unsafe code patterns
- provide security alerts in the “Security” tab
- Runs automatically on pushes and pull requests.
GitHub Action (Continuous Integration): .github/workflows/codeql.yml
- This workflow configures GitHub CodeQL code scanning for the repository.
- This workflow continuously scans the codebase for security and quality problems using CodeQL.
- It performs static code analysis on source code.
- It looks for:
  - Security vulnerabilities (e.g. injection flaws, unsafe API usage)
  - Common programming errors
  - Code quality issues
- It runs automatically:
- On pushes to main
- On pull requests targeting main
- Manually via the GitHub Actions UI
- The results are uploaded to GitHub and appear under Security → Code scanning alerts.
- The “QL” is the same concept as SQL, but specialized for code analysis.

2.5. GitHub Action coverage.yml - Test Coverage and Coveralls Integration

Trice uses Go’s built-in coverage tooling to measure how much of the Go codebase is exercised by automated tests.

Local Action (developer machine):

Action	Command
Generate a coverage profile locally	`go test ./... -covermode=atomic -coverprofile=./temp/log/coverage.out`
Show results as list in terminal	`go tool cover -func=./temp/log/coverage.out`
Show results colored file specific in browser	`go tool cover -html=./temp/log/coverage.out`

GitHub Action (Continuous Integration):
On GitHub, the workflow .github/workflows/coverage.yml runs automatically for every pull request and also on a monthly schedule. The workflow:
1. executes go test with coverage enabled,
2. prints a coverage summary in the CI logs,
3. uploads the raw coverage.out file as a workflow artifact, and
4. publishes the coverage results to Coveralls (if configured).

Coverage badge:
The README displays the current coverage status for the default branch using the Coveralls badge:

[![Coverage Status](https://coveralls.io/repos/github/rokath/trice/badge.svg?branch=master)](https://coveralls.io/github/rokath/trice?branch=master)

This badge is updated whenever the CI workflow successfully uploads a new coverage report for the master branch.

2.6. GitHub Action go.yml - Building and Testing Go Code

A workflow for building and testing Go code. It runs GitHub CodeQL for Go and C (cpp language pack), detecting security vulnerabilities and code issues.
- Typically includes steps such as:
- setting up the Go toolchain
- checking out the repository
- compiling the project
- running unit tests
Local Action (developer machine): go test ./... or better ./scripts/testAll.sh full (takes long)
GitHub Action (Continuous Integration): .github/workflows/go.yml

2.7. GitHub Action goreleaser.yml - Build & Pack Trice Distribution

This workflow runs GoReleaser, the tool that builds and packages Trice for distribution.

Purpose:
- create release binaries for all supported platforms
- generate archives (ZIP, tar.gz, etc.)
- compute checksums
- create a GitHub Release with all artifacts
Triggers:
- manually from the GitHub UI (“Run workflow”)
- automatically when pushing a tag matching v* (e.g., v0.44.0)
- This is the workflow responsible for generating official Trice releases.
Local Action (developer machine): goreleaser
GitHub Action (Continuous Integration): .github/workflows/goreleaser.yml

2.8. GitHub Action label.yml - Automatic Labeling Rules

Defines automatic labeling rules for issues and PRs.
- For example, files in certain directories may automatically get category labels.
- This helps maintainers classify submissions more easily.
GitHub Action (Continuous Integration): .github/workflows/label.yml

2.9. GitHub Action link-check.yml - Broken Links Check

Local Action (developer machine): ./scripts/_530_test_links.sh from the repository root, also included in ./scripts/testAll.sh.
- Uses lychee.toml as configuration; the direct checker command is lychee --config lychee.toml ..
- The script additionally maps the CLI-help source URL to the local checkout and records results in temp/log/_530_test_links.log. If Lychee is missing, it reports a skip.
- For GitHub URLs, set GITHUB_TOKEN or GH_TOKEN locally as well to reduce API throttling and timeouts during checks
GitHub Action (Continuous Integration): .github/workflows/link-check.yml
- The workflow already provides GITHUB_TOKEN to the Lychee action for GitHub-hosted links

2.10. GitHub Action manual.ym - To Be Triggered Manually

A workflow that is designed to be triggered manually (similar to workflow_dispatch workflows). Common use cases:

executing maintenance tasks
running scripts on demand
testing workflow behavior without making a commit
This workflow does not run automatically.

2.11. GitHub Action shellcheck.yml - Catching Common Bash Scripts Bugs

Runs ShellCheck on all *.sh files, catching common bugs in Bash scripts.

GitHub Action (Continuous Integration): .github/workflows/shellcheck.yml

2.12. GitHub Action shfmt.yml - Ensure Consistent Shell Scripts Formatting

Runs shfmt in diff mode on pull requests to ensure consistent formatting of shell scripts.

Local Action (developer machine): go test ./... or better ./scripts/testAll.sh full (takes long)
GitHub Action (Continuous Integration): .github/workflows/shfmt.yml

2.13. GitHub Action stale.yml - Automatic Stale Issue Handling

Automates stale issue handling. Function:

marks inactive issues or PRs as “stale”
closes them after a configurable time period if there is no further activity
eps the issue tracker manageable.

Mark stale issues and pull requests

GitHub Action (Continuous Integration): .github/workflows/stale.yml

2.14. GitHub Action superlinter.yml - Ensure Consistent YAML and Markdown Formatting

Local Action (developer machine): markdownlint .
Runs GitHub Super Linter, a powerful linting suite. Purpose:
- ensure consistent code formatting
- detect stylistic issues
- catch potential errors in supported languages
- Helps maintain code quality across the entire repository.
GitHub Action (Continuous Integration): .github/workflows/superlinter.yml
- Checks YAML and Markdown files

2.15. GitHub Action pages.yml - Creates The Trice GitHub Pages

This workflow creates the Trice github pages avaliable under rokath.github.io/trice/.

GitHub Action (Continuous Integration): .github/workflows/pages.yml

3. Trice Reference Manual Maintenance (or any `*.md` file)

Recommended Tool: VS Code with some extensions:
- Markdown All in One (Yu Zhang)
- Markdown Table Prettifier (Kristin Daroczi)
  - Click in mouse context menu the entry “Format Document” to adjust Markdown tables.
- Markdown Preview Enhanced
  - Click the preview button in the top right.
- mdtoc
  - The User Manual and RM chapters contain managed TOC containers and persisted settings. Keep these markers in place where each table of contents should be generated. List every RM chapter in docs/rm/README.md.
      
  - Run ./scripts/_310_refresh_trice_user_manual.sh format to regenerate TOCs, numbering and anchors in the User Manual and all managed RM chapters with mdtoc.
  - Run ./scripts/_310_refresh_trice_user_manual.sh check to verify both manuals without editing them. Missing chapters, incomplete TOC containers and chapters omitted from the RM overview fail before formatting starts.
  - The repository no longer uses a VS Code TOC extension for manual maintenance.
- Markdown Paste (telesoho)
  - Helpful to get web site content preformatted as Markdown. Use mouse context menu.
- markdownlint (David Anson)
  - Uses .markdownlint.yaml as rule set and .markdownlintignore to ignore files.
  - You can also run markdownlint . in a terminal after installing the CLI tool. It uses the same control files.
  - The GitHub action superlinter.yml uses .markdownlint.yaml and the same config files.
- Markdown PDF (yzane)
  - Use Shift-Command-P “markdown PDF:export” to generate a PDF
  - page break for PDF generation: <div style="page-break-before: always;"></div>

4. Cleaning the Sources

In GitHub are some Actions defined. Some of them get triggered on a git push and perform some checks. To get no fail, some scripts should run before committing:

./scripts/format_repo.sh check checks manual, shell, Go and C formatting. It preserves sources, ID metadata, example build outputs and .DS_Store files; it does not install formatters. Temporary formatter files are removed on exit.
./scripts/format_repo.sh format also refreshes Bind headers, cleans example build outputs and removes .DS_Store files. Run it separately from testAll.sh.
docs/_scratchPad/ contains notes and historical sources. It is excluded from repository-wide Go discovery, formatting, linting and link checks; no go.mod is needed there.
npx markdownlint *.md (or just markdownlint) - uses .markdownlint.yaml to allow exceptions.
- npx markdownlint ./docs/rm/*.md 2>&1 | awk '!seen[$2]++' for example to reduce message count in case of errors.
./scripts/_300_clean_dsstore.sh - remove macOS maintenance data.
./scripts/_240_legacy_clean_ids.sh removes all IDs in the legacy workflow.