Adding new issue templates (#185)

* Adding new issue templates * Fixing yaml issue * Fixing indent * Fixing links * Fixing path * Apply suggestions from code review Co-authored-by: Elias Yishak <[email protected]> * Update pkgs/unified_analytics/USAGE_GUIDE.md Co-authored-by: Elias Yishak <[email protected]> --------- Co-authored-by: Elias Yishak <[email protected]>
dart-lang · Oct 31, 2023 · 01c0b52 · 01c0b52
1 parent 5daf7bc
commit 01c0b52
Show file tree

Hide file tree

Showing 3 changed files with 114 additions and 0 deletions.
diff --git a/.github/ISSUE_TEMPLATE/unified_analytics_event.yml b/.github/ISSUE_TEMPLATE/unified_analytics_event.yml
@@ -0,0 +1,47 @@
+name: "[package:unified_analytics] Request a new event"
+description: "Create a request for collecting a new event or new event data."
+labels: "package:unified_analytics"
+body:
+  - type: markdown
+    attributes:
+      value: |
+        An event is an action that a user, or the tool, performs. 
+        You can see the events that are being collected [here](../../pkgs/unified_analytics/lib/src/enums.dart)
+        and the data associated with those events [here](../../pkgs/unified_analytics/lib/src/event.dart).
+  - type: checkboxes
+    attributes:
+      label: Has this already been approved in the privacy design documentation?
+      options:
+        - label: This field is already covered in the PDD 
+      description: |
+        You can request that a new event be added to the package 
+        regardless of whether it's included in the privacy design documentation. 
+        However, the privacy team will need to approve before it is added.
+            
+  - type: textarea
+    attributes:
+      label: Event name
+      description: |
+        If the event already exists, please tell us the name of the event 
+        you would like to add data to.
+
+        If this is a new event, tell us the name, description, and tool owner. 
+        Possible tool owners can be found in the `DashTool` enum [here](../../pkgs/unified_analytics/lib/src/enums.dart).
+
+        For example, pub_get represents pub package resolution details. The owner is the Dart tool.
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Event data
+      description: |
+        Event data are key-value pairs that are associated with an event.
+        Please list the different event data associated with this event. 
+        You should also include a description of the event data values.
+
+        For example, if the event is pub_get, one event data may be 
+        the packageName. The values would be the name of the package 
+        as a string.
+    validations:
+      required: true
diff --git a/.github/ISSUE_TEMPLATE/unified_analytics_user_property.yml b/.github/ISSUE_TEMPLATE/unified_analytics_user_property.yml
@@ -0,0 +1,37 @@
+name: "[package:unified_analytics] Request a new user property"
+description: "Create a request for collecting a new user property."
+labels: "package:unified_analytics"
+body:
+  - type: markdown
+    attributes:
+      value: |
+        A user property is a key-value pair that is used to segment users. 
+        For example, the Flutter channel that the user is on. You can see 
+        which user properties are being collected 
+        [here](../../pkgs/unified_analytics/lib/src/user_property.dart).
+
+  - type: checkboxes
+    attributes:
+      label: Has this already been approved in the privacy design documentation?
+      options:
+        - label: This field is already covered in the PDD 
+      description: |
+        You can request that a new user property be added to the package 
+        regardless of whether it's included in the privacy design documentation. 
+        However, the privacy team will need to approve before it is added.
+          
+  - type: textarea
+    attributes:
+      label: User property name
+      description: |
+        Please tell us the name of the user property you would like to add (e.g. flutter_channel).
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: User property values
+      description: |
+        Please list or describe the unique values for this property (e.g. master, beta, stable).
+    validations:
+      required: true
diff --git a/pkgs/unified_analytics/USAGE_GUIDE.md b/pkgs/unified_analytics/USAGE_GUIDE.md
@@ -126,6 +126,36 @@ the consent message.
 
 ## Developing Within `package:unified_analytics`
 
+### Adding new data classes
+
+#### User properties
+In Google Analytics, new data fields can be collected as user properties 
+or events. 
+
+User properties are key-value pairs that can be used to segment users. For example, 
+the Flutter channel used. To request that a new user property 
+be added, file an issue [using this template](https://github.com/dart-lang/tools/issues/new?template=unified_analytics_user_property.yml). 
+
+To add a new user property, add a new property to the `UserProperty` class 
+in the [`user_property.dart` file](./lib/src/user_property.dart). 
+
+#### Events
+Events are actions that the user, or tool, performs. In Google Analytics, 
+events can have associated data. This event data is stored 
+in key-value pairs. 
+
+To request new events, or event data, file an issue 
+[using this template](https://github.com/dart-lang/tools/issues/new?template=unified_analytics_event.yml).
+
+To add a new event, create a new field in the `DashEvent` enum (if necessary) in
+the [`enums.dart` file](./lib/src/enums.dart). 
+
+Then, add event data, create a new constructor for the `Event` class 
+in the [`event.dart` file](./lib/src/event.dart).
+
+
+### Testing event collection
+
 When contributing to this package, if the developer needs to verify that
 events have been sent, the developer should the use development constructor
 so that the events being sent are not going into the production instance.