diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 74dbcdd..4c64973 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,6 +1,6 @@ ##################################################### # -# List of approvers for SecObs semantic conventions repository +# List of approvers for Contrast Semantic Conventions repository # ##################################################### # @@ -9,11 +9,6 @@ # # Schemas and schema file tooling -/schemas/ @seschis -/internal/tools/schema_check.sh @seschis - -# Actions semantic conventions approvers -/model/actions/ @seschis -/docs/actions/ @seschis +/ @seschis # TODO - Add semconv area experts and groups diff --git a/.github/workflows/checks.yaml b/.github/workflows/checks.yaml new file mode 100644 index 0000000..533d948 --- /dev/null +++ b/.github/workflows/checks.yaml @@ -0,0 +1,116 @@ +name: Checks + +on: + push: + pull_request: + +jobs: + markdownlint: + runs-on: ubuntu-latest + steps: + - name: check out code + uses: actions/checkout@v2 + + - name: install dependencies + run: npm install + + - name: Check file and folder names + run: make check-file-and-folder-names-in-docs + + - name: run markdownlint + run: npx gulp lint-md + + yamllint: + runs-on: ubuntu-latest + steps: + - name: check out code + uses: actions/checkout@v2 + + - uses: actions/setup-python@v2 + + - name: install yamllint + run: make install-yamllint + + - name: run yamllint + run: yamllint . -f github + + markdown-link-check: + runs-on: ubuntu-latest + steps: + - name: check out code + uses: actions/checkout@v2 + + - name: install dependencies + run: npm install + + - name: run markdown-link-check + run: make markdown-link-check + + markdown-toc-check: + runs-on: ubuntu-latest + steps: + - name: check out code + uses: actions/checkout@v2 + + - name: install dependencies + run: npm install + + - name: run markdown-toc + run: make markdown-toc + + - name: validate markdown-toc + run: git diff --exit-code ':*.md' || (echo 'Generated markdown Table of Contents is out of date, please run "make markdown-toc" and commit the changes in this PR.' && exit 1) + + misspell: + runs-on: ubuntu-latest + steps: + - name: check out code + uses: actions/checkout@v2 + + - name: run misspell + run: make misspell + + semantic-conventions: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v1 + - name: verify semantic convention tables + run: make table-check + + semantic-conventions-registry: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v1 + - name: verify registry tables + run: | + make attribute-registry-generation + git diff --exit-code './docs/attributes-registry/*.md' || (echo 'Attribute registry markdown is out of date, please run "make attribute-registry-generation" and commit the changes in this PR.' && exit 1) + + schemas-check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v1 + - name: verify schemas + run: make schema-check + + policies-check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v1 + - name: verify semantic conventions yaml definitions + run: make check-policies + + polices-test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v1 + - name: verify semantic conventions yaml definitions + run: make test-policies + + # TODO: Remove this once policies-check is the only enforcement on github. + semantic-conventions-compatibility: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v1 + - name: verify semantic convention compatibility with latest released version + run: make compatibility-check \ No newline at end of file diff --git a/README.md b/README.md index a5a08fb..efac704 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,8 @@ -# Security Observability Semantic Conventions +# Contrast Icon Contrast Semantic Conventions + +[![Checks](https://github.com/Contrast-Security-OSS/contrast-semantic-conventions/workflows/Checks/badge.svg?branch=main)](https://github.com/Contrast-Security-OSS/contrast-semantic-conventions/actions?query=workflow%3A%22Checks%22+branch%3Amain) +[![GitHub tag (latest SemVer)](https://img.shields.io/github/tag/open-telemetry/semantic-conventions.svg?logo=opentelemetry&&color=f5a800&label=Latest%20release)](https://github.com/open-telemetry/semantic-conventions/releases/latest) +[![Specification Version](https://img.shields.io/badge/OTel_specification_version-v1.37.0-blue?logo=opentelemetry&color=f5a800)](https://github.com/open-telemetry/opentelemetry-specification/releases/tag/v1.37.0) This repo is built on top of [this otel specification version][SpecificationVersion] @@ -27,16 +31,10 @@ This standard will be used for all signal data sent by Contrast sensors to that proper dimensional correlation/association can be performed on the backend data across all of our products. -## Model Definition Files - -The model definition files have a particular schema associated to them that the -opentelemetry [semconvgen](https://github.com/open-telemetry/build-tools/blob/v0.22.0/semantic-conventions/README.md) -build tool interprets and processes. `semconvgen` is used to generate -documentation data from the definition files. Specific language agents can use -these definition files to generate library code. +## Read the docs -The model definitions use a syntax defined at -[Semantic Convention YAML Language](https://raw.githubusercontent.com/open-telemetry/build-tools/v0.22.0/semantic-conventions/syntax.md) +The human-readable version of the semantic conventions resides in the [docs](docs/README.md) folder. +Major parts of these Markdown documents are generated from the YAML definitions located in the [model](model/README.md) folder. ## Releases @@ -48,10 +46,4 @@ The Contrast Semantic Conventions version will encompass the version of the adde here and the core semantic conventions version which is [v1.22.0](https://github.com/open-telemetry/semantic-conventions/releases/tag/v1.22.0) at the time of this writing. -## Consuming the Semantic Convention Documentation - -The markdown documentation along with any generated table information from -the definition files can be consumed by just pointing a browser to the `docs/` -directory in this repo. - [SpecificationVersion]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0 diff --git a/docs/README.md b/docs/README.md index 370b5bb..c340393 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,4 +1,4 @@ -# Security Observability Semantic Conventions +# Contrast Semantic Conventions The Semantic Conventions define a common set of (semantic) attributes which provide meaning to data when collecting, producing and consuming it.