improve public documentation for authoring an integration

Author: haetamoudi

docs/extend/_publish_an_integration.md

@@ -3,32 +3,39 @@ mapped_pages:
   - https://www.elastic.co/guide/en/integrations-developer/current/_publish_an_integration.html
 ---
 
-# Publish an integration [_publish_an_integration]
+# Publish an integration via Pull Request[_publish_an_integration]
 
-When your integration is done, it’s time to open a PR to include it in the integrations repository. Before opening your PR, run:
+When your integration is done, it’s time to open a PR to include it in the integrations repository. 
+Before opening your PR, make sure you have:
 
+1. Pass all checks
+Run:
 ```bash
 elastic-package check
 ```
 
-The `check` command ensures the package is built correctly, formatted properly, and aligned with the spec. Passing the `check` command is required before adding your integration to the repository.
+This command validates that your package is built correctly, formatted properly, and aligned with the specification. Passing this `check` is required before submitting your integration.
 
-When CI is happy, merge your PR into the integrations repository.
+2. Added a new entry into `changelog.yml`
+Update the package’s `changelog.yml` with a clear description of your changes for the new version.
 
-CI will kick off a build job for the main branch, which can release your integration to the package-storage. It means that it will open a PR to the Package Storage/snapshot with the built integration if only the package version doesn’t already exist in the storage (hasn’t been released yet).
+3. Bumped the package version
+If you are releasing new changes, increment the version in your manifest.yml file. This is required for the package to be published.
 
+4. Wrote clear PR title and description
+- Use a concise, descriptive title (e.g., `[New Integration] Add Acme Logs integration`).
+- In the PR description, summarize what your integration or change does, list key features or fixes, reference related issues, and provide testing instructions.
+- Ensure your documentation, sample events, and tests are included and up to date.
 
-## Promote [_promote]
+::::{tip}
+A well-written PR with clear documentation, versioning, and testing instructions will speed up the review and publishing process!
+::::
 
-Now that you’ve tested your integration with {{kib}}, it’s time to promote it to staging or production. Run:
 
-```bash
-elastic-package promote
-```
+When CI is happy, merge your PR into the integrations repository.
 
-The tool will open 2 pull requests (promote and delete) to the package-storage: target and source branches.
+Once the PR with the new version of the package is merged, the required CI pipelines are triggered to release that new version into Package Storage V2 and make them available in https://epr.elastic.co.
 
-Please review both pull requests on your own, check if CI is happy and merge - first target, then source. Once any PR is merged, the CI will kick off a job to bake a new Docker image of package-storage (tracking). Ideally the "delete" PR should be merged once the CI job for "promote" is done, as the Docker image of previous stage depends on the later one.
 
 ::::{tip}
 When you are ready for your changes in the integration to be released, remember to bump up the package version. It is up to you, as the package developer, to decide how many changes you want to release in a single version. For example, you could implement a change in a PR and bump up the package version in the same PR. Or you could implement several changes across multiple pull requests and then bump up the package version in the last of these pull requests or in a separate follow up PR.

docs/extend/add-data-stream.md

@@ -20,24 +20,39 @@ apache
 
 A data stream defines multiple {{es}} assets, like index templates, ingest pipelines, and field definitions. These assets are loaded into {{es}} when a user installs an integration using the {{fleet}} UI in {{kib}}.
 
-A data stream also defines a policy template. Policy templates include variables that allow users to configure the data stream using the {{fleet}} UI in {{kib}}. Then, the {{agent}} interprets the resulting policy to collect relevant information from the product or service being observed. Policy templates can also define an integration’s supported [`deployment_modes`](/extend/define-deployment-modes.md#deployment_modes).
+A data stream also defines a policy template. Policy templates include variables that allow users to configure the data stream using the {{fleet}} UI in {{kib}}. Then, the {{agent}} interprets the resulting policy to collect relevant information from the product or service being observed. Policy templates can also define an integration’s supported [`deployment_modes`](/extend/define-deployment-modes.md#set-deployment-modes).
 
 See [data streams](docs-content://reference/fleet/data-streams.md) for more information.
 
 ::::
 
+## How to add a data stream [how-to]
 
-Bootstrap a new data stream using the TUI wizard. In the directory of your package, run:
+1. Boostrap a new data stream
+
+In your package directory, run:
 
 ```bash
 elastic-package create data-stream
 ```
 
-Follow the prompts to name, title, and select your data stream type. Then, run this command each time you add a new data stream to your integration.
+Follow the prompts to set the name, title, and type (logs, metrics, etc.) for the data stream. Repeat this command for each new data stream you want to add.
+
+2. Configure the data stream
+
+After bootstrapping, manually adjust the generated files to suit your use case:
+
+* Define required variables:
+In the policy template, specify variables that users can configure (e.g., paths, ports, log levels).
+* Define used fields:
+Edit the fields/ files to describe the structure and types of data your stream will ingest.
+* Define ingest pipeline definitions:
+If needed, create or update ingest pipelines to parse, enrich, or transform incoming data before it’s indexed.
+* Update the {{agent}} stream configuration:
+Ensure the {{agent}}’s stream configuration matches your data collection requirements and references the correct variables and pipelines.
 
-Next, manually adjust the data stream:
+3. How data streams are used
 
-* define required variables
-* define used fields
-* define ingest pipeline definitions (if necessary)
-* update the {{agent}}'s stream configuration
+* When the integration is installed, each data stream is registered in {{es}} as a managed, time-based resource.
+* Data sent to the data stream is automatically routed to the correct backing indices, with lifecycle management (rollover, retention) handled by Elasticsearch.
+* Users can query, visualize, and analyze data from each stream in {{kib}}, using the single data stream name (e.g., `logs-apache.access`).