DataTalksClub
diff --git a/‎.github/ISSUE_TEMPLATE/faq-proposal.yml‎
Lines changed: 64 additions & 0 deletions b/‎.github/ISSUE_TEMPLATE/faq-proposal.yml‎
Lines changed: 64 additions & 0 deletions
diff --git a/‎.github/workflows/faq-automation.yml‎
Lines changed: 149 additions & 0 deletions b/‎.github/workflows/faq-automation.yml‎
Lines changed: 149 additions & 0 deletions
diff --git a/‎.gitignore‎
Lines changed: 3 additions & 1 deletion b/‎.gitignore‎
Lines changed: 3 additions & 1 deletion
diff --git a/‎CONTRIBUTING.md‎
Lines changed: 162 additions & 0 deletions b/‎CONTRIBUTING.md‎
Lines changed: 162 additions & 0 deletions
@@ -0,0 +1,64 @@
+name: FAQ Proposal
+description: Propose a new FAQ entry or update to existing FAQ
+title: "[FAQ] "
+labels: ["faq-proposal"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ## FAQ Proposal
+
+        Thank you for helping improve our FAQ! Please provide a clear question and answer below.
+
+        Our FAQ bot will automatically analyze your proposal and determine if it should:
+        - Create a new FAQ entry
+        - Update an existing FAQ entry
+        - Mark as duplicate of an existing FAQ
+
+  - type: dropdown
+    id: course
+    attributes:
+      label: Course
+      description: Which course is this FAQ for?
+      options:
+        - machine-learning-zoomcamp
+        - data-engineering-zoomcamp
+        - llm-zoomcamp
+        - mlops-zoomcamp
+    validations:
+      required: true
+
+  - type: textarea
+    id: question
+    attributes:
+      label: Question
+      description: What is the FAQ question?
+      placeholder: "How do I install the required dependencies?"
+    validations:
+      required: true
+
+  - type: textarea
+    id: answer
+    attributes:
+      label: Answer
+      description: What is the answer to this question?
+      placeholder: |
+        To install the required dependencies, run:
+        ```bash
+        uv pip install -r requirements.txt
+        ```
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Checklist
+      description: Please confirm the following
+      options:
+        - label: I have searched existing FAQs and this question is not already answered
+          required: true
+        - label: The answer provides accurate, helpful information
+          required: true
+        - label: I have included any relevant code examples or links
+          required: false
@@ -0,0 +1,149 @@
+name: FAQ Automation
+
+on:
+  issues:
+    types: [opened]
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+
+jobs:
+  process-faq-proposal:
+    if: contains(github.event.issue.labels.*.name, 'faq-proposal')
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install dependencies
+        run: |
+          uv sync --no-dev
+
+      - name: Fetch issue body
+        id: fetch_issue
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const body = context.payload.issue.body || '';
+
+            // Save issue body to file for Python to parse
+            const fs = require('fs');
+            fs.writeFileSync('/tmp/issue_body.txt', body);
+
+            console.log('Fetched issue body, saved to /tmp/issue_body.txt');
+
+      - name: Process FAQ with AI
+        id: process
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+        run: |
+          # Run FAQ automation CLI with full issue body
+          uv run python -m faq_automation.cli \
+            --issue-body "$(cat /tmp/issue_body.txt)" \
+            --issue-number ${{ github.event.issue.number }} \
+            --model "gpt-5-nano" \
+            --output-dir /tmp
+
+          # Write decision output to GitHub Actions
+          uv run scripts/write_faq_decision_output.py
+
+      - name: Handle NEW or UPDATE action
+        if: fromJson(steps.process.outputs.decision).action != 'DUPLICATE'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const decision = ${{ steps.process.outputs.decision }};
+            const action = decision.action;
+            const issueNumber = decision.issue_number;
+            const prBody = decision.pr_body;
+            const filePath = decision.file_path;
+
+            // Create branch name
+            const branchName = `faq-bot/issue-${issueNumber}`;
+
+            // Configure git
+            await exec.exec('git', ['config', 'user.name', 'FAQ Bot']);
+            await exec.exec('git', ['config', 'user.email', '[email protected]']);
+
+            // Fetch and checkout main, then create new branch from it
+            await exec.exec('git', ['fetch', 'origin', 'main']);
+            await exec.exec('git', ['checkout', 'main']);
+            await exec.exec('git', ['checkout', '-b', branchName]);
+
+            // Add modified files
+            await exec.exec('git', ['add', filePath]);
+
+            // Commit changes
+            const commitMsg = `${action}: ${decision.decision.question.substring(0, 72)}`;
+            await exec.exec('git', ['commit', '-m', commitMsg]);
+
+            // Push branch
+            await exec.exec('git', ['push', 'origin', branchName]);
+
+            // Create pull request
+            const { data: pr } = await github.rest.pulls.create({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              title: `[FAQ Bot] ${action}: ${decision.decision.question.substring(0, 72)}`,
+              head: branchName,
+              base: 'main',
+              body: `${prBody}\n\nCloses #${issueNumber}`
+            });
+
+            // Comment on issue with PR link
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: issueNumber,
+              body: `✅ FAQ ${action} proposal created in PR #${pr.number}\n\nPlease review and approve the changes.`
+            });
+
+      - name: Handle DUPLICATE action
+        if: fromJson(steps.process.outputs.decision).action == 'DUPLICATE'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const decision = ${{ steps.process.outputs.decision }};
+            const comment = decision.comment;
+            const issueNumber = decision.issue_number;
+
+            // Post comment
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: issueNumber,
+              body: comment
+            });
+
+            // Close issue
+            await github.rest.issues.update({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: issueNumber,
+              state: 'closed',
+              state_reason: 'completed'
+            });
+
+      - name: Handle errors
+        if: failure()
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const issueNumber = context.payload.issue.number;
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: issueNumber,
+              body: `❌ FAQ Bot encountered an error processing this proposal.\n\nPlease check the [workflow run](${context.payload.repository.html_url}/actions/runs/${context.runId}) for details.\n\nA maintainer will review this manually.`
+            });
@@ -2,4 +2,6 @@
 _site
 __pycache__
 .envrc
-.ipynb_checkpoints/
+.ipynb_checkpoints/
+CLAUDE.md
+*.egg-info/
@@ -0,0 +1,162 @@
+# Contributing to DataTalks.Club FAQ
+
+Thank you for your interest in contributing to the DataTalks.Club FAQ! This guide will help you understand how to propose new FAQ entries or updates.
+
+## Proposing a New FAQ Entry
+
+We have an automated system that helps maintain the FAQ repository. Here's how to propose a new FAQ entry:
+
+### 1. Create a New Issue
+
+1. Go to the [FAQ Proposal form](https://github.com/DataTalksClub/faq/issues/new?template=faq-proposal.yml)
+2. Fill out the form:
+   - **Course**: Which course this FAQ is for (e.g., `machine-learning-zoomcamp`)
+   - **Question**: The FAQ question
+   - **Answer**: A clear, helpful answer with examples if applicable
+   - Check the validation boxes
+
+### 2. Automated Processing
+
+Once you submit your issue, our FAQ Bot will automatically:
+
+1. **Analyze your proposal** using AI to compare it with existing FAQs
+2. **Make a decision**:
+   - **NEW**: Create a new FAQ entry if the question isn't covered
+   - **UPDATE**: Update an existing FAQ if your proposal adds valuable context
+   - **DUPLICATE**: Mark as duplicate if the question is already fully answered
+
+### 3. What Happens Next
+
+#### For NEW or UPDATE Decisions
+
+- A Pull Request will be automatically created with the proposed changes
+- The PR will include:
+  - The new or modified FAQ file(s)
+  - Explanation of why this action was chosen
+  - Section placement and reasoning
+- A maintainer will review the PR
+- Once approved and merged, your FAQ contribution will be live!
+- The originating issue will be automatically closed when the PR is merged
+
+#### For DUPLICATE Decisions
+
+- The bot will comment on your issue with:
+  - Explanation of why it's considered a duplicate
+  - Link to the existing FAQ that covers your question
+  - Link to the source file
+- The issue will be automatically closed
+- If you believe this is incorrect, you can reopen and mention a maintainer
+
+## Writing Good FAQ Entries
+
+### Question Guidelines
+
+- Be specific and clear
+- Use the actual words students might search for
+- Start with question words (How, What, When, Why, etc.)
+- Examples:
+  - ✅ "How do I install Python dependencies using uv?"
+  - ❌ "Dependencies"
+
+### Answer Guidelines
+
+- Start with a direct answer
+- Include code examples when relevant
+- Add links to documentation or resources
+- Keep it concise but complete
+- Use markdown formatting for readability
+
+**Example:**
+
+### Course
+machine-learning-zoomcamp
+
+### Question
+How do I run the tests for this project?
+
+### Answer
+To run all tests, use:
+
+```bash
+make test
+```
+
+For unit tests only:
+
+```bash
+make test-unit
+```
+
+For integration tests only:
+
+```bash
+make test-int
+```
+
+See the [testing documentation](tests/README.md) for more details.
+
+## Manual Contributions
+
+If you prefer to contribute directly via Pull Request:
+
+1. Fork the repository
+2. Create a new branch: `git checkout -b faq/your-topic`
+3. Add your FAQ file in the appropriate location:
+   - `_questions/{course}/{section}/{NNN}_{id}_{slug}.md`
+4. Follow the frontmatter format:
+
+```markdown
+---
+id: abc123
+question: 'Your question here?'
+sort_order: 10
+---
+
+Your answer content here.
+```
+
+5. Update `_questions/{course}/_metadata.yaml` if adding a new section
+6. Run tests: `make test`
+7. Create a Pull Request
+
+## FAQ File Structure
+
+FAQ files are organized as:
+
+```
+_questions/
+├── machine-learning-zoomcamp/
+│   ├── _metadata.yaml          # Course configuration
+│   ├── general/
+│   │   ├── 001_abc123_when-does-course-start.md
+│   │   └── 002_def456_what-are-prerequisites.md
+│   └── module-1/
+│       ├── 001_xyz789_install-docker.md
+│       └── 002_uvw456_docker-errors.md
+└── data-engineering-zoomcamp/
+    └── ...
+```
+
+### Frontmatter Fields
+
+- **id** (required): Unique 10-character identifier
+- **question** (required): The FAQ question
+- **sort_order** (required): Integer for ordering within section
+- **images** (optional): Array of image objects for embedded images
+
+### Markdown Content
+
+- Write the answer in markdown
+- Use code blocks with language specifications
+- Include links where helpful
+- Keep formatting clean and readable
+
+## Questions or Issues?
+
+If you have questions about contributing or encounter issues with the FAQ Bot:
+
+1. Check existing issues for similar questions
+2. Create a new issue with the "question" or "bug" label
+3. Tag a maintainer if urgent
+
+Thank you for helping improve the DataTalks.Club FAQ! 🎉