update-integrations-prs

# Update integrations PRs Process contributor integration docs PRs in `langchain-ai/docs` so they match the [hosted-guide eligibility rules](https://docs.langchain.com/oss/contributing/publish-langchain#eligibility-for-hosted-guides) from [#4865](https://github.com/langchain-ai/docs/pull/4865). For **new** listings filed as GitHub issues (issue form + `integration-submission` label), use the `submit-integration` skill instead. That path creates listing changes for CI to open a PR. ## Policy | Case | Action | |------|--------| | **≥50K monthly downloads** (PyPI or npm) **or** maintainer feature override | Keep hosted MDX. Ensure correct `integration:` frontmatter. May set `highlight: true` in `packages.yml` and regenerate overview via `partner_pkg_table` (**never** hand-edit `overview.mdx`). | | **Under 50K**, not featured | Remove hosted pages. Add YAML to `scripts/data/integration_external_docs.yaml`. Surface via downloads tables / `all_providers`. Prefer partner docs URLs. Keep `packages.yml` when there is a public LangChain-related package. | Policy source: `src/oss/contributing/publish-langchain.mdx` and `src/oss/contributing/integrations-langchain.mdx`. ## Workflow checklist Copy and track: ``` - [ ] Identify PR + package name(s) - [ ] Report monthly downloads (PyPI and/or npm) - [ ] Decide: hosted/feature vs external - [ ] Rebase onto upstream/main (keep contributor commits) - [ ] Apply conversion in a **separate** commit - [ ] Verify net diff vs main - [ ] Report result; do **not** push unless asked ``` ### 1. Inspect the current branch ```bash git branch --show-current gh pr view --json number,title,url,author,maintainerCanModify,files,body git diff --stat upstream/main...HEAD ``` Find the LangChain-related package name(s) from `packages.yml`, MDX install snippets, or registry metadata. Ignore unrelated packages with similar names. ### 2. Measure downloads **PyPI** (last ~30 days, no mirrors): ```bash curl -s "https://pypistats.org/api/packages/<pkg>/overall?mirrors=false" \ | python3 -c "import sys,json; d=json.load(sys.stdin); data=d.get('data',[]); last30=data[-30:] if len(data)>=30 else data; print(sum(x.get('downloads',0) for x in last30))" curl -s "https://pypistats.org/api/packages/<pkg>/recent" ``` **npm** (last month): ```bash curl -s "https://api.npmjs.org/downloads/point/last-month/<pkg>" ``` Report the number to the user before converting when they asked for downloads only. ### 3. Rebase ```bash git fetch upstream main git rebase upstream/main ``` - Keep contributor commits; put the conversion in a **new** commit after rebase. - On heavy merge history, cherry-pick content commits onto `upstream/main`, then convert. - Drop obsolete Card grids that main replaced with `IntegrationDownloads`. - Drop redirects for pages that were never on `main`. - Drop unrelated `packages.yml` download-count churn from bot commits. ### 4a. External conversion (under 50K) 1. **Delete** hosted MDX (component page and provider page if present). 2. **Add YAML** under the correct language + component in `scripts/data/integration_external_docs.yaml`: ```yaml - name: ClassOrDisplayName pypi: langchain-example # or npm: "@org/pkg" under javascript: docs_url: https://partner.example/docs ``` Prefer partner docs, then public GitHub/GitLab README, then PyPI/npm. 3. **Downloads snippet** (sort by `data-sort-value`): add a row to the matching `src/snippets/oss/*-*-downloads.mdx` (for example `python-sandboxes-downloads.mdx`). Match existing badge markup. 4. **`all_providers`**: card with external `href` (alphabetical). Use `icon="link"` or an existing provider icon. 5. **`packages.yml`**: append only for a public LangChain-related package. Ensure a trailing newline before appending. Omit `path: .`. Skip if the source repo is private or not a normal public VCS listing. 6. **Nav / redirects**: remove `docs.json` entries and redirects for deleted never-on-main pages. Do not add redirects for pages that never shipped. 7. **Deep Agents / indexes**: if the PR added provider cards that main no longer uses, prefer downloads tables and index grids; keep brief mentions only when main already lists providers that way. Align listings with **partner docs**, not stale PR page counts. ### 4b. Hosted / featured path (≥50K or override) 1. Keep (or fix) hosted MDX; test code examples when touching them. 2. Frontmatter: follow templates under `src/oss/*/integrations/**/TEMPLATE.mdx`. Do not set `featured: true` unless a maintainer asked. 3. Prefer `langchain` imports over `langchain_core` when editing kept pages. 4. For featuring: set `highlight: true` in `packages.yml` only when asked; regenerate overview with the partner package table tool, do not hand-edit `overview.mdx`. 5. Update `src/docs.json` if adding a page that should stay. ### 5. Commit and handoff - Conversion commit message focuses on why (threshold / external listing / feature). - Show `git diff --stat upstream/main...HEAD` and downloads in the summary. - Note `maintainerCanModify` for push later. - **Do not push** unless the user asks. Use force-with-lease after rebase when pushing to the PR head. - If `maintainerCanModify: false`, say so and ask whether to open a replacement PR. ## Hard rules - Ask for clarification rather than assuming package identity or feature overrides. - Never fabricate download counts, docs URLs, or package names. - Never edit `build/`. - Never hand-edit generated overview tables. - When appending to `packages.yml`, ensure a trailing newline first. - Run `make lint_prose FILES="..."` on changed MDX before handoff when prose changed. - Follow repo git safety: no bare `git push`; no force to main; no commit unless asked (except when the user said "go" / "next branch" for this workflow, commit the conversion). ## Common pitfalls | Pitfall | Fix | |---------|-----| | Wrong package (similar name on PyPI) | Confirm against install snippets and partner repo | | Re-adding Card grids removed on main | Use `IntegrationDownloads` / YAML only | | Redirects for never-shipped pages | Delete them | | Duplicate table rows | Remove YAML if keeping hosted page | | Private source repo | Skip incomplete `packages.yml` entry | | JS + Python packages | Add both YAML sections / download rows when both exist | ## Reference - Eligibility docs: `/oss/contributing/publish-langchain#eligibility-for-hosted-guides` - YAML data: `scripts/data/integration_external_docs.yaml` - Downloads snippets: `src/snippets/oss/*-downloads.mdx` - Package registry: `packages.yml` - Policy PR: https://github.com/langchain-ai/docs/pull/4865