docs[patch]: Add version docs

docs/core_docs/docs/langchain_over_time.mdx → docs/core_docs/docs/versions/overview.mdx

@@ -1,3 +1,8 @@
+---
+sidebar_position: 0
+sidebar_label: Overview
+---
+
 # LangChain Over Time
 
 Due to the rapidly evolving field, LangChain has also evolved rapidly.

docs/core_docs/docs/versions/packages.mdx

@@ -0,0 +1,54 @@
+---
+sidebar_position: 3
+sidebar_label: Packages
+---
+
+# 📕 Package versioning
+
+As of now, LangChain has an ad hoc release process: releases are cut with high frequency by
+a maintainer and published to [NPM](https://npm.org/).
+The different packages are versioned slightly differently.
+
+## `@langchain/core`
+
+`@langchain/core` is currently on version `0.1.x`.
+
+As `@langchain/core` contains the base abstractions and runtime for the whole LangChain ecosystem, we will communicate any breaking changes with advance notice and version bumps.
+The exception for this is anything marked as `beta` (you can see this in the API reference and will see warnings when using such functionality).
+The reason for beta features is that given the rate of change of the field, being able to move quickly is still a priority.
+
+Minor version increases will occur for:
+
+- Breaking changes for any public interfaces marked as `beta`.
+
+Patch version increases will occur for:
+
+- Bug fixes
+- New features
+- Any changes to private interfaces
+- Any changes to `beta` features
+
+## `langchain`
+
+`langchain` is currently on version `0.2.x`
+
+Minor version increases will occur for:
+
+- Breaking changes for any public interfaces NOT marked as `beta`.
+
+Patch version increases will occur for:
+
+- Bug fixes
+- New features
+- Any changes to private interfaces
+- Any changes to `beta` features.
+
+## `@langchain/community`
+
+`@langchain/community` is currently on version `0.2.x`
+
+All changes will be accompanied by the same type of version increase as changes in `langchain`.
+
+## Partner Packages
+
+Partner packages are versioned independently.

docs/core_docs/docs/versions/release_policy.mdx

@@ -0,0 +1,85 @@
+---
+sidebar_position: 2
+sidebar_label: Release Policy
+---
+
+# LangChain releases
+
+The LangChain ecosystem is composed of different component packages (e.g., `@langchain/core`, `langchain`, `@langchain/community`, `@langchain/langgraph`, partner packages etc.)
+
+## Versioning
+
+### `langchain` and `@langchain/core`
+
+`langchain` and `@langchain/core` follow [semantic versioning](https://semver.org/) in the format of 0.**Y**.**Z**. The packages are under rapid development, and so are currently versioning the packages with a major version of 0.
+
+Minor version increases will occur for:
+
+- Breaking changes for any public interfaces marked as `beta`.
+
+Patch version increases will occur for:
+
+- Bug fixes
+- New features
+- Any changes to private interfaces
+- Any changes to `beta` features
+
+When upgrading between minor versions, users should review the list of breaking changes and deprecations.
+
+From time to time, we will version packages as **release candidates**. These are versions that are intended to be released as stable versions, but we want to get feedback from the community before doing so.
+Release candidates will be versioned as 0.**Y**.**Z**-rc**.N**. For example, `0.2.0-rc.1`. If no issues are found, the release candidate will be released as a stable version with the same version number.
+\If issues are found, we will release a new release candidate with an incremented `N` value (e.g., `0.2.0-rc.2`).
+
+### Other packages in the langchain ecosystem
+
+Other packages in the ecosystem (including user packages) can follow a different versioning scheme, but are generally expected to pin to specific minor versions of `langchain` and `@langchain/core`.
+
+## Release cadence
+
+We expect to space out **minor** releases (e.g., from 0.2.0 to 0.3.0) of `langchain` and `@langchain/core` by at least 2-3 months, as such releases may contain breaking changes.
+
+Patch versions are released frequently as they contain bug fixes and new features.
+
+## API stability
+
+The development of LLM applications is a rapidly evolving field, and we are constantly learning from our users and the community. As such, we expect that the APIs in `langchain` and `@langchain/core` will continue to evolve to better serve the needs of our users.
+
+Even though both `langchain` and `@langchain/core` are currently in a pre-1.0 state, we are committed to maintaining API stability in these packages.
+
+- Breaking changes to the public API will result in a minor version bump (the second digit)
+- Any bug fixes or new features will result in a patch version bump (the third digit)
+
+We will generally try to avoid making unnecessary changes, and will provide a deprecation policy for features that are being removed.
+
+### Stability of other packages
+
+The stability of other packages in the LangChain ecosystem may vary:
+
+- `@langchain/community` is a community maintained package that contains 3rd party integrations. While we do our best to review and test changes in `@langchain/community`, `@langchain/community` is expected to experience more breaking changes than `langchain` and `@langchain/core` as it contains many community contributions.
+- Partner packages may follow different stability and versioning policies, and users should refer to the documentation of those packages for more information; however, in general these packages are expected to be stable.
+
+### What is a "API stability"?
+
+API stability means:
+
+- All the public APIs (everything in this documentation) will not be moved or renamed without providing backwards-compatible aliases.
+- If new features are added to these APIs – which is quite possible – they will not break or change the meaning of existing methods. In other words, "stable" does not (necessarily) mean "complete."
+- If, for some reason, an API declared stable must be removed or replaced, it will be declared deprecated but will remain in the API for at least two minor releases. Warnings will be issued when the deprecated method is called.
+
+### **APIs marked as internal**
+
+Certain APIs are explicitly marked as “internal” in a couple of ways:
+
+- Some documentation refers to internals and mentions them as such. If the documentation says that something is internal, it may change.
+- Functions, methods, and other objects prefixed by a leading underscore (**`_`**). If any method starts with a single **`_`**, it’s an internal API.
+  - **Exception:** Certain methods are prefixed with `_` , but do not contain an implementation. These methods are _meant_ to be overridden by sub-classes that provide the implementation. Such methods are generally part of the **Public API** of LangChain.
+
+## Deprecation policy
+
+We will generally avoid deprecating features until a better alternative is available.
+
+When a feature is deprecated, it will continue to work in the current and next minor version of `langchain` and `@langchain/core`. After that, the feature will be removed.
+
+Since we're expecting to space out minor releases by at least 2-3 months, this means that a feature can be removed within 2-6 months of being deprecated.
+
+In some situations, we may allow the feature to remain in the code base for longer periods of time, if it's not causing issues in the packages, to reduce the burden on users.

docs/core_docs/docs/versions/v0_2.mdx

@@ -0,0 +1,91 @@
+---
+sidebar_position: 1
+sidebar_label: v0.2
+---
+
+# LangChain v0.2
+
+LangChain v0.2 was released in May 2024. This release includes a number of breaking changes and deprecations. This document contains a guide on upgrading to 0.2.x, as well as a list of deprecations and breaking changes.
+
+## Migration
+
+This documentation will help you upgrade your code to LangChain `0.2.x.`. To prepare for migration, we first recommend you take the following steps:
+
+1. install the 0.2.x versions of `@langchain/core`, langchain and upgrade to recent versions of other packages that you may be using (e.g. `@langchain/langgraph`, `@langchain/community`, `@langchain/openai`, etc.)
+2. Verify that your code runs properly with the new packages (e.g., unit tests pass)
+3. Install a recent version of `langchain-cli` , and use the tool to replace old imports used by your code with the new imports. (See instructions below.)
+4. Manually resolve any remaining deprecation warnings
+5. Re-run unit tests
+
+### Upgrade to new imports
+
+We created a tool to help migrate your code. This tool is still in **beta** and may not cover all cases, but
+we hope that it will help you migrate your code more quickly.
+
+The migration script has the following limitations:
+
+1. It's limited to helping users move from old imports to new imports. It doesn't help address other deprecations.
+2. It can't handle imports that involve `as` .
+3. New imports are always placed in global scope, even if the old import that was replaced was located inside some local scope (e..g, function body).
+4. It will likely miss some deprecated imports.
+
+Here is an example of the import changes that the migration script can help apply automatically:
+
+| From Package           | To Package                 | Deprecated Import                                                          | New Import                                                                       |
+| ---------------------- | -------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `langchain`            | `@langchain/community`     | `import { UpstashVectorStore } from "langchain/vectorstores/upstash"`      | `import { UpstashVectorStore } from "@langchain/community/vectorstores/upstash"` |
+| `@langchain/community` | `@langchain/openai`        | `import { ChatOpenAI } from "@langchain/community/chat_models/openai"`     | `import { ChatOpenAI } from "@langchain/openai"`                                 |
+| `langchain`            | `@langchain/core`          | `import { Document } from "langchain/schema/document"`                     | `import { Document } from "@langchain/core/documents"`                           |
+| `langchain`            | `@langchain/textsplitters` | `import { RecursiveCharacterTextSplitter } from "langchain/text_splitter"` | `import { RecursiveCharacterTextSplitter } from "@langchain/textsplitters"`      |
+
+#### Deprecation timeline
+
+We have two main types of deprecations:
+
+1. Code that was moved from `langchain` into another package (e.g, `@langchain/community`)
+
+If you try to import it from `langchain`, it will fail since the entrypoint has been removed.
+
+2. Code that has better alternatives available and will eventually be removed, so there's only a single way to do things. (e.g., `predictMessages` method in ChatModels has been deprecated in favor of `invoke`).
+
+Many of these were marked for removal in 0.2. We have bumped the removal to 0.3.
+
+#### Installation
+
+:::note
+The 0.2.X migration script is only available in version `0.0.14-rc.1` or later.
+:::
+
+```bash npm2yarn
+npm i @langchain/scripts@0.0.14-rc.1
+```
+
+#### Usage
+
+Given that the migration script is not perfect, you should make sure you have a backup of your code first (e.g., using version control like `git`).
+
+For example, say your code still uses `import ChatOpenAI from "@langchain/community/chat_models/openai";`:
+
+Invoking the migration script will replace this import with `import ChatOpenAI from "@langchain/openai";`.
+
+```typescript
+import { updateEntrypointsFrom0_x_xTo0_2_x } from "@langchain/scripts/migrations";
+
+const pathToMyProject = "..."; // This path is used in the following glob pattern: `${projectPath}/**/*.{ts,tsx,js,jsx}`.
+
+updateEntrypointsFrom0_x_xTo0_2_x({
+  projectPath: pathToMyProject,
+  shouldLog: true,
+});
+```
+
+#### Other options
+
+```typescript
+updateEntrypointsFrom0_x_xTo0_2_x({
+  projectPath: pathToMyProject,
+  tsConfigPath: "tsconfig.json", // Path to the tsConfig file. This will be used to load all the project files into the script.
+  testRun: true, // If true, the script will not save any changes, but will log the changes that would be made.
+  files: ["..."], // A list of .ts file paths to check. If this is provided, the script will only check these files.
+});
+```