Release - 2.1.0

CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# How to contribute to the Telemetry library
+
+**Did you find a bug?**
+- Search through [open issues](https://github.com/stellarwp/telemetry/issues) to **ensure the bug has not already been reported**.
+- Once you've verified the issue has not been reported, [open a new issue](https://github.com/stellarwp/telemetry/issues/new). Please include a title and clear description, as much relevant information as possible, a code sample or testing steps to demonstrate the issue.
+
+**Did you fix a bug?**
+- Open a new GitHub pull request with the fix.
+- Clearly describe the problem and solution in the PR's description field. If it fixes an open issue, please include the issue number.
+
+## Development Workflow
+
+The library uses a [gitflow process](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow) to coordinate releases and ongoing development.
+
+<img src="docs/img/git-flow.svg" alt="A diagram showing the git branching structure for the library" width="700" style="display: block; margin: 25px auto;">
+
+Branch all new code from [`develop`](https://github.com/stellarwp/telemetry/tree/develop) and once the feature or bugfix is complete, submit a pull request to be merged back into `develop`. **The PR will need to be code-reviewed and fully tested before it is merged**.
+
+When a new release is planned, a new `release/[version]` branch will be created from the current develop branch. **No other PRs will be merged into the release branch.** It will be used to update all docblocks using `@since TBD` values and prep the library for a new release.
+
+The library uses semantic versioning where the version number is represented as: `[major].[minor].[patch]`
+
+- **Major**: This release will have breaking changes.
+- **Minor**: This release includes new features and bugfixes.
+- **Patch**: This release only includes bug fixes.
+
+Release candidates will be represented as: `[major].[minor].[patch]-rc.[candidate-number]`
+- The candidate number should have a leading 0 (i.e. `1.0.0-rc.01`)
+
+**At this point, the library should be fully tested and documentation complete.**
+
+When the release is complete, it will be merged into `main` and tagged with the version number to be updated on [Packagist](https://packagist.org/packages/stellarwp/telemetry) and in the [lastest releases](https://github.com/stellarwp/telemetry/releases).

README.md

@@ -31,6 +31,7 @@ A library for Opt-in and Telemetry data to be sent to the StellarWP Telemetry se
 		- [stellarwp/telemetry/exit\_interview\_args](#stellarwptelemetryexit_interview_args)
 		- [stellarwp/telemetry/{stellar\_slug}/exit\_interview\_args](#stellarwptelemetrystellar_slugexit_interview_args)
 	- [Adding Plugin Data to Site Health](#adding-plugin-data-to-site-health)
+	- [Capturing User Events](#capturing-user-events)
 ## Installation
 
 It's recommended that you install Telemetry as a project dependency via [Composer](https://getcomposer.org/):
@@ -434,3 +435,61 @@ function add_summary_to_telemtry( $info ) {
 
 add_filter( 'debug_information', 'add_summary_to_telemetry', 10, 1) ;
 ```
+
+## Capturing User Events
+
+When a user completes an action, an event can be captured with the telemetry server for a specific site. These events take `name` and `data` (array) parameters to capture any specific information necessary for the event.
+
+Some examples of actions you may want to capture:
+- User creates their first post
+- A plugin feature is used for the first time (but not completed or utilized)
+- X days have passed and a feature has not yet been utilized
+
+**NOTE: All plugins should trigger an event when a user opts out of telemetry for a site.**
+
+To create an event, set up a do_action with the necessary details wherever you'd like to capture it:
+```php
+// Event data is sent to the telemetry server as JSON.
+$data = [
+	'one'   => 1,
+	'two'   => 2,
+	'three' => 3,
+];
+do_action( 'stellarwp/telemetry/event', 'your-event-name', $data );
+```
+
+Here is how you might log events when a user creates a new post:
+```php
+/**
+ * Log event when a user creates a new post.
+ *
+ * @action save_post
+ *
+ * @param int     $post_id The ID of the post being saved.
+ * @param WP_Post $post    The post object being saved.
+ * @param bool    $update  If this is an update to a pre-existing post.
+ *
+ * @return void
+ */
+function user_creates_post( $post_id, $post, $update ) {
+	// Only send events for new posts.
+	if ( $update ) {
+		return;
+	}
+
+	// Only send event for posts, avoid everything else.
+	if ( $post->post_type !== 'post' ) {
+		return;
+	}
+
+	// Add any data to the event that needs to be captured.
+	$event_data = [
+		'title'   => $post->post_title,
+		'content' => $post->post_content,
+		'some-other-data' => 'use the array to capture anything else that might be necessary for context'
+	];
+
+	// Log the event with the telemetry server.
+	do_action( 'stellarwp/telemetry/event', 'new_post', $event_data );
+}
+```