updated list of changes and migration tips

Signed-off-by: Don Bourne <dbourne@ca.ibm.com>

spec/src/main/asciidoc/appendix.adoc

@@ -127,6 +127,40 @@ public class MetricRegistryFactory {
 
 === Migration hints
 
+[[migration-hint-to-50]]
+==== To version 5.0
+
+===== SimpleTimer / @SimplyTimed
+
+The `SimpleTimer` class and `@SimplyTimed` annotation have been removed.  This change was made to make it possible to implement the spec using commonly used metrics libraries that lack a similar metric type.
+
+Use `Timer` class or `@Timer` annotation instead.  Alternatively, you can create your own `Gauge` to track the total time and your own `Counter` to track the total number of hits of something you want to time.
+
+===== ConcurrentGauge / @ConcurrentGauge
+
+The `ConcurrentGauge` class and `@ConcurrentGauge` annotation have been removed.  This change was made to make it possible to implement the spec using commonly used metrics libraries that lack a similar metric type.
+
+Use `Gauge` class or `@Gauge` annotation instead. A `Gauge` allows you to track a value that may go up or down over time. If you need to track the recent maximum or minimum with precision (as was handled by a `ConcurrentGauge`), create a separate `Gauge` for each of those statistics, in addition to the `Gauge` to track the current value of what you are observing.
+
+===== Meter / @Metered
+
+The `Meter` class and `@Metered` annotation have been removed.  This change was made to make it possible to implement the spec using commonly used metrics libraries that lack a similar metric type.
+
+Use `Counter` class or `@Counted` annotation instead. Tools, such as Prometheus, are able to compute the rate of increase of an observed metric over a specified period of time.
+
+===== Snapshot
+
+The `Snapshot` class has been modified to avoid restricting the list of percentiles to a fixed set of percentile values. This change was made in anticipation of making the list of percentiles be configurable in the future. As in prior releases, the `Timer` and `Histogram` classes still track the 50th, 75th, 95th, 98th, 99th, and 99.9th percentiles in the corresponding `Snapshot`.
+
+Use `snapshot.percentileValues()` method, then iterate over the returned array of `PercentileValue` objects to find the value at the specific percentile you're interested in.
+
+===== Metric names
+
+The `base_`, `vendor_` and `application_` prefixes for metric names that were used in prior releases have been replaced by a tag named `mp_scope` with value `base`, `vendor`, or `application` (you can also register metrics with custom scopes).
+
+When using the Prometheus format output from the `/metrics` endpoint, use `metric_name{mp_scope="scopeValue",...}` instead of `scopeValue_metric_name{...}` where `metric_name` is the Prometheus-formatted name of your metric and `scopeValue` is one of `base`, `vendor`, `application` or a custom value.
+
+
 [[migration-hint-to-20]]
 ==== To version 2.0
 

spec/src/main/asciidoc/changelog.adoc

@@ -25,14 +25,30 @@
 [[release_notes_5_0]]
 == Changes in 5.0
 
+=== Incompatible Changes
+** This release aligns with Jakarta EE 10, so it won’t work with earlier versions of Jakarta or Java EE
+
 === Breaking changes
+* Removed SimpleTimer class and SimplyTimed annotation
+* Removed ConcurrentGauge class and ConcurrentGauge annotation
+* Removed Meter class and Metered annotation
+* Removed Metered interface
 
-=== API/SPI Changes
 * Updated Timer class
 ** Removed `getFifteenMinuteRate()` method
 ** Removed `getFiveMinuteRate()` method
-** Removed `getMeanMinuteRate()` method
+** Removed `getMeanRate()` method
+** Removed `getOneMinuteRate()` method
+** Removed `getMean()` method
+** Removed `getStdDev()` method
+
+* Updated Histogram class
+** Removed `getFifteenMinuteRate()` method
+** Removed `getFiveMinuteRate()` method
+** Removed `getMeanRate()` method
 ** Removed `getOneMinuteRate()` method
+** Removed `getMean()` method
+** Removed `getStdDev()` method
 
 * Updated MetricRegistry class
 ** Removed `register(String name, T metric)` method
@@ -63,10 +79,70 @@
 ** Removed `getSimpleTimers()` method
 ** Removed `getSimpleTimers(MetricFilter filter)` method
 
+* Updated DefaultMetadata class
+** Removed displayName from constructor
+** Removed `getDisplayname()` method
+** Removed `displayName()` method
+
+* Updated Metadata class
+** Removed `getDisplayname()` method
+** Removed `displayName()` method
+
+* Updated MetadataBuilder class
+** Removed `withDisplayName(String displayName)` method
+
+* Updated Snapshot class
+** Removed `getValue(double quantile)` method
+** Removed `getValues()` method
+** Removed `get75thPercentile()` method
+** Removed `get95thPercentile()` method
+** Removed `get98thPercentile()` method
+** Removed `get999thPercentile()` method
+** Removed `get99thPercentile()` method
+** Removed `getMedian()` method
+** Removed `getMin()` method
+** Removed `getStdDev()` method
+** Modified `size()` method to return long
+** Modified `getMax()` method to return double
+
+* Updated Gauge class
+** can now only work with types that extend Number
+
 * Updated MetricType class
-** Removed `CONCURRENT_GAUGE("concurrent gauge", ConcurrentGauge.class)` enum
-** Removed `METERED("meter", Meter.class)` enum
-** Removed `SIMPLE_TIMER("simple timer", SimpleTimer.class)` enum
+** Removed `CONCURRENT_GAUGE` enum
+** Removed `METERED` enum
+** Removed `SIMPLE_TIMER` enum
+
+=== API/SPI Changes
+* Updated Snapshot class
+** Added `percentileValues()` method
+
+=== Functional Changes
+
+* Added concept of custom scopes for metrics (https://github.com/eclipse/microprofile-metrics/issues/677[677])
+** added tagging of all metrics with mp_scope=value
+** changed /metrics/base to /metrics?scope=base (https://github.com/eclipse/microprofile-metrics/issues/692[692])
+** changed /metrics/vendor to /metrics?scope=vendor (https://github.com/eclipse/microprofile-metrics/issues/692[692])
+** changed /metrics/application to /metrics?scope=application (https://github.com/eclipse/microprofile-metrics/issues/692[692])
+** added /metrics?scope=myScope for custom scoped metrics (https://github.com/eclipse/microprofile-metrics/issues/677[677])
+** added ability for applications to add metrics to a custom scope (https://github.com/eclipse/microprofile-metrics/issues/677[677])
+** added ability to use custom scope names with @RegistryScope annotation (https://github.com/eclipse/microprofile-metrics/issues/677[677])
+** replaced @RegistryType with @RegistryScope (https://github.com/eclipse/microprofile-metrics/issues/677[677])
+
+* Other changes
+** removed requirement to convert metrics to base units for Prometheus output
+** changed from prepending scope to the metric name to putting the scope in mp_scope tag
+** clarified that implementations of /metrics endpoint must support Prometheus text-based exposition format, and may also support OpenMetrics exposition format. (https://github.com/eclipse/microprofile-metrics/issues/678[678])
+** removed JSON format for /metrics output (https://github.com/eclipse/microprofile-metrics/issues/685[685])
+** added restriction to block apps from adding metric IDs with the reserved mp_scope and mp_app tag names (https://github.com/eclipse/microprofile-metrics/issues/700[700])
+** changed _app tag name to mp_app (https://github.com/eclipse/microprofile-metrics/issues/705[705])
+** added mp_scope tag to indicate metric scope
+** added configuration recommendations for vendors implementing the API with Micrometer libraries
+** added rule that metrics of the same name must all contain the same label set (https://github.com/eclipse/microprofile-metrics/issues/721[721])
+** changed REST.request metric from SimpleTimer to Timer type
+** changed the base metrics to be optional (https://github.com/eclipse/microprofile-metrics/issues/680[680])
+
+
 
 [[release_notes_4_0]]
 == Changes in 4.0

spec/src/main/asciidoc/microprofile-metrics-spec.asciidoc

@@ -23,8 +23,7 @@
 :doctype: book
 :license: Apache License v2.0
 :source-highlighter: coderay
-:authors: Heiko W. Rupp, Raymond Lam, David Chan, Don Bourne, Antonin Stefanutti, Brennan Nichyporuk, Mike Croft, Werner Keil, Jan Martiska
-:email: hrupp@redhat.com, lamr@ca.ibm.com, chdavid@ca.ibm.com, dbourne@ca.ibm.com, antonin@stefanutti.fr, brennan.nichyporuk@gmail.com, mike.croft@payara.fish, werner@catmedia.us, jmartisk@redhat.com
+:author: The MicroProfile community and its contributors
 :doctype: book
 ifdef::backend-pdf[]
 :pagenums: