diff --git a/.github/ISSUE_TEMPLATE/question.yml b/.github/ISSUE_TEMPLATE/question.yml new file mode 100644 index 0000000..bf529b3 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/question.yml @@ -0,0 +1,82 @@ +--- +name: ❓ Question / Help +description: Ask a usage question or get help with SonarMark +title: "[Question]: " +labels: ["question"] +assignees: [] +body: + - type: markdown + attributes: + value: | + Thanks for reaching out! Please fill out the sections below so we can help you as quickly as possible. + For general discussion, you can also use + [GitHub Discussions](https://github.com/demaconsulting/SonarMark/discussions). + + - type: textarea + id: question + attributes: + label: Question + description: A clear and concise description of what you need help with. + placeholder: What would you like to know or understand? + validations: + required: true + + - type: textarea + id: what-tried + attributes: + label: What Have You Tried? + description: Describe what you have already attempted, including any code or configuration you have used. + placeholder: | + ```bash + sonarmark --server https://sonarcloud.io --project-key my-project + ``` + render: bash + + - type: textarea + id: expected + attributes: + label: Expected Outcome + description: A clear and concise description of what you expected to happen or what you are trying to achieve. + placeholder: Describe the outcome you are looking for... + validations: + required: true + + - type: input + id: version + attributes: + label: Tool Version + description: What version of SonarMark are you using? + placeholder: e.g., 1.0.0 + validations: + required: true + + - type: dropdown + id: dotnet-version + attributes: + label: .NET Version + description: What version of .NET are you using? + options: + - ".NET 8" + - ".NET 9" + - ".NET 10" + - Other (please specify in additional context) + validations: + required: true + + - type: textarea + id: additional-context + attributes: + label: Additional Context + description: Add any other context, screenshots, or links that may help answer your question. + placeholder: Any additional information... + + - type: checkboxes + id: checklist + attributes: + label: Checklist + description: Please confirm the following + options: + - label: I have searched existing issues and discussions to ensure this has not been answered before + required: true + - label: I have provided a clear description of my question + required: true diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index 9d361bf..442bba5 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -90,7 +90,7 @@ jobs: strategy: matrix: - os: [windows-latest, ubuntu-latest] + os: [windows-latest, ubuntu-latest, macos-latest] runs-on: ${{ matrix.os }} @@ -124,8 +124,8 @@ jobs: run: | mkdir -p artifacts echo "Capturing tool versions..." - # Create short job ID: build-win, build-ubuntu - OS_SHORT=$(echo "${{ matrix.os }}" | sed 's/windows-latest/win/;s/ubuntu-latest/ubuntu/') + # Create short job ID: build-windows, build-ubuntu, build-macos + OS_SHORT=$(echo "${{ matrix.os }}" | sed 's/-latest//') JOB_ID="build-${OS_SHORT}" dotnet versionmark --capture --job-id "${JOB_ID}" \ --output "artifacts/versionmark-${JOB_ID}.json" -- \ @@ -230,6 +230,7 @@ jobs: uses: github/codeql-action/init@v4 with: languages: csharp + build-mode: manual queries: security-and-quality config-file: ./.github/codeql-config.yml @@ -285,7 +286,7 @@ jobs: strategy: matrix: - os: [windows-latest, ubuntu-latest] + os: [windows-latest, ubuntu-latest, macos-latest] dotnet-version: ['8.x', '9.x', '10.x'] steps: @@ -331,8 +332,8 @@ jobs: run: | mkdir -p artifacts echo "Capturing tool versions..." - # Create short job ID: int-win-8, int-win-9, int-ubuntu-8, etc. - OS_SHORT=$(echo "${{ matrix.os }}" | sed 's/windows-latest/win/;s/ubuntu-latest/ubuntu/') + # Create short job ID: int-windows-8, int-ubuntu-9, int-macos-10, etc. + OS_SHORT=$(echo "${{ matrix.os }}" | sed 's/-latest//') DOTNET_SHORT=$(echo "${{ matrix.dotnet-version }}" | sed 's/\.x$//') JOB_ID="int-${OS_SHORT}-${DOTNET_SHORT}" dotnet versionmark --capture --job-id "${JOB_ID}" \ diff --git a/AGENTS.md b/AGENTS.md index af7f7b1..3afffe2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,6 +12,18 @@ SonarQube/SonarCloud analysis results. - **Code Quality Agent** - Enforces linting, static analysis, and security standards - **Repo Consistency Agent** - Ensures SonarMark remains consistent with TemplateDotNetTool template patterns +## Agent Selection Guide + +- Fix a bug → **Software Developer** +- Add a new feature → **Requirements Agent** → **Software Developer** → **Test Developer** +- Write a test → **Test Developer** +- Fix linting or static analysis issues → **Code Quality Agent** +- Update documentation → **Technical Writer** +- Add or update requirements → **Requirements Agent** +- Ensure test coverage linkage in `requirements.yaml` → **Requirements Agent** +- Run security scanning or address CodeQL alerts → **Code Quality Agent** +- Propagate template changes → **Repo Consistency Agent** + ## Tech Stack - C# (latest), .NET 8.0/9.0/10.0, MSTest, dotnet CLI, NuGet @@ -38,6 +50,7 @@ evidence. This is critical for platform and framework requirements - **do not re - `windows@TestName` - proves the test passed on a Windows platform - `ubuntu@TestName` - proves the test passed on a Linux (Ubuntu) platform +- `macos@TestName` - proves the test passed on a macOS platform - `net8.0@TestName` - proves the test passed under the .NET 8 target framework - `net9.0@TestName` - proves the test passed under the .NET 9 target framework - `net10.0@TestName` - proves the test passed under the .NET 10 target framework diff --git a/README.md b/README.md index 2270fe2..02bbd5a 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,10 @@ documentation workflows. - 🌐 **Multi-Platform** - Support for .NET 8, 9, and 10 across Windows, Linux, and macOS - ✅ **Self-Validation** - Built-in tests to verify functionality without requiring a live server - 🔗 **API Integration** - Direct integration with SonarQube and SonarCloud REST APIs +- 🔍 **Linting Enforcement** - markdownlint, cspell, and yamllint enforced on every CI run +- 📋 **Continuous Compliance** - Compliance evidence generated automatically on every CI run, following + the [Continuous Compliance][link-continuous-compliance] methodology +- 🗂️ **Requirements Traceability** - Requirements linked to passing tests with auto-generated trace matrix ## Installation @@ -271,3 +275,4 @@ SonarMark is built with the following open-source projects: [link-quality]: https://sonarcloud.io/dashboard?id=demaconsulting_SonarMark [link-security]: https://sonarcloud.io/dashboard?id=demaconsulting_SonarMark [link-nuget]: https://www.nuget.org/packages/DemaConsulting.SonarMark +[link-continuous-compliance]: https://github.com/demaconsulting/ContinuousCompliance diff --git a/docs/guide/guide.md b/docs/guide/guide.md index ccf5af1..fadb1ed 100644 --- a/docs/guide/guide.md +++ b/docs/guide/guide.md @@ -30,6 +30,20 @@ This user guide covers: - **CI/CD Integration**: Support for enforcement mode to fail builds on quality gate failures - **Multi-Platform**: Works on Windows, Linux, and macOS with .NET 8, 9, or 10 +# Continuous Compliance + +SonarMark follows the [Continuous Compliance][continuous-compliance] methodology, which ensures +compliance evidence is generated automatically on every CI run. + +## Key Practices + +- **Requirements Traceability**: Every requirement is linked to passing tests, and a trace matrix is + auto-generated on each release +- **Linting Enforcement**: markdownlint, cspell, and yamllint are enforced before any build proceeds +- **Automated Audit Documentation**: Each release ships with generated requirements, justifications, + trace matrix, and quality reports +- **CodeQL and SonarCloud**: Security and quality analyses run on every build + # Installation ## Prerequisites @@ -649,3 +663,4 @@ fi [security]: https://github.com/demaconsulting/SonarMark/blob/main/SECURITY.md [sonarqube-docs]: https://docs.sonarqube.org/latest/ [sonarcloud-docs]: https://docs.sonarcloud.io/ +[continuous-compliance]: https://github.com/demaconsulting/ContinuousCompliance diff --git a/requirements.yaml b/requirements.yaml index c6ff49a..6293566 100644 --- a/requirements.yaml +++ b/requirements.yaml @@ -20,6 +20,7 @@ # Source filter prefixes: # windows@TestName - proves the test passed on a Windows platform # ubuntu@TestName - proves the test passed on a Linux (Ubuntu) platform +# macos@TestName - proves the test passed on a macOS platform # net8.0@TestName - proves the test passed under the .NET 8 target framework # net9.0@TestName - proves the test passed under the .NET 9 target framework # net10.0@TestName - proves the test passed under the .NET 10 target framework @@ -311,6 +312,23 @@ sections: - ubuntu@SonarMark_HotSpotsRetrieval - ubuntu@SonarMark_MarkdownReportGeneration + - id: SonarMark-Plt-MacOS + title: The tool shall run on macOS operating systems. + justification: | + macOS is a major development platform for developers using Apple hardware. Supporting macOS + ensures the tool can be used in macOS-based development environments and CI/CD systems, + broadening the tool's reach across all major desktop development platforms. + # Test source pattern "macos@" ensures these tests ran on macOS. + # This filtering is necessary to prove macOS functionality. + tests: + - macos@IntegrationTest_VersionFlag_OutputsVersion + - macos@IntegrationTest_HelpFlag_OutputsUsageInformation + - macos@IntegrationTest_ReportParameter_IsAccepted + - macos@SonarMark_QualityGateRetrieval + - macos@SonarMark_IssuesRetrieval + - macos@SonarMark_HotSpotsRetrieval + - macos@SonarMark_MarkdownReportGeneration + - id: SonarMark-Plt-Net8 title: The tool shall support .NET 8.0 runtime. justification: |