CONTRIBUTING.md Quick Start: focus on langchain core; clarify docs and experimental are separate (#10906)

follow up to #7959 ,
explaining better to focus just on langchain core

no dependencies

twitter @cjcjameson

Author: cjcjameson

.github/CONTRIBUTING.md

@@ -14,8 +14,8 @@ Please do not try to push directly to this repo unless you are a maintainer.
 Please follow the checked-in pull request template when opening pull requests. Note related issues and tag relevant
 maintainers.
 
-Pull requests cannot land without passing the formatting, linting and testing checks first. See
-[Common Tasks](#-common-tasks) for how to run these checks locally.
+Pull requests cannot land without passing the formatting, linting and testing checks first. See [Testing](#testing) and
+[Formatting and Linting](#formatting-and-linting) for how to run these checks locally.
 
 It's essential that we maintain great documentation and testing. If you:
 - Fix a bug
@@ -59,43 +59,85 @@ we do not want these to get in the way of getting good code into the codebase.
 
 ## 🚀 Quick Start
 
-> **Note:** You can run this repository locally (which is described below) or in a [development container](https://containers.dev/) (which is described in the [.devcontainer folder](https://github.com/hwchase17/langchain/tree/master/.devcontainer)).
+This quick start describes running the repository locally.
+For a [development container](https://containers.dev/), see the [.devcontainer folder](https://github.com/hwchase17/langchain/tree/master/.devcontainer).
 
-This project uses [Poetry](https://python-poetry.org/) v1.5.1 as a dependency manager. Check out Poetry's [documentation on how to install it](https://python-poetry.org/docs/#installation) on your system before proceeding.
+### Dependency Management: Poetry and other env/dependency managers
 
-❗Note: If you use `Conda` or `Pyenv` as your environment/package manager, avoid dependency conflicts by doing the following first:
-1. *Before installing Poetry*, create and activate a new Conda env (e.g. `conda create -n langchain python=3.9`)
-2. Install Poetry v1.5.1 (see above)
-3. Tell Poetry to use the virtualenv python environment (`poetry config virtualenvs.prefer-active-python true`)
-4. Continue with the following steps.
+This project uses [Poetry](https://python-poetry.org/) v1.5.1+ as a dependency manager.
+
+❗Note: *Before installing Poetry*, if you use `Conda`, create and activate a new Conda env (e.g. `conda create -n langchain python=3.9`)
+
+Install Poetry: **[documentation on how to install it](https://python-poetry.org/docs/#installation)**.
+
+❗Note: If you use `Conda` or `Pyenv` as your environment/package manager, after installing Poetry,
+tell Poetry to use the virtualenv python environment (`poetry config virtualenvs.prefer-active-python true`)
+
+### Core vs. Experimental
 
 There are two separate projects in this repository:
 - `langchain`: core langchain code, abstractions, and use cases
-- `langchain.experimental`: more experimental code
+- `langchain.experimental`: see the [Experimental README](../libs/experimental/README.md) for more information.
+
+Each of these has their own development environment. Docs are run from the top-level makefile, but development
+is split across separate test & release flows.
 
-Each of these has their OWN development environment.
-In order to run any of the commands below, please move into their respective directories.
-For example, to contribute to `langchain` run `cd libs/langchain` before getting started with the below.
+For this quickstart, start with langchain core:
 
-To install requirements:
+```bash
+cd libs/langchain
+```
+
+### Local Development Dependencies
+
+Install langchain development requirements (for running langchain, running examples, linting, formatting, tests, and coverage):
 
 ```bash
 poetry install --with test
 ```
 
-This will install all requirements for running the package, examples, linting, formatting, tests, and coverage.
+Then verify dependency installation:
 
-❗Note: If during installation you receive a `WheelFileValidationError` for `debugpy`, please make sure you are running Poetry v1.5.1. This bug was present in older versions of Poetry (e.g. 1.4.1) and has been resolved in newer releases. If you are still seeing this bug on v1.5.1, you may also try disabling "modern installation" (`poetry config installer.modern-installation false`) and re-installing requirements. See [this `debugpy` issue](https://github.com/microsoft/debugpy/issues/1246) for more details.
+```bash
+make test
+```
 
-Now assuming `make` and `pytest` are installed, you should be able to run the common tasks in the following section. To double check, run `make test` under `libs/langchain`, all tests should pass. If they don't, you may need to pip install additional dependencies, such as `numexpr` and `openapi_schema_pydantic`.
+If the tests don't pass, you may need to pip install additional dependencies, such as `numexpr` and `openapi_schema_pydantic`.
 
-## ✅ Common Tasks
+If during installation you receive a `WheelFileValidationError` for `debugpy`, please make sure you are running
+Poetry v1.5.1+. This bug was present in older versions of Poetry (e.g. 1.4.1) and has been resolved in newer releases.
+If you are still seeing this bug on v1.5.1, you may also try disabling "modern installation"
+(`poetry config installer.modern-installation false`) and re-installing requirements.
+See [this `debugpy` issue](https://github.com/microsoft/debugpy/issues/1246) for more details.
 
-Type `make` for a list of common tasks.
+### Testing
 
-### Code Formatting
+_some test dependencies are optional; see section about optional dependencies_.
 
-Formatting for this project is done via a combination of [Black](https://black.readthedocs.io/en/stable/) and [isort](https://pycqa.github.io/isort/).
+Unit tests cover modular logic that does not require calls to outside APIs.
+If you add new logic, please add a unit test.
+
+To run unit tests:
+
+```bash
+make test
+```
+
+To run unit tests in Docker:
+
+```bash
+make docker_tests
+```
+
+There are also [integration tests and code-coverage](../libs/langchain/tests/README.md) available.
+
+### Formatting and Linting
+
+Run these locally before submitting a PR; the CI system will check also.
+
+#### Code Formatting
+
+Formatting for this project is done via a combination of [Black](https://black.readthedocs.io/en/stable/) and [ruff](https://docs.astral.sh/ruff/rules/).
 
 To run formatting for this project:
 
@@ -111,9 +153,9 @@ make format_diff
 
 This is especially useful when you have made changes to a subset of the project and want to ensure your changes are properly formatted without affecting the rest of the codebase.
 
-### Linting
+#### Linting
 
-Linting for this project is done via a combination of [Black](https://black.readthedocs.io/en/stable/), [isort](https://pycqa.github.io/isort/), [flake8](https://flake8.pycqa.org/en/latest/), and [mypy](http://mypy-lang.org/).
+Linting for this project is done via a combination of [Black](https://black.readthedocs.io/en/stable/), [ruff](https://docs.astral.sh/ruff/rules/), and [mypy](http://mypy-lang.org/).
 
 To run linting for this project:
 
@@ -131,7 +173,7 @@ This can be very helpful when you've made changes to only certain parts of the p
 
 We recognize linting can be annoying - if you do not want to do it, please contact a project maintainer, and they can help you with it. We do not want this to be a blocker for good code getting contributed.
 
-### Spellcheck
+#### Spellcheck
 
 Spellchecking for this project is done via [codespell](https://github.com/codespell-project/codespell).
 Note that `codespell` finds common typos, so it could have false-positive (correctly spelled but rarely used) and false-negatives (not finding misspelled) words.
@@ -157,17 +199,7 @@ If codespell is incorrectly flagging a word, you can skip spellcheck for that wo
 ignore-words-list = 'momento,collison,ned,foor,reworkd,parth,whats,aapply,mysogyny,unsecure'
 ```
 
-### Coverage
-
-Code coverage (i.e. the amount of code that is covered by unit tests) helps identify areas of the code that are potentially more or less brittle.
-
-To get a report of current coverage, run the following:
-
-```bash
-make coverage
-```
-
-### Working with Optional Dependencies
+## Working with Optional Dependencies
 
 Langchain relies heavily on optional dependencies to keep the Langchain package lightweight.
 
@@ -192,51 +224,7 @@ To introduce the dependency to the pyproject.toml file correctly, please do the
 test makes use of lightweight fixtures to test the logic of the code.
 5. Please use the `@pytest.mark.requires(package_name)` decorator for any tests that require the dependency.
 
-### Testing
-
-See section about optional dependencies.
-
-#### Unit Tests
-
-Unit tests cover modular logic that does not require calls to outside APIs.
-
-To run unit tests:
-
-```bash
-make test
-```
-
-To run unit tests in Docker:
-
-```bash
-make docker_tests
-```
-
-If you add new logic, please add a unit test.
-
-
-
-#### Integration Tests
-
-Integration tests cover logic that requires making calls to outside APIs (often integration with other services).
-
-**warning** Almost no tests should be integration tests.
-
-  Tests that require making network connections make it difficult for other
-  developers to test the code.
-
-  Instead favor relying on `responses` library and/or mock.patch to mock
-  requests using small fixtures.
-
-To run integration tests:
-
-```bash
-make integration_tests
-```
-
-If you add support for a new external API, please add a new integration test.
-
-### Adding a Jupyter Notebook
+## Adding a Jupyter Notebook
 
 If you are adding a Jupyter Notebook example, you'll want to install the optional `dev` dependencies.
 
@@ -259,6 +247,12 @@ When you run `poetry install`, the `langchain` package is installed as editable
 While the code is split between `langchain` and `langchain.experimental`, the documentation is one holistic thing.
 This covers how to get started contributing to documentation.
 
+From the top-level of this repo, install documentation dependencies:
+
+```bash
+poetry install
+```
+
 ### Contribute Documentation
 
 The docs directory contains Documentation and API Reference.

Makefile

@@ -42,7 +42,8 @@ spell_fix:
 ######################
 
 help:
-	@echo '----'
+	@echo '===================='
+	@echo '-- DOCUMENTATION --'
 	@echo 'clean                        - run docs_clean and api_docs_clean'
 	@echo 'docs_build                   - build the documentation'
 	@echo 'docs_clean                   - clean the documentation build artifacts'
@@ -51,4 +52,5 @@ help:
 	@echo 'api_docs_clean               - clean the API Reference documentation build artifacts'
 	@echo 'api_docs_linkcheck           - run linkchecker on the API Reference documentation'
 	@echo 'spell_check               	- run codespell on the project'
-	@echo 'spell_fix               		- run codespell on the project and fix the errors'
+	@echo 'spell_fix               		- run codespell on the project and fix the errors'
+	@echo '-- TEST and LINT tasks are within libs/*/ per-package --'

libs/experimental/README.md

@@ -13,4 +13,4 @@ Some of the code here may be marked with security notices. However,
 given the exploratory and experimental nature of the code in this package,
 the lack of a security notice on a piece of code does not mean that
 the code in question does not require additional security considerations
-in order to be safe to use.
+in order to be safe to use.

libs/langchain/Makefile

@@ -14,33 +14,6 @@ coverage:
 		--cov-report xml \
 		--cov-report term-missing:skip-covered
 
-######################
-# DOCUMENTATION
-######################
-
-clean: docs_clean api_docs_clean
-
-
-docs_build:
-	docs/.local_build.sh
-
-docs_clean:
-	rm -r docs/_dist
-
-docs_linkcheck:
-	poetry run linkchecker docs/_dist/docs_skeleton/ --ignore-url node_modules
-
-api_docs_build:
-	poetry run python docs/api_reference/create_api_rst.py
-	cd docs/api_reference && poetry run make html
-
-api_docs_clean:
-	rm -f docs/api_reference/api_reference.rst
-	cd docs/api_reference && poetry run make clean
-
-api_docs_linkcheck:
-	poetry run linkchecker docs/api_reference/_build/html/index.html
-
 # Define a variable for the test file path.
 TEST_FILE ?= tests/unit_tests/
 
@@ -98,7 +71,6 @@ spell_fix:
 
 help:
 	@echo '===================='
-	@echo '-- DOCUMENTATION --'
 	@echo 'clean                        - run docs_clean and api_docs_clean'
 	@echo 'docs_build                   - build the documentation'
 	@echo 'docs_clean                   - clean the documentation build artifacts'
@@ -120,3 +92,4 @@ help:
 	@echo 'test_watch                   - run unit tests in watch mode'
 	@echo 'integration_tests            - run integration tests'
 	@echo 'docker_tests                 - run unit tests in docker'
+	@echo '-- DOCUMENTATION tasks are from the top-level Makefile --'

libs/langchain/tests/README.md

@@ -1,12 +1,52 @@
-# Readme tests(draft)
+# Langchain Tests
 
-## Integrations Tests
+## Unit Tests
+
+Unit tests cover modular logic that does not require calls to outside APIs.
+If you add new logic, please add a unit test.
+
+To run unit tests:
+
+```bash
+make test
+```
+
+To run unit tests in Docker:
+
+```bash
+make docker_tests
+```
+
+## Integration Tests
+
+Integration tests cover logic that requires making calls to outside APIs (often integration with other services).
+If you add support for a new external API, please add a new integration test.
+
+**warning** Almost no tests should be integration tests.
+
+  Tests that require making network connections make it difficult for other
+  developers to test the code.
+
+  Instead favor relying on `responses` library and/or mock.patch to mock
+  requests using small fixtures.
+
+To install dependencies for integration tests:
+
+```bash
+poetry install --with test_integration
+```
+
+To run integration tests:
+
+```bash
+make integration_tests
+```
 
 ### Prepare
 
-This repository contains functional tests for several search engines and databases. The
-tests aim to verify the correct behavior of the engines and databases according to their
-specifications and requirements.
+The integration tests exercise several search engines and databases. The tests
+aim to verify the correct behavior of the engines and databases according to
+their specifications and requirements.
 
 To run some integration tests, such as tests located in
 `tests/integration_tests/vectorstores/`, you will need to install the following
@@ -15,14 +55,6 @@ software:
 - Docker
 - Python 3.8.1 or later
 
-We have optional group `test_integration` in the `pyproject.toml` file. This group
-should contain dependencies for the integration tests and can be installed using the
-command:
-
-```bash
-poetry install --with test_integration
-```
-
 Any new dependencies should be added by running:
 
 ```bash
@@ -70,4 +102,20 @@ pytest tests/integration_tests/vectorstores/test_elasticsearch.py --vcr-record=n
 pytest tests/integration_tests/vectorstores/test_elasticsearch.py --cov=langchain --cov-report=html
 start "" htmlcov/index.html || open htmlcov/index.html
 
-```
+```
+
+## Coverage
+
+Code coverage (i.e. the amount of code that is covered by unit tests) helps identify areas of the code that are potentially more or less brittle.
+
+Coverage requires the dependencies for integration tests:
+
+```bash
+poetry install --with test_integration
+```
+
+To get a report of current coverage, run the following:
+
+```bash
+make coverage
+```