Make it possible to automatically list all specification requirements

[ocelotl]

This is the original content of this issue:

What are you trying to achieve?
I am trying to quickly make a list of specification requirements in order to check the specification compliance of a particular implementation.

What did you expect to see?
I was expecting to easily find all the requirements that make up the specification.

Additional context.
I have been reading some parts of the specification and found that the usage of RFC 2119 keywords is sometimes inconsistent, some hard requirements are not specified with MUST, some optional requirements are not specified with SHOULD/MAY. Instead, some requirements are written using other terms that have the same meaning but not the exact syntax of RFC 2119. This makes it impossible to simply search for these keywords in the specification in order to find all the precise requirements that make up the document.

@jmacd requested an issue to be filed. I prefer to reuse this one to minimize the amount of issues 👍

Motivation for this change

The spec is hard to understand because it is written in an inconsistently-applied formal language. Here are some examples:

• This is a "Recommendations" section where MUST and SHOULD appear both
• This section states that a name SHOULD SHOULD NOT coincide with namespaces
• This section uses the terms "this is required for..." instead of using MUST
• This section includes conditional requirements. It is hard to find which requirements an implementation has to fulfill if it requires finding any conditions in the specification first
• This section uses may in lower case

When implementing OpenTelemetry it is very hard to know what has to be implemented because there is no clear listing of all requirements. If the specifcation is written in the way intended in this PR it will be possible to generate automatically a list of every requirement and condition that the specification states.

It is also much easier to check that the specification is correct if we only need to check a list of well defined sections. Some checks (like having a RFC 2119 keyword, for example) can even be automated.

It is also easier to communicate between OpenTelemetry participants if the requirements are clearly identifiable, this approach uses markdown headings so that each requirement will have its own URL so that they can be used as reference in Slack, email, etc.

Steps

Fixing this issue will require a big change, because it means reformatting every document that has been written to this moment, so it would be convenient to separate this into smaller steps:

• Merge the specification-writing guidelines
• Update the specification document status states to manage the transition
• Merge the scripts that generate the JSON files from the specification markdown files
• Reformat common/attribute-naming.md
• Reformat common/common.md
• Reformat sdk-configuration.md
• Reformat context/api-propagators.md
• Reformat context/context.md
• Reformat overview.md
• Reformat protocol/exporter.md
• Reformat protocol/otlp.md
• Reformat protocol/design-goals.md
• Reformat protocol/requirements.md
• Reformat performance-benchmark.md
• Reformat vendors.md
• Reformat logs/overview.md
• Reformat logs/data-model.md
• Reformat sdk-environment-variables.md
• Reformat compatibility/openmetrics.md
• Reformat compatibility/opentracing.md
• Reformat compatibility/opencensus.md
• Reformat resource/sdk.md
• Reformat resource/semantic_conventions/device.md
• Reformat resource/semantic_conventions/cloud_provider/aws/logs.md
• Reformat resource/semantic_conventions/cloud_provider/aws/README.md
• Reformat resource/semantic_conventions/cloud_provider/aws/eks.md
• Reformat resource/semantic_conventions/cloud_provider/aws/ecs.md
• Reformat resource/semantic_conventions/webengine.md
• Reformat resource/semantic_conventions/os.md
• Reformat resource/semantic_conventions/README.md
• Reformat resource/semantic_conventions/deployment_environment.md
• Reformat resource/semantic_conventions/k8s.md
• Reformat resource/semantic_conventions/host.md
• Reformat resource/semantic_conventions/process.md
• Reformat resource/semantic_conventions/faas.md
• Reformat resource/semantic_conventions/container.md
• Reformat resource/semantic_conventions/cloud.md
• Reformat versioning-and-stability.md
• Reformat baggage/api.md
• Reformat performance.md
• Reformat library-guidelines.md
• Reformat metrics/supplementary-guidelines.md
• Reformat metrics/sdk.md
• Reformat metrics/api.md
• Reformat metrics/README.md
• Reformat metrics/datamodel.md
• Reformat metrics/sdk_exporters/in-memory.md
• Reformat metrics/sdk_exporters/prometheus.md
• Reformat metrics/sdk_exporters/stdout.md
• Reformat metrics/sdk_exporters/otlp.md
• Reformat metrics/semantic_conventions/runtime-environment-metrics.md
• Reformat metrics/semantic_conventions/system-metrics.md
• Reformat metrics/semantic_conventions/rpc.md
• Reformat metrics/semantic_conventions/openmetrics-guidelines.md
• Reformat metrics/semantic_conventions/faas-metrics.md
• Reformat metrics/semantic_conventions/README.md
• Reformat metrics/semantic_conventions/http-metrics.md
• Reformat metrics/semantic_conventions/process-metrics.md
• Reformat library-layout.md
• Reformat trace/sdk.md
• Reformat trace/api.md
• Reformat trace/sdk_exporters/zipkin.md
• Reformat trace/sdk_exporters/jaeger.md
• Reformat trace/sdk_exporters/non-otlp.md
• Reformat trace/semantic_conventions/instrumentation/aws-sdk.md
• Reformat trace/semantic_conventions/instrumentation/aws-lambda.md
• Reformat trace/semantic_conventions/http.md
• Reformat trace/semantic_conventions/database.md
• Reformat trace/semantic_conventions/rpc.md
• Reformat trace/semantic_conventions/exceptions.md
• Reformat trace/semantic_conventions/messaging.md
• Reformat trace/semantic_conventions/README.md
• Reformat trace/semantic_conventions/faas.md
• Reformat trace/semantic_conventions/span-general.md
• Reformat error-handling.md