diff --git a/CHANGELOG.md b/CHANGELOG.md
index 27ab7050c1..1415d835e3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,8 +1,19 @@
-# Change Log
+# CHANGELOG
All notable changes to this project will be documented in this file based on the [Keep a Changelog](http://keepachangelog.com/) Standard. This project adheres to [Semantic Versioning](http://semver.org/).
+## Unreleased
-## [Unreleased](https://github.com/elastic/ecs/compare/0.1.0...master)
+### Breaking changes
+
+### Bugfixes
+
+### Added
+
+### Improvements
+
+### Deprecated
+
+## 1.0.0-beta1
### Breaking changes
* Change structure of URL. #7
@@ -32,8 +43,6 @@ All notable changes to this project will be documented in this file based on the
* Rename `url.hostname` to `url.domain`. #175
* Remove `source.hostname` and `destination.hostname`. #175
-### Bugfixes
-
### Added
* Add `network.total.packets` and `network.total.bytes` field. PR#2
* Add `event.action` field. #21
@@ -54,4 +63,6 @@ All notable changes to this project will be documented in this file based on the
* Remove duplicate definitions of the reuseable `os` field set from `host.os` and
`user_agent.os`. #168
-### Deprecated
+## 0.1.0
+
+Initial draft release
diff --git a/README.md b/README.md
index a70c787db4..549a6331d1 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,7 @@ See CONTRIBUTING.md for more details on setting up.
-->
-**WARNING: THIS IS WORK IN PROGRESS**
+**WARNING: THE MASTER BRANCH IS FOR WORK IN PROGRESS**
# Elastic Common Schema (ECS)
@@ -23,7 +23,18 @@ ECS is still under development and backward compatibility is not guaranteed. Any
feedback on the general structure, missing fields, or existing fields is appreciated.
For contributions please read the [Contributing Guide](CONTRIBUTING.md).
-The current version of ECS is `0.1.0`.
+
+# Versions
+
+The master branch of this repository should never be considered an
+official release of ECS. You can browse official releases of ECS
+[here](https://github.com/elastic/ecs/releases).
+
+Please note that when the README.md file and other generated files
+(like schema.csv and template.json) are not in agreement,
+the README.md should be considered the official spec.
+The other two files are simply provided as a convenience, and may not always be
+fully up to date.
# In this readme
diff --git a/docs/intro.md b/docs/intro.md
index 0f223a868a..40e342cf9e 100644
--- a/docs/intro.md
+++ b/docs/intro.md
@@ -10,7 +10,7 @@ See CONTRIBUTING.md for more details on setting up.
-->
-**WARNING: THIS IS WORK IN PROGRESS**
+**WARNING: THE MASTER BRANCH IS FOR WORK IN PROGRESS**
# Elastic Common Schema (ECS)
@@ -23,7 +23,18 @@ ECS is still under development and backward compatibility is not guaranteed. Any
feedback on the general structure, missing fields, or existing fields is appreciated.
For contributions please read the [Contributing Guide](CONTRIBUTING.md).
-The current version of ECS is `0.1.0`.
+
+# Versions
+
+The master branch of this repository should never be considered an
+official release of ECS. You can browse official releases of ECS
+[here](https://github.com/elastic/ecs/releases).
+
+Please note that when the README.md file and other generated files
+(like schema.csv and template.json) are not in agreement,
+the README.md should be considered the official spec.
+The other two files are simply provided as a convenience, and may not always be
+fully up to date.
# In this readme