Add runtime field flag in documentation files

[mrodm]

Closes #1229

Description

This PR updates the generation of fields documentation to include the runtime flag in the corresponding field definitions.

Example of the docs if runtime flag is added in the same column as the type:

| day_of_week | Day of week. | keyword(runtime) |  |  |
| labels.\* |  | keyword(runtime) |  |  |
| package_registry.day_of_week | Other day of week. | keyword(runtime) |  |  |
| package_registry.day_of_week2 | Day of week 2. | keyword(runtime) |  |  |
| package_registry.labels.version | Elastic Package Registry version. | keyword(runtime) |  |  |

How to test this PR locally

Go to a package and add some runtime field definitions:

- name: labels.*
  type: keyword
  runtime: true
- name: labels.a
  description: "My label a"
  type: text

- name: package_registry.day_of_week
  description: "Other day of week."
  type: keyword
  runtime: "emit(doc['@timestamp'].value.dayOfWeekEnum.getDisplayName(TextStyle.FULL, Locale.ENGLISH))"

- name: package_registry
  type: group
  fields:
    - name: day_of_week2
      description: Day of week 2.
      type: keyword
      runtime: "emit(doc['@timestamp'].value.dayOfWeekEnum.getDisplayName(TextStyle.FULL, Locale.ENGLISH))"

- name: day_of_week
  type: keyword
  description: Day of week.
  runtime: "emit(doc['@timestamp'].value.dayOfWeekEnum.getDisplayName(TextStyle.FULL, Locale.ENGLISH))"

Build your package with elastic-package and check the README docs built:

cd /path/to/package

elastic-package build -v

# check changes in doc files

[mrodm]

I didn't find any usages of this Update function in the elastic-package code base.

It looks like that it was removed in this PR #1335:
https://github.com/elastic/elastic-package/pull/1335/files#diff-77cc155ee037ac620b1e188302f60fdf736637a25e5021e76dbad83594edd09cL133

[jsoriano]

Interesting, this used to be neccesary 🤔 But good if we don't need it anymore.

[mrodm]

At least, that function is not called anymore...

[mrodm]

/test

[mrodm]

/test

[mrodm]

/test

[mrodm]

Removed test (file) related to the Update function.

[mrodm]

In this PR, it is implemented that the runtime flag is added next to the type of the field:

| day_of_week | Day of week. | keyword (runtime) |  |  |
| labels.\* |  | keyword (runtime) |  |  |
| package_registry.day_of_week | Other day of week. | keyword (runtime) |  |  |
| package_registry.day_of_week2 | Day of week 2. | keyword (runtime) |  |  |
| package_registry.labels.version | Elastic Package Registry version. | keyword (runtime) |  |  |

Another option would be to set the runtime flag in the first column (field name). It could be like this:

| day_of_week (runtime) | Day of week. | keyword |  |  |
| labels.\* (runtime) |  | keyword|  |  |
| package_registry.day_of_week (runtime) | Other day of week. | keyword |  |  |
| package_registry.day_of_week2 (runtime) | Day of week 2. | keyword |  |  |
| package_registry.labels.version (runtime) | Elastic Package Registry version. | keyword |  |  |

Which of the two ways do you think shows better the runtime fields to the user?

[jsoriano]

Which of the two ways do you think shows better the runtime fields to the user?

I think it would be better in the type? 🤔 But not a strong opinion, as you prefer.

[jsoriano]

Looks good, but can this break current integrations builds? Or there is no package using runtime?

[jsoriano]

Interesting, this used to be neccesary 🤔 But good if we don't need it anymore.

[mrodm]

Looks good, but can this break current integrations builds? Or there is no package using runtime?

Currently, there are no packages using runtime fields in the integrations repository:

 $ git grep "runtime:"  |grep "yml:" |grep "fields/"
 $

EDIT:

• Just to be sure, triggered a new integrations PR to test all packages: Test elastic-package#2415 - DO NOT MERGE integrations#12824

[elasticmachine]

💚 Build Succeeded

• Buildkite Build
• Commit: c537098

History

• 💚 Build #4855 succeeded 8f9fe13
• 💚 Build #4854 succeeded 7a9ae0e
• 💚 Build #4853 succeeded 7a9ae0e
• 💚 Build #4852 succeeded 7a9ae0e
• 💔 Build #4851 failed 7a9ae0e
• 💚 Build #4846 succeeded 52ab78c

cc @mrodm

[mrodm]

test integrations

[elastic-vault-github-plugin-prod]

Created or updated PR in integrations repository to test this version. Check elastic/integrations#12824

[mrodm]

• Just to be sure, triggered a new integrations PR to test all packages: Test elastic-package#2415 - DO NOT MERGE integrations#12824

Packages failing in that PR are the expected ones related to validation based on mappings:
https://buildkite.com/elastic/integrations/builds/22461