Merge branch 'main' into feat/database-metrics-yaml

CONTRIBUTING.md

@@ -11,10 +11,51 @@ requirements and recommendations.
 Before you can contribute, you will need to sign the [Contributor License
 Agreement](https://identity.linuxfoundation.org/projects/cncf).
 
-## TODO
+## How to Contribute
+
+When contributing to semantic conventions, it's important to understand a few
+key, but non-obvious, aspects:
+
+- All attributes, metrics, etc. are formally defined in YAML files under
+  the `model/` directory.
+- All descriptions, normative language are defined in the `docs/`
+  directory.
+  - We provide tooling to generate Markdown documentation from the formal
+    YAML definitons.  See [Yaml to Markdown](#yaml-to-markdown).
+  - We use Hugo to render [semantic conventions on our website](https://opentelemetry.io/docs/specs/semconv/).
+    You will see `<!--- Hugo front matter used to generate ...` sections
+    in markdown.  See [Hugo frontmatter](#hugo-frontmatter) for details.
+- All changes to existing attributes, metrics, etc. MUST be allowed as
+  per our [stability guarantees](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/versioning-and-stability.md#semantic-conventions-stability) and
+  defined in a schema file.  As part of any contribution, you should
+  include attribute changes defined in the `schema-next.yaml` file.
+  For details, please read [the schema specification](https://opentelemetry.io/docs/specs/otel/schemas/).
+- After creating a pull request, please update the [CHANGELOG](CHANGELOG.md) file with
+  a description of your changes.
+
+Please make sure all Pull Requests are compliant with these rules!
+
+### Hugo frontmatter
+
+At the top of all Markdown files under the `docs/` directory, you will see
+headers like the following:
 
-We need to flesh out the rest of the contributing document for specifics on
-semantic conventions.
+```
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: HTTP
+path_base_for_github_subdir:
+  from: content/en/docs/specs/semconv/http/_index.md
+  to: http/README.md
+--->
+```
+
+When creating new pages, you should provide the `linkTitle` attribute. This is used
+to generate the navigation bar on the website, and will be listed relative to the
+"parent" document.
+
+## Automation
+
+Semantic Conventions provides a set of automated tools for general development.
 
 ### Consistency Checks
 

internal/tools/schema_check.sh

@@ -11,36 +11,58 @@ BUILD_TOOL_SCHEMAS_VERSION=0.18.0
 # List of versions that do not require or have a schema.
 declare -a skip_versions=("1.0.0" "1.0.1" "1.1.0" "1.2.0" "1.3.0" "1.6.0")
 
-root_dir=$PWD
-schemas_dir=$root_dir/schemas
-
-# Find all version sections in CHANGELOG that start with a number in 1..9 range.
-grep -o -e '## v[1-9].*\s' $root_dir/CHANGELOG.md | grep -o '[1-9].*' | while read ver; do
-  if [[ " ${skip_versions[*]} " == *" $ver "* ]]; then
-    # Skip this version, it does not need a schema file.
-    continue
+# Verifies remote avilability of a schema file.
+# 
+# If the schema file is available for download, THEN we make sure it is exactly
+# what is in the repository.  If the file is not available for download,
+# we pass this check.  This is to allow releases to be checked in, where
+# a new version is specified but hasn't propagated to the website yet.
+#
+# Args:
+# 1 - version number
+verify_remote_availability() {
+  local ver="$1"
+  echo -n "Ensure published schema file https://opentelemetry.io/schemas/$ver matches local copy... "
+  if curl --fail --no-progress-meter https://opentelemetry.io/schemas/$ver > verify$ver 2>/dev/null; then
+    diff verify$ver $file && echo "OK, matches" \
+      || (echo "Incorrect!" && exit 3)
+  else
+    echo "Not found"
   fi
+  rm verify$ver
+}
 
+# Verifies remote avilability of a schema file in the current repository.
+#
+# Args:
+# 1 - version number
+verify_local_availability() {
+  local ver="$1"
+
   file="$schemas_dir/$ver"
   echo -n "Ensure schema file $file exists... "
-
+  
   # Check that the schema for the version exists.
   if [ -f "$file" ]; then
     echo "OK, exists."
   else
     echo "FAILED: $file does not exist. The schema file must exist because the version is declared in CHANGELOG.md."
     exit 3
   fi
+}
+
+root_dir=$PWD
+schemas_dir=$root_dir/schemas
+
+# Find all version sections in CHANGELOG that start with a number in 1..9 range.
+grep -o -e '## v[1-9].*\s' $root_dir/CHANGELOG.md | grep -o '[1-9].*' | while read ver; do
+  if [[ " ${skip_versions[*]} " == *" $ver "* ]]; then
+    # Skip this version, it does not need a schema file.
+    continue
+  fi
 
-  # Schema file will no be served directly from this repository when linked
-  # into opentelemetry.io.  We disable this for now and need to move the check
-  # into the website.
-  # curl --no-progress-meter https://opentelemetry.io/schemas/$ver > verify$ver
-  #
-  # diff verify$ver $file && echo "Published schema at https://opentelemetry.io/schemas/$ver is correct" \
-  #   || (echo "Published schema at https://opentelemetry.io/schemas/$ver is incorrect!" && exit 3)
-  #
-  # rm verify$ver
+  verify_local_availability "$ver"
+  verify_remote_availability "$ver"
 done
 
 # Now check the content of all schema files in the ../shemas directory.