Merge branch 'release-v38.0.0' into release

mozilla · May 12, 2021 · 5928b3d · 5928b3d
2 parents 0a40b48 + 5c95689
commit 5928b3d
Show file tree

Hide file tree

Showing 58 changed files with 2,051 additions and 717 deletions.
diff --git a/.buildconfig.yml b/.buildconfig.yml
@@ -1,4 +1,4 @@
-libraryVersion: 37.0.0
+libraryVersion: 38.0.0
 groupId: org.mozilla.telemetry
 projects:
   glean:

diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -528,8 +528,7 @@ jobs:
       - run:
           name: Install new carthage
           command: |
-            time brew update
-            time brew upgrade carthage
+            brew upgrade carthage
       - run:
           name: Set Ruby Version
           command: echo 'chruby ruby-2.7.2' >> ~/.bash_profile
@@ -636,8 +635,7 @@ jobs:
       - run:
           name: Install new carthage
           command: |
-            time brew update
-            time brew upgrade carthage
+            brew upgrade carthage
       - install-rustup
       - setup-rust-toolchain
       - run:

diff --git a/.dictionary b/.dictionary
@@ -1,10 +1,11 @@
-personal_ws-1.1 en 220 utf-8
+personal_ws-1.1 en 221 utf-8
 AAR
 AARs
 ABI
 API's
 APIs
 APK
+AppServices
 BUGFIX
 Bool
 Booleans

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,21 @@
 # Unreleased changes
 
-[Full changelog](https://github.com/mozilla/glean/compare/v37.0.0...main)
+[Full changelog](https://github.com/mozilla/glean/compare/v38.0.0...main)
+
+# v38.0.0 (2021-05-12)
+
+[Full changelog](https://github.com/mozilla/glean/compare/v37.0.0...v38.0.0)
+
+* General
+  * Update documentation to recommend using Glean Dictionary instead of metrics.md ([#1604](https://github.com/mozilla/glean/pull/1604))
+* Rust
+  * **Breaking Change**: Don't return a result from `submit_ping`. The boolean return value indicates whether a ping was submitted ([#1613](https://github.com/mozilla/glean/pull/1613))
+  * **Breaking Change**: Glean now schedules "metrics" pings, accepting a new Configuration parameter. ([#1599](https://github.com/mozilla/glean/pull/1599))
+  * Dispatch setting the source tag to avoid a potential crash ([#1614](https://github.com/mozilla/glean/pull/1614))
+  * Testing mode will wait for init & upload tasks to finish ([#1628](https://github.com/mozilla/glean/pull/1628))
+* Android
+  * Set required fields for `client_info` before optional ones ([#1633](https://github.com/mozilla/glean/pull/1633))
+  * Provide forward-compatibility with Gradle 6.8 ([#1616](https://github.com/mozilla/glean/pull/1633))
 
 # v37.0.0 (2021-04-30)
 

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/DEPENDENCIES.md b/DEPENDENCIES.md
@@ -3248,9 +3248,9 @@ THE SOFTWARE.
 
 The following text applies to code linked from these dependencies:
 
-* [glean 37.0.0]( https://github.com/mozilla/glean )
-* [glean-core 37.0.0]( https://github.com/mozilla/glean )
-* [glean-ffi 37.0.0]( https://github.com/mozilla/glean )
+* [glean 38.0.0]( https://github.com/mozilla/glean )
+* [glean-core 38.0.0]( https://github.com/mozilla/glean )
+* [glean-ffi 38.0.0]( https://github.com/mozilla/glean )
 * [zeitstempel 0.1.1]( https://github.com/badboy/zeitstempel )
 
 

diff --git a/build.gradle b/build.gradle
@@ -20,7 +20,7 @@ buildscript {
         mockito: '2.28.2',  // This is different than a-c, but we're fine, it's only tests.
         mockwebserver: '4.9.1', // This is different than a-c, but we're fine, it's only tests.
         kotlin: '1.4.10',
-        robolectric: '4.2.1', // This is different than a-c, but we're fine, it's only tests.
+        robolectric: '4.5.1', // This is different than a-c, but we're fine, it's only tests.
         rust_android_plugin: '0.8.3',
 
         // Android X dependencies

diff --git a/docs/shared/tabs.js b/docs/shared/tabs.js
@@ -82,7 +82,12 @@ function switchAllTabs(language) {
             button.classList.add("tablinks");
             if (!tabcontent.innerHTML) {
                 button.classList.add("disabled");
-                button.title = `${tabcontent.dataset.lang} does not provide this API`;
+                if (!tabcontent.dataset.bug) {
+                    button.title = `${tabcontent.dataset.lang} does not provide this API`;
+                } else {
+                    button.title =
+                        `${tabcontent.dataset.lang} does not provide this API yet. \nFollow https://bugzilla.mozilla.org/show_bug.cgi?id=${tabcontent.dataset.bug} for updates.`;
+                }
             } else {
                 button.onclick = onClickTab;
             }

diff --git a/docs/user/SUMMARY.md b/docs/user/SUMMARY.md
@@ -46,6 +46,7 @@
 
 # Language Bindings Information
 
+- [Overview](language-bindings/index.md)
 - [Android](language-bindings/android/index.md)
     - [Android build configuration options](language-bindings/android/android-build-configuration-options.md)
     - [Android offline builds](language-bindings/android/android-offline-builds.md)

diff --git a/docs/user/chart.min.js b/docs/user/chart.min.js
diff --git a/docs/user/language-bindings/android/android-build-configuration-options.md b/docs/user/language-bindings/android/android-build-configuration-options.md
@@ -32,7 +32,7 @@ The Glean SDK can automatically generate Markdown documentation for metrics and
 ext.gleanGenerateMarkdownDocs = true
 ```
 
-Flipping the feature to `true` will generate a `metrics.md` file in `$projectDir/docs` at build-time.
+Flipping the feature to `true` will generate a `metrics.md` file in `$projectDir/docs` at build-time. In general this is not necessary for projects using Mozilla's data ingestion infrastructure: in those cases human-readable documentation will automatically be viewable via the [Glean Dictionary](https://dictionary.telemetry.mozilla.org).
 
 ## `gleanDocsDirectory`
 

diff --git a/docs/user/language-bindings/index.md b/docs/user/language-bindings/index.md
@@ -0,0 +1,53 @@
+# Overview
+
+The Glean SDK provides multiple language bindings for integration into different platforms and with different programming languages
+
+## Rust
+
+The Rust bindings can be used with any Rust application.
+It can serve a wide variety of usage patterns,
+such as short-lived CLI applications as well as longer-running desktop or server applications.
+It can optionally send builtin pings at startup.
+It does not assume an interaction model and the integrating application is responsible to connect the respective hooks.
+
+It is available as the [`glean` crate][glean crate] on crates.io.
+
+[glean crate]: https://crates.io/crates/glean
+
+## Kotlin
+
+The Kotlin bindings are primarily used for integration with Android applications.
+It assumes a common interaction model for mobile applications.
+It sends builtin pings at startup of the integrating application.
+
+It is available standalone as `org.mozilla.telemetry:glean`
+or via [Android Components][ac] as `org.mozilla.components:service-glean`
+from the [Mozilla Maven instance][maven].
+
+> *Note*: The Kotlin bindings can also be used from Java.
+
+[ac]: https://github.com/mozilla-mobile/android-components/
+[maven]: https://maven.mozilla.org/?prefix=maven2
+
+See [Android](android/) for more on integrating Glean on Android.
+
+## Swift
+
+The Swift bindings are primarily used for integration with iOS applications.
+It assumes a common interaction model for mobile applications.
+It sends builtin pings at startup of the integrating application.
+
+It is available as a standalone Xcode framework from the [Glean releases page][releases] or bundled with the [AppServices framework][as-releases].
+
+[releases]: https://github.com/mozilla/glean/releases
+[as-releases]: https://github.com/mozilla/application-services/releases
+
+## Python
+
+The Python bindings allow integration with any Python application.
+It can serve a wide variety of usage patterns,
+such as short-lived CLI applications as well as longer-running desktop or server applications.
+
+It is available as [`glean-sdk` on PyPI][pypi].
+
+[pypi]: https://pypi.org/project/glean-sdk/
diff --git a/docs/user/reference/general/index.md b/docs/user/reference/general/index.md
@@ -26,14 +26,27 @@ The Glean SDK provides a general API that supports the following operations. See
 
 The following steps are required for applications using the Glean SDK, but not libraries.
 
-> **Note**: The `initialize` function _must_ be called, even if telemetry upload is disabled.
+{{#include ../../../shared/blockquote-info.html}}
+
+##### Note
+
+> The `initialize` function _must_ be called, even if telemetry upload is disabled.
 > Glean needs to perform maintenance tasks even when telemetry is disabled, and because Glean
 > does this as part of its initialization, it is _required_ to always call the `initialize`
 > function. Otherwise, Glean won't be able to clean up collected data, disable queuing of pre-init
 > tasks, or perform other required operations.
 >
 > This does not apply to special builds where telemetry is disabled at build time. In that case, it is acceptable to not call `initialize` at all.
 
+{{#include ../../../shared/blockquote-stop.html}}
+
+##### Initialize clean with the correct value for `uploadEnabled`!
+
+> `Glean.initialize` must **always** be called with real values.
+> Always pass the user preference, e.g. `Glean.initialize(upload=userSettings.telemetry_enabled)` or the equivalent for your application.
+> Never call `Glean.initialize(upload=true)` if `true` is a placeholder value that later gets reset by `Glean.setUploadEnabled(false)`.
+> Depending on the provided placeholder value, this might trigger the generation of new client ids or the submission of bogus [`deletion-request` pings](../../user/pings/deletion_request.md).
+
 {{#include ../../../shared/tab_header.md}}
 
 <div data-lang="Kotlin" class="tab">