fix: github minor fixes (#1516)

docs_website/docs/integrations/add_github_integration.mdx

@@ -4,15 +4,17 @@ title: GitHub Integration Guide
 sidebar_label: GitHub Integration
 ---
 
-:::info
-Please check the [GitHub User Guide](../user_guide/github_integration.mdx) for detailed instructions on using GitHub features.
+:::warning
+**Experimental Feature:** The GitHub Integration is currently in an experimental phase and may undergo changes that could break existing implementations in future updates. Please use it with caution and stay updated with the latest releases.
 :::
 
 ## Overview
 
 The **GitHub Integration Guide** offers instructions to set up and configure GitHub within Querybook. Follow these steps to allow interaction between Querybook and your GitHub repositories.
 
-> **Note:** The GitHub Integration is an experimental feature. Ensure that all configurations are correctly set to avoid setup issues.
+:::info
+Please check the [GitHub User Guide](../user_guide/github_integration.mdx) for detailed instructions on using GitHub features.
+:::
 
 ## Implementation
 
@@ -108,6 +110,7 @@ public_config:
 
 ## Additional Tips for Developers
 
+-   **OAuth Permissions:** Ensure that users completing the GitHub OAuth process have **write permissions** to the configured GitHub repository (`GITHUB_REPO_NAME`). This is necessary for Querybook to perform actions such as committing changes or managing the repository effectively.
 -   **Security:** Keep your GitHub OAuth credentials secure. Avoid hardcoding sensitive information in configuration files. Store secrets safely and securely using environment variables.
 -   **Testing:** After setting up, perform test commits to verify that the integration works as expected before deploying to production environments.
 

docs_website/docs/user_guide/github_integration.mdx

@@ -55,8 +55,10 @@ The **GitHub** feature allows you to seamlessly link your DataDocs with GitHub r
 
 ## Best Practices
 
+-   **Ensure Changes Are Saved:** Before committing, wait for the DataDoc saving spinner to complete. This ensures all recent changes are saved and included in the GitHub commit.
 -   **Frequent Commits:** Commit your changes regularly to maintain a clear history of your DataDoc's evolution.
 -   **Descriptive Messages:** Use clear and descriptive commit messages to make it easier to understand the purpose of each commit.
+-   **No Changes, No Commit:** If no changes have been made to the DataDoc since the last commit, a new commit will not be created.
 
 ## Version History and Branching
 

querybook/server/lib/github/serializers.py

@@ -101,7 +101,7 @@ def serialize_cell_content(cell: DataCell, exclude_metadata: bool = False) -> st
     cell_meta = cell.meta or {}
 
     if cell.cell_type == DataCellType.query:
-        query_title = cell_meta.get("title", "Query")
+        query_title = cell_meta.get("title") or "Query"
         header = f"## Query: {query_title}\n\n"
         if exclude_metadata:  # Exclude code fences
             content = f"{cell.context.strip()}\n"
@@ -224,7 +224,7 @@ def deserialize_datadoc_content(content_str: str) -> List[DataCell]:
         cell = DataCell(
             id=metadata.get("id"),
             cell_type=cell_type_enum,
-            context=context if cell_type_enum != DataCellType.chart else None,
+            context=context if cell_type_enum != DataCellType.chart else "",
             created_at=parse_datetime_as_utc(metadata.get("created_at")),
             updated_at=parse_datetime_as_utc(metadata.get("updated_at")),
             meta=metadata.get("meta", {}),

querybook/tests/test_lib/test_github_integration/test_serializers.py

@@ -1,6 +1,7 @@
 import pytest
 from const.data_doc import DataCellType
 from lib.github.serializers import (
+    serialize_cell_content,
     serialize_datadoc_to_markdown,
     deserialize_datadoc_from_markdown,
 )
@@ -30,7 +31,7 @@ def mock_datadoc():
         DataCell(
             id=3,
             cell_type=DataCellType.chart,
-            context=None,  # Context is None for chart cells
+            context="",  # Context is None for chart cells
             created_at=datetime(2023, 1, 1, 0, 0, 0, tzinfo=timezone.utc),
             updated_at=datetime(2023, 1, 1, 0, 0, 0, tzinfo=timezone.utc),
             meta={"chart_type": "line"},
@@ -172,3 +173,17 @@ def test_deserialize_with_inner_code_blocks():
     assert deserialized.to_dict(with_cells=True) == expected_datadoc.to_dict(
         with_cells=True
     )
+
+
+def test_serialize_query_cell_with_empty_title():
+    cell = DataCell(
+        id=1,
+        cell_type=DataCellType.query,
+        context="SELECT * FROM table;",
+        created_at=datetime(2023, 1, 1, 0, 0, 0, tzinfo=timezone.utc),
+        updated_at=datetime(2023, 1, 1, 0, 0, 0, tzinfo=timezone.utc),
+        meta={"title": ""},  # Empty title
+    )
+    serialized = serialize_cell_content(cell)
+    expected_header = "## Query: Query\n\n```sql\nSELECT * FROM table;\n```\n"
+    assert serialized == expected_header

requirements/dev.txt

@@ -5,3 +5,8 @@ watchdog[watchmedo]
 black==24.3.0
 pre-commit==2.9.2
 setuptools>=65.5.1 # not directly required, pinned by Snyk to avoid a vulnerability
+
+# GitHub integration dependencies
+pygithub==2.4.0
+cryptography==3.4.8
+requests-oauthlib==1.3.0