Point README to the new official docs and other contributor-centric d…

…oc (elastic#400) * readme no longer contains the field definitions * readme now directs people to the main website, for the official ECS documentation * Introduce `make legacy_use_cases` to generate the use cases (they were previously generated at the same time as the readme) * Document generated files a bit * contributing guidelines now point people to a page in the docs, to reduce content duplication * renamed the two intermediary in memory representations to match the variable names used in the code
kgeller · Mar 26, 2019 · fa81fa6 · fa81fa6
1 parent 0a30233
commit fa81fa6
Show file tree

Hide file tree

Showing 13 changed files with 53 additions and 1,121 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -52,7 +52,9 @@ You can contribute even if you are not an experienced Git user. You'll need a gi
 
 The `fields.yml` files describe the Elastic Common Schema in a structured way. We can use these files to generate an Elasticsearch index template, a Kibana index pattern, or documentation output.
 
-The file structure is similar to this:
+The file structure is documented in [schemas/README.md](schemas).
+
+It looks similar to this:
 
 ```
 - name: agent
@@ -86,29 +88,4 @@ The `type` is the [Elasticsearch field type](https://www.elastic.co/guide/en/ela
 
 ## Guidelines for implementing ECS
 
-* The document MUST have the `@timestamp` field.
-* The [data type](https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-types.html)
-  defined for an ECS field MUST be used.
-* It SHOULD have the field `ecs.version` to define which version of ECS it uses.
-* As many fields as possible should be mapped to ECS.
-
-### Writing fields
-
-* All fields must be lower case
-* Combine words using underscore
-* No special characters except `_`
-
-### Naming fields
-
-* *Present tense.* Use present tense unless field describes historical information.
-* *Singular or plural.* Use singular and plural names properly to reflect the field content. For example, use `requests_per_sec` rather than `request_per_sec`.
-* *General to specific.* Organise the prefixes from general to specific to allow grouping fields into objects with a prefix like `host.*`.
-* *Avoid repetition.* Avoid stuttering of words. If part of the field name is already in the prefix, do not repeat it. Example: `host.host_ip` should be `host.ip`.
-* *Use prefixes.* Fields must be prefixed except for the base fields. For example all `host` fields are prefixed with `host.`. See `dot` notation in FAQ for more details.
-* Do not use abbreviations. (A few exceptions such as `ip`, `os` ,`geo`, exist.)
-
-### Implementation details
-
-* Host can contain hostname and port (hostname:port)
-* Hostname never contains a port number
-
+Look at our [Guidelines and Best Practices](https://www.elastic.co/guide/en/ecs/current/ecs-guidelines.html) on the ECS documentation website.
diff --git a/Makefile b/Makefile
@@ -56,7 +56,7 @@ fmt: ve
 
 # Alias to generate everything.
 .PHONY: generate
-generate: readme template codegen generator
+generate: template legacy_use_cases codegen generator
 
 # Run the new generator
 .PHONY: generator
@@ -73,6 +73,11 @@ gocodegen:
 	        -schema=../schemas \
 	        -out=../code/go/ecs
 
+# Generate the Use Cases
+.PHONY: legacy_use_cases
+legacy_use_cases:
+	$(PYTHON) scripts/use-cases.py --stdout=true >> /dev/null
+
 # Check Makefile format.
 .PHONY: makelint
 makelint: SHELL:=/bin/bash
@@ -86,17 +91,6 @@ misspell:
 	go get github.com/client9/misspell/cmd/misspell
 	misspell README.md CONTRIBUTING.md
 
-# Build README.md by concatenating various markdown snippets.
-.PHONY: readme
-readme:
-	cat docs/intro.md > README.md
-	$(PYTHON) scripts/schemas.py --stdout=true >> README.md
-	cat docs/use-cases-header.md >> README.md
-	$(PYTHON) scripts/use-cases.py --stdout=true >> README.md
-	cat docs/implementing.md >> README.md
-	cat docs/about.md >> README.md
-	cat docs/generated-files.md >> README.md
-
 .PHONY: reload_docs
 reload_docs: generator docs
 

diff --git a/README.md b/README.md
diff --git a/docs/about.md b/docs/about.md
diff --git a/docs/generated-files.md b/docs/generated-files.md
diff --git a/docs/implementing.md b/docs/implementing.md
diff --git a/docs/intro.md b/docs/intro.md
diff --git a/docs/use-cases-header.md b/docs/use-cases-header.md
diff --git a/generated/README.md b/generated/README.md
@@ -0,0 +1,25 @@
+# Artifacts generated from ECS
+
+Various kinds of files or programs can be generated directly based on ECS.
+
+In this directory, you'll find the following:
+
+* `beats/fields.ecs.yml`: The YAML field definition file used by Beats to import ECS in it's broader
+  field schema.
+
+* `csv/fields.csv`: A csv file you can use to import ECS field definitions
+in a spreadsheet.
+
+* `ecs/*.yml`: Two files that are the fully fleshed out representation of ECS.
+  All the default values are filled in, basic checks have been made to ensure
+  correctness or consistency, etc.
+  Generators literally operate on one of these two representations, depending on
+  whether they depend on the variables `ecs_flat` or `ecs_nested`.
+
+* `elasticsearch/{6,7}/template.json`: Sample Elasticsearch templates to get
+  started using ECS. Check out how to use them in
+  [generated/elasticsearch/README.md](elasticsearch).
+
+If you'd like to share your own generator with the ECS community, you're welcome
+to look at our [contribution guidelines](/CONTRIBUTING.md), and then at the
+generators in `scripts/generators`.
diff --git a/generated/ecs/fields_flat.yml → generated/ecs/ecs_flat.yml b/generated/ecs/fields_flat.yml → generated/ecs/ecs_flat.yml
diff --git a/generated/ecs/fields_nested.yml → generated/ecs/ecs_nested.yml b/generated/ecs/fields_nested.yml → generated/ecs/ecs_nested.yml
diff --git a/schemas/format.md → schemas/README.md b/schemas/format.md → schemas/README.md