# dbt Description Suggestions

### Overview <a href="#overview" id="overview"></a>

The **dbt Description Suggestions** feature enables teams to propose and manage changes to dbt resource descriptions directly from Euno's interface. When you suggest a description change, Euno automatically creates a GitHub pull request with the updated YAML file, allowing your team to review, approve, and merge changes through your standard Git workflow.

This feature bridges the gap between metadata management in Euno and source control in your dbt repository, ensuring that documentation improvements flow seamlessly into your codebase.

{% hint style="info" %}
Note: in order to use this feature you must first enable the [Github](#id-1-github-integration) integration
{% endhint %}

### How It Works <a href="#how-it-works" id="how-it-works"></a>

#### Proposing a Description Change <a href="#proposing-a-description-change" id="proposing-a-description-change"></a>

1. **Navigate to Resource:** Open any dbt resource (model, source, etc.) in the Data Model screen
2. **Open Sidepane:** Click on the resource to view its details in the right sidepane
3. **About Tab:** The description section will show a "Propose description" button for eligible resources<br>

   <figure><img src="https://3442486607-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fjd87LSzdZm6uu6WlpVMg%2Fuploads%2Fgit-blob-d8bb5ccf5e7590acf318c05da784933f0a3094f9%2Fimage%20(5).png?alt=media" alt=""><figcaption></figcaption></figure>
4. **Edit Description:** Click the button to open a markdown editor<br>

   <figure><img src="https://3442486607-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fjd87LSzdZm6uu6WlpVMg%2Fuploads%2Fgit-blob-ac9e8e21ca1126dbbf35afeafe9244e743fe0c0d%2Fimage%20(21).png?alt=media" alt=""><figcaption></figcaption></figure>
5. **Submit Proposal:** Review your changes and click "Submit"<br>

   <figure><img src="https://3442486607-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fjd87LSzdZm6uu6WlpVMg%2Fuploads%2Fgit-blob-8916534aff3d12e2f129b9ebb2fc104768b70a48%2Fimage%20(41).png?alt=media" alt=""><figcaption></figcaption></figure>

Euno will then:

1. Create a deterministic branch name based on the resource and user (e.g., `euno/dbt-description/dbt_model/customers-a1b2c3d4`)
2. Fetch the current schema YAML file from the repository
3. Update the description field for the specified resource
4. Commit the change to the branch
5. Create a pull request (or update existing PR if one already exists)
6. Post a comment on the PR with the proposed description

#### Pull Request Details <a href="#pull-request-details" id="pull-request-details"></a>

**Branch Naming Convention:**

```
euno/dbt-description/{resource_type}/{sanitized_resource_name}-{user_hash}
```

**PR Title:**

```
Euno Suggestion: Update {resource_type} "{resource_name}" description
```

**PR Body:**

```markdown
This PR was automatically created by Euno on behalf of **{user_email}**.

**Resource:** `{resource_type}` {resource_name}

**Original Description:**
> {original_description or *None*}

**Suggested Description:**
> {new_description}
```

**Commit Message:**

```
Update description for {resource_type} {resource_name}
```

#### Managing Suggestions <a href="#managing-suggestions" id="managing-suggestions"></a>

**Viewing Active Suggestions**

When a suggestion is pending:

* The resource sidepane shows "Proposal pending approval" badge
* A "View PR" link provides direct access to the GitHub pull request
* Hovering shows creation date and status

**Updating a Suggestion**

To update an existing proposal:

1. Click the "Proposal pending approval" badge
2. Edit the description in the markdown editor
3. Submit the updated proposal

Euno will:

* Commit the new changes to the same branch
* Post a new comment on the PR with the updated description
* Preserve the PR history

#### After PR is Merged <a href="#after-pr-is-merged" id="after-pr-is-merged"></a>

Once your team merges the pull request:

1. The resource sidepane shows "Changes approved, waiting for crawl"
2. During the next crawl, Euno detects the updated description
3. The resource metadata is updated in Euno
4. The suggestion status is automatically cleared

### Limitations <a href="#limitations" id="limitations"></a>

* Only supports GitHub (GitLab and Bitbucket not yet supported)
* One active proposal per user per resource
* Column descriptions must exist in the same schema file as the resource