[editorial] Setup Prettier and run it on some files (#192)

Co-authored-by: Armin Ruech <armin.ruech@dynatrace.com>

.markdown_link_check_config.json

@@ -15,8 +15,5 @@
     }
   ],
   "retryOn429": true,
-  "aliveStatusCodes": [
-    200,
-    403
-  ]
+  "aliveStatusCodes": [200, 403]
 }

.prettierignore

@@ -0,0 +1,8 @@
+/.github
+
+# for the first iteration, we only reformat /docs/cloud* and will add the rest in individual PRs
+/docs/**
+!/docs/cloud*
+!/docs/cloud*/**
+/model
+/schemas

CHANGELOG.md

@@ -349,7 +349,7 @@ This and earlier versions were released as part of [the Specification](https://g
   ([#2508](https://github.com/open-telemetry/opentelemetry-specification/pull/2508)).
 - Refactor jvm classes semantic conventions
   ([#2550](https://github.com/open-telemetry/opentelemetry-specification/pull/2550)).
-- Add browser.* attributes
+- Add browser.\* attributes
   ([#2353](https://github.com/open-telemetry/opentelemetry-specification/pull/2353)).
 - Change JVM runtime metric `process.runtime.jvm.memory.max`
   to `process.runtime.jvm.memory.limit`

CONTRIBUTING.md

@@ -49,6 +49,7 @@ See:
 - [MarkdownStyle](#markdown-style)
 - [Misspell Check](#misspell-check)
 - Markdown link checking (docs TODO)
+- Prettier formatting
 
 ### YAML to Markdown
 

Makefile

@@ -102,14 +102,22 @@ table-check:
 schema-check:
 	$(TOOLS_DIR)/schema_check.sh
 
+.PHONY: check-format
+check-format:
+	npm run check:format
+
+.PHONY: fix-format
+fix-format:
+	npm run fix:format
+
 # Run all checks in order of speed / likely failure.
 .PHONY: check
-check: misspell markdownlint markdown-link-check
+check: misspell markdownlint markdown-link-check check-format
 	@echo "All checks complete"
 
 # Attempt to fix issues / regenerate tables.
 .PHONY: fix
-fix: table-generation misspell-correction
+fix: table-generation misspell-correction fix-format
 	@echo "All autofixes complete"
 
 .PHONY: install-tools

README.md

@@ -25,7 +25,7 @@ Approvers ([@open-telemetry/specs-semconv-approvers](https://github.com/orgs/ope
 - [Sean Marciniak](https://github.com/MovieStoreGuy), Atlassian
 - [Ted Young](https://github.com/tedsuo), Lightstep
 
-*Find more about the approver role in [community repository](https://github.com/open-telemetry/community/blob/master/community-membership.md#approver).*
+_Find more about the approver role in [community repository](https://github.com/open-telemetry/community/blob/master/community-membership.md#approver)._
 
 Maintainers ([@open-telemetry/specs-semconv-maintainers](https://github.com/orgs/open-telemetry/teams/specs-semconv-maintainers)):
 
@@ -33,6 +33,6 @@ Maintainers ([@open-telemetry/specs-semconv-maintainers](https://github.com/orgs
 - [Armin Ruech](https://github.com/arminru)
 - [Reiley Yang](https://github.com/reyang)
 
-*Find more about the maintainer role in [community repository](https://github.com/open-telemetry/community/blob/master/community-membership.md#maintainer).*
+_Find more about the maintainer role in [community repository](https://github.com/open-telemetry/community/blob/master/community-membership.md#maintainer)._
 
 [SpecificationVersion]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0

docs/cloud-providers/README.md

@@ -13,6 +13,6 @@ This document defines semantic conventions for cloud provider SDK spans, metrics
 
 Semantic conventions exist for the following cloud provider SDKs:
 
-* [AWS SDK](aws-sdk.md): Semantic Conventions for the *AWS SDK*.
+- [AWS SDK](aws-sdk.md): Semantic Conventions for the _AWS SDK_.
 
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md

docs/cloud-providers/aws-sdk.md

@@ -23,6 +23,7 @@ The span name MUST be of the format `Service.Operation` as per the AWS HTTP API,
 `S3.ListBuckets`. This is equivalent to concatenating `rpc.service` and `rpc.method` with `.` and consistent
 with the naming guidelines for RPC client spans.
 
+<!-- prettier-ignore-start -->
 <!-- semconv aws -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
@@ -35,12 +36,13 @@ with the naming guidelines for RPC client spans.
 
 **[2]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
 <!-- endsemconv -->
+<!-- prettier-ignore-end -->
 
 ## AWS service specific attributes
 
 The following Semantic Conventions extend the general AWS SDK attributes for specific AWS services:
 
-* [AWS DynamoDB](/docs/database/dynamodb.md): Semantic Conventions for *AWS DynamoDB*.
-* [AWS S3](/docs/object-stores/s3.md): Semantic Conventions for *AWS S3*.
+- [AWS DynamoDB](/docs/database/dynamodb.md): Semantic Conventions for _AWS DynamoDB_.
+- [AWS S3](/docs/object-stores/s3.md): Semantic Conventions for _AWS S3_.
 
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md

docs/cloudevents/README.md

@@ -13,6 +13,6 @@ This document defines semantic conventions for the [CloudEvents specification](h
 
 Semantic conventions for CloudEvents are defined for the following signals:
 
-* [CloudEvents Spans](cloudevents-spans.md): Semantic Conventions for modeling CloudEvents as *spans*.
+- [CloudEvents Spans](cloudevents-spans.md): Semantic Conventions for modeling CloudEvents as _spans_.
 
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md

docs/cloudevents/cloudevents-spans.md

@@ -6,7 +6,7 @@ linkTitle: CloudEvents Spans
 
 **Status**: [Experimental][DocumentStatus]
 
-<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->
+<!-- prettier-ignore-start -->
 
 <!-- toc -->
 
@@ -20,14 +20,15 @@ linkTitle: CloudEvents Spans
 
 <!-- tocstop -->
 
+<!-- prettier-ignore-end -->
+
 ## Definitions
 
 From the
 [CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#overview):
 
 > CloudEvents is a specification for describing event data in common formats
-to provide interoperability across services, platforms and systems.
->
+> to provide interoperability across services, platforms and systems.
 
 For more information on the concepts, terminology and background of CloudEvents
 consult the
@@ -39,7 +40,7 @@ document.
 A CloudEvent can be sent directly from producer to consumer.
 For such a scenario, the traditional parent-child trace model works well.
 However, CloudEvents are also used in distributed systems where an event
-can go through many [hops](https://en.wikipedia.org/wiki/Hop_(networking))
+can go through many [hops](<https://en.wikipedia.org/wiki/Hop_(networking)>)
 until it reaches a consumer. In this scenario, the traditional parent-child
 trace model is not sufficient to produce a meaningful trace.
 
@@ -197,6 +198,7 @@ in the [table below](#attributes).
 
 The following attributes are applicable to creation and processing Spans.
 
+<!-- prettier-ignore-start -->
 <!-- semconv cloudevents -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
@@ -206,5 +208,6 @@ The following attributes are applicable to creation and processing Spans.
 | `cloudevents.event_type` | string | The [event_type](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#type) contains a value describing the type of event related to the originating occurrence. | `com.github.pull_request.opened`; `com.example.object.deleted.v2` | Recommended |
 | `cloudevents.event_subject` | string | The [subject](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#subject) of the event in the context of the event producer (identified by source). | `mynewfile.jpg` | Recommended |
 <!-- endsemconv -->
+<!-- prettier-ignore-end -->
 
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md

package.json

@@ -1,4 +1,13 @@
 {
+  "scripts": {
+    "_check:format": "npx prettier --check .",
+    "_check:format:any": "npx prettier --check --ignore-path ''",
+    "check": "make check",
+    "check:format": "npm run _check:format || (echo '[help] Run: npm run format'; exit 1)",
+    "fix": "make fix",
+    "fix:format": "npm run _check:format -- --write",
+    "test": "npm run check"
+  },
   "devDependencies": {
     "gulp": "^4.0.2",
     "js-yaml": "^4.1.0",

supplementary-guidelines/compatibility/aws.md

@@ -33,7 +33,7 @@ the  `MD5OfMessageAttributes` that it receives).
 
 The following formats are currently natively supported by AWS services for propagation:
 
-* [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html)
+- [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html)
 
 AWS service-supported context propagation is necessary to allow context propagation
 through AWS managed services, for example: `S3 -> SNS -> SQS -> Lambda`.