Template DX

A comprehensive Development Experience (DX) template repository that provides a structured framework and essential tools to streamline the software development process.

• 1. Details
  • 1.1. Prerequisites
• 2. Contribute
  • 2.1. AI Agents
  • 2.2. Task Runner
    • 2.2.1. Make
  • 2.3. Bootstrap
    • 2.3.1. Scripts
  • 2.4. Dev Containers
  • 2.5. Release Manager
    • 2.5.1. Semantic-Release
  • 2.6. Update Manager
    • 2.6.1. Renovate
    • 2.6.2. Dependabot
  • 2.7. Secrets Manager
    • 2.7.1. SOPS
  • 2.8. Container Manager
    • 2.8.1. Docker
  • 2.9. Policy Manager
    • 2.9.1. Conftest
  • 2.10. Supply Chain Manager
    • 2.10.1. Trivy
• 3. Troubleshoot
  • 3.1. TODO
• 4. References

1. Details

1.1. Prerequisites

• Git

  Distributed version control system for tracking source code changes.

• Git LFS

  Git extension for managing large files (assets, binaries) outside normal Git history.

• Make

  Task automation tool to manage build processes and workflows.

• Docker

  Containerization tool to run applications in isolated container environments and execute container-based tasks.

2. Contribute

Contribution guidelines and project management tools.

2.1. AI Agents

AI Agents are automated tools that assist in various development tasks such as code generation, testing, and documentation.

1. Insights and Details

   • AGENTS.md

     Instructions for AI coding agents working with the project.

   • SKILL.md

     Instructions for AI agent skills used in the project.

2. Usage and Instructions

   • Implicit Invocation

     AI Agents can be implicitly invoked based on file paths, programming languages, or specific keywords in user prompts.

     .github/skills/<skill-name>/SKILL.md
     

   • Explicit Invocation

     AI Agents can be explicitly invoked by specifying the skill name in user prompts.

     @agent <skill-name> <task-description>
     

2.2. Task Runner

2.2.1. Make

Make is a automation tool that defines and manages tasks to streamline development workflows.

1. Insights and Details

   • Makefile

     Makefile defining tasks for building, testing, and managing the project.

2. Usage and Instructions

   • Tasks

     make help

     [!NOTE]

     • Each task description must begin with ## to be included in the task list.

     $ make help
     
     Tasks
             A collection of tasks used in the current project.
     
     Usage
             make <task>
     
             bootstrap         Initialize a software development workspace with requisites
             setup             Install and configure all dependencies essential for development
             teardown          Remove development artifacts and restore the host to its pre-setup state
     

2.3. Bootstrap

2.3.1. Scripts

1. Insights and Details

   • scripts/

     Provides scripts to bootstrap, setup, and teardown a software development workspace with requisites.

2. Usage and Instructions

   • Tasks

     make bootstrap

     make setup

     make teardown

2.4. Dev Containers

1. Insights and Details

   • .devcontainer/

     Provides Dev Containers as a consistent development environment using Docker containers.

2. Usage and Instructions

   • Tasks

     # TODO
     # make devcontainer-go
     # make devcontainer-cpp
     # make devcontainer-python

2.5. Release Manager

2.5.1. Semantic-Release

Semantic-Release automates the release process by analyzing commit messages to determine the next version number, generating changelog and release notes, and publishing the release.

1. Insights and Details

   • .releaserc.json

     Configuration file for Semantic-Release specifying release rules and plugins.

2. Usage and Instructions

   • CI/CD

     uses: sentenz/actions/semantic-release@latest

2.6. Update Manager

2.6.1. Renovate

Renovate automates dependency updates by creating merge requests for outdated dependencies, libraries and packages.

1. Insights and Details

   • renovate.json

     Configuration file for Renovate specifying update rules and schedules.

2. Usage and Instructions

   • CI/CD

     uses: sentenz/actions/renovate@latest

2.6.2. Dependabot

Dependabot automates dependency updates by creating pull requests for outdated dependencies, libraries and packages.

1. Insights and Details

   • .github/dependabot.yml

     Configuration file for Dependabot specifying update rules and schedules.

2.7. Secrets Manager

2.7.1. SOPS

SOPS (Secrets OPerationS) is a tool for managing and encrypting sensitive data such as passwords, API keys, and other secrets.

1. Insights and Details

   • .sops.yaml

     Configuration file for SOPS specifying encryption rules and key management.

2. Usage and Instructions

   • GPG Key Pair Generation

     • Tasks

       Generate a new key pair to be used with SOPS.

       [!NOTE] The UID can be customized via the SECRETS_SOPS_UID variable (defaults to sops-dx).

       make secrets-gpg-generate SECRETS_SOPS_UID=<uid>

   • GPG Public Key Fingerprint

     • Tasks

       Print the GPG Public Key fingerprint associated with a given UID.

       make secrets-gpg-show SECRETS_SOPS_UID=<uid>

     • .sops.yaml

       The GPG UID is required for populating in .sops.yaml.

       creation_rules:
         - pgp: "<fingerprint>" # <uid>

   • SOPS Encrypt/Decrypt

     • Tasks

       Encrypt/decrypt one or more files in place using SOPS.

       make secrets-sops-encrypt <files>

       make secrets-sops-decrypt <files>

2.8. Container Manager

2.8.1. Docker

Docker containerization tool to run applications in isolated container environments and execute container-based tasks.

1. Insights and Details

   • Dockerfile

     Dockerfile defining the container image for the project.

2. Usage and Instructions

   • CI/CD

     # TODO

   • Tasks

     # TODO

2.9. Policy Manager

2.9.1. Conftest

Conftest is a Policy as Code (PaC) tool to streamline policy management for improved development, security and audit capability.

1. Insights and Details

   • conftest.toml

     Configuration file for Conftest specifying policy paths and output formats.

   • tests/policy/

     Directory contains Rego policies for Conftest to enforce best practices and compliance standards.

2. Usage and Instructions

   • CI/CD

     uses: sentenz/actions/regal@latest

     uses: sentenz/actions/conftest@latest

   • Tasks

     make policy-regal-lint <filepath>

     make policy-conftest-test <filepath>

2.10. Supply Chain Manager

2.10.1. Trivy

Trivy is a comprehensive security scanner for vulnerabilities, misconfigurations, and compliance issues in container images, filesystems, and source code.

1. Insights and Details

   • trivy.yaml

     Configuration file for Trivy specifying scan settings and options.

   • .trivyignore

     File specifying vulnerabilities to ignore during Trivy scans.

2. Usage and Instructions

   • CI/CD

     uses: sentenz/actions/trivy@latest

   • Tasks

     make sast-trivy-fs <path>

     make sast-trivy-sbom-cyclonedx-fs <path>

     make sast-trivy-sbom-scan <sbom_path>

     make sast-trivy-sbom-license <sbom_path>

3. Troubleshoot

3.1. TODO

TODO

4. References

• Sentenz Template DX repository.
• Sentenz Template C++ repository.
• Sentenz Actions repository.
• Sentenz Manager Tools article.