diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bf15333d2..19881e97d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,47 +1,163 @@ # Contributing to Langflow -This guide is intended to help you get started contributing to Langflow. -As an open-source project in a rapidly developing field, we are extremely open -to contributions, whether it be in the form of a new feature, improved infra, or better documentation. +This guide is intended to help you start contributing to Langflow. +As an open-source project in a rapidly developing field, Langflow welcomes contributions, whether it be in the form of a new feature, improved infrastructure, or better documentation. -To contribute to this project, please follow the [fork and pull request](https://docs.github.com/en/get-started/quickstart/contributing-to-projects) workflow. +To contribute code or documentation to this project, follow the [fork and pull request](https://docs.github.com/en/get-started/quickstart/contributing-to-projects) workflow. -## Reporting bugs or suggesting improvements +## Install Langflow from source -Our [GitHub issues](https://github.com/langflow-ai/langflow/issues) page is kept up to date -with bugs, improvements, and feature requests. There is a taxonomy of labels to help -with sorting and discovery of issues of interest. [See this page](https://github.com/langflow-ai/langflow/labels) for an overview of -the system we use to tag our issues and pull requests. +Install Langflow from source by forking the repository, and then set up your development environment using Make. -If you're looking for help with your code, consider posting a question on the -[GitHub Discussions board](https://github.com/langflow-ai/langflow/discussions). Please -understand that we won't be able to provide individual support via email. We -also believe that help is much more valuable if it's **shared publicly**, -so that more people can benefit from it. +### Prerequisites -- **Describing your issue:** Try to provide as many details as possible. What - exactly goes wrong? _How_ is it failing? Is there an error? - "XY doesn't work" usually isn't that helpful for tracking down problems. Always - remember to include the code you ran and if possible, extract only the relevant - parts and don't just dump your entire script. This will make it easier for us to - reproduce the error. +* [uv](https://docs.astral.sh/uv/getting-started/installation/) version 0.4 or later +* [Node.js](https://nodejs.org/en/download/package-manager) +* [Make](https://www.gnu.org/software/make/#documentation) -- **Sharing long blocks of code or logs:** If you need to include long code, - logs or tracebacks, you can wrap them in `
` and `
`. This - [collapses the content](https://developer.mozilla.org/en/docs/Web/HTML/Element/details) - so it only becomes visible on click, making the issue easier to read and follow. +### Clone the Langflow repository -## Contributing code and documentation +1. Fork the [Langflow GitHub repository](https://github.com/langflow-ai/langflow). -You can develop Langflow locally and contribute to the Project! +2. Add the new remote to your local repository on your local machine: +```bash +git remote add FORK_NAME https://github.com/GIT_USERNAME/langflow.git +``` +Replace the following: +* `FORK_NAME`: A name for your fork of the repository +* `GIT_USERNAME`: Your Git username -See [DEVELOPMENT.md](DEVELOPMENT.md) for instructions on setting up and using a development environment. +### Run Langflow from source -## Opening a pull request +If you're not developing, but want to run Langflow from source after cloning the repo, run: -Once you wrote and manually tested your change, you can start sending the patch to the main repository. +```bash +make run_cli +``` -- Open a new GitHub pull request with the patch against the `main` branch. -- Ensure the PR title follows semantic commits conventions. - - For example, `feat: add new feature`, `fix: correct issue with X`. -- Ensure the PR description clearly describes the problem and solution. Include the relevant issue number if applicable. +This command: +- Installs frontend and backend dependencies +- Builds the frontend static files +- Starts the application with default settings + +The `make run_cli` command allows you to configure the application such as logging level, host, port, and environment variables. + +For example, this command starts Langflow with custom settings for the logging level, host binding, and port number, and specifies a custom `.env` file. + +```bash +make run_cli log_level=info host=localhost port=8000 env=.env.custom +``` + +The `make run_cli` command accepts the following parameters: + +| Parameter | Default | Description | +|-----------|---------|-------------| +| `log_level` | `debug` | Set the logging level. Options: `debug`, `info`, `warning`, `error`, `critical` | +| `host` | `0.0.0.0` | The host address to bind the server to. Use `localhost` or `127.0.0.1` for local-only access. | +| `port` | `7860` | The port number to run the server on. | +| `env` | `.env` | Path to the environment file containing configuration variables. | +| `open_browser` | `true` | Whether to automatically open the browser when starting. Set to `false` to disable. | + +### Set up your Langflow development environment + +1. To set up the Langflow development environment, run the following command: + +```bash +make init +``` + +This command sets up the development environment by: +- Checking for uv and npm. +- Installing backend and frontend dependencies. +- Installing pre-commit hooks. + +2. Run the backend and frontend in separate terminals for development: + +```bash +# Run backend in development mode (includes hot reload) +make backend + +# In another terminal, run frontend in development mode (includes hot reload) +make frontend +``` + +The `make backend` and `make frontend` commands automatically install dependencies, so you don't need to run install commands separately. + +3. (Optional) Install pre-commit hooks to help keep your changes clean and well-formatted. `make init` installs pre-commit hooks automatically. + +```bash +uv sync +uv run pre-commit install +``` + +:::note +With pre-commit hooks installed, you need to use `uv run git commit` instead of `git commit` directly. +::: + +4. To test your changes, run `make lint`, `make format`, and `make unit_tests` before pushing to the repository. +To run all tests, including unit tests, integration tests, and coverage, run `make tests`. + +### Debug + +The repo includes a `.vscode/launch.json` file for debugging the backend in VSCode, which is faster than debugging with Docker Compose. To debug Langflow with the `launch.json` file in VSCode: + +For more information, see the [VSCode documentation](https://code.visualstudio.com/docs/debugtest/debugging#_start-a-debugging-session). + +### Additional contribution guides + +- [Contribute Bundles](./docs/docs/Contributing/contributing-bundles.md) +- [Contribute Components](./docs/docs/Contributing/contributing-components.md) +- [Contribute Tests](./docs/docs/Contributing/contributing-component-tests.md) +- [Contribute Templates](./docs/docs/Contributing/contributing-templates.md) + +## Contribute documentation + +The documentation is built using [Docusaurus](https://docusaurus.io/) and written in [Markdown](https://docusaurus.io/docs/markdown-features). +Contributions should follow the [Google Developer Documentation Style Guide](https://developers.google.com/style). + +### Prerequisites + +* [Node.js](https://nodejs.org/en/download/package-manager) +* [Yarn](https://yarnpkg.com/) + +### Clone the Langflow repository + +1. Fork the [Langflow GitHub repository](https://github.com/langflow-ai/langflow). + +2. Add the new remote to your local repository on your local machine: +```bash +git remote add FORK_NAME https://github.com/GIT_USERNAME/langflow.git +``` +Replace the following: +* `FORK_NAME`: A name for your fork of the repository +* `GIT_USERNAME`: Your Git username + +3. From your Langflow fork's root, change directory to the `langflow/docs` folder with the following command: +```bash +cd docs +``` + +4. To install dependencies and start a local Docusaurus static site with hot reloading, run: +```bash +yarn install && yarn start +``` + +The documentation will be available at `localhost:3000` and all the files are located in the `/docs` folder. + +5. Optional: Run `yarn build` to build the site locally and ensure there are no broken links. + +## Open a pull request + +To submit a pull request, do the following: + +1. Open a new GitHub pull request with your patch against the `main` branch. +2. Ensure the PR title follows semantic commit conventions. For example, features are `feat: add new feature` and fixes are `fix: correct issue with X`. + +Some additional guidance on pull request titles: +* Ensure the pull request description clearly describes the problem and solution. If the PR fixes an issue, include a link to the fixed issue in the PR description with `Fixes #1234`. +* Pull request titles appear in Langflow's release notes, so they should explain what the PR does as explicitly as possible. +* Pull requests should strive to fix one thing **only**, and should contain a good description of what is being fixed. + +3. A Langflow maintainer will review your pull request and may request changes, so ensure you pay attention to your PRs. Thanks for your contribution! + +For more information, see the [Python Developer's Guide](https://devguide.python.org/getting-started/pull-request-lifecycle/index.html#making-good-commits). \ No newline at end of file diff --git a/docs/docs/Contributing/contributing-how-to-contribute.md b/docs/docs/Contributing/contributing-how-to-contribute.md index 7d265677a..9529a9477 100644 --- a/docs/docs/Contributing/contributing-how-to-contribute.md +++ b/docs/docs/Contributing/contributing-how-to-contribute.md @@ -8,115 +8,159 @@ As an open-source project in a rapidly developing field, Langflow welcomes contr To contribute code or documentation to this project, follow the [fork and pull request](https://docs.github.com/en/get-started/quickstart/contributing-to-projects) workflow. -## Contribute code +## Install Langflow from source -Develop Langflow locally with [uv](https://docs.astral.sh/uv/getting-started/installation/) and [Node.js](https://nodejs.org/en/download/package-manager). +Install Langflow from source by forking the repository, and then set up your development environment using Make. ### Prerequisites -* [uv(>=0.4)](https://docs.astral.sh/uv/getting-started/installation/) +* [uv](https://docs.astral.sh/uv/getting-started/installation/) version 0.4 or later * [Node.js](https://nodejs.org/en/download/package-manager) +* [Make](https://www.gnu.org/software/make/#documentation) -### Clone the Langflow Repository +### Clone the Langflow repository -1. Navigate to the [Langflow GitHub repository](https://github.com/langflow-ai/langflow), and then click **Fork**. +1. Fork the [Langflow GitHub repository](https://github.com/langflow-ai/langflow). 2. Add the new remote to your local repository on your local machine: -Replace `YOUR_FORK_NAME` with a name for your fork. -Replace `YOUR_GIT_USERNAME` with your Git username. ```bash -git remote add YOUR_FORK_NAME https://github.com/YOUR_GIT_USERNAME/langflow.git +git remote add FORK_NAME https://github.com/GIT_USERNAME/langflow.git +``` +Replace the following: +* `FORK_NAME`: A name for your fork of the repository +* `GIT_USERNAME`: Your Git username + +### Run Langflow from source + +If you're not developing, but want to run Langflow from source after cloning the repo, run: + +```bash +make run_cli ``` -### Prepare the development environment +This command: +- Installs frontend and backend dependencies +- Builds the frontend static files +- Starts the application with default settings -1. Create development hooks. +The `make run_cli` command allows you to configure the application such as logging level, host, port, and environment variables. + +For example, this command starts Langflow with custom settings for the logging level, host binding, and port number, and specifies a custom `.env` file. + +```bash +make run_cli log_level=info host=localhost port=8000 env=.env.custom +``` + +The `make run_cli` command accepts the following parameters: + +| Parameter | Default | Description | +|-----------|---------|-------------| +| `log_level` | `debug` | Set the logging level. Options: `debug`, `info`, `warning`, `error`, `critical` | +| `host` | `0.0.0.0` | The host address to bind the server to. Use `localhost` or `127.0.0.1` for local-only access. | +| `port` | `7860` | The port number to run the server on. | +| `env` | `.env` | Path to the environment file containing configuration variables. | +| `open_browser` | `true` | Whether to automatically open the browser when starting. Set to `false` to disable. | + +### Set up your Langflow development environment + +1. To set up the Langflow development environment, run the following command: ```bash make init ``` -This command sets up the development environment by installing backend and frontend dependencies, building the frontend static files, and initializing the project. It runs `make install_backend`, `make install_frontend`, `make build_frontend`, and finally `uv run langflow run` to start the application. +This command sets up the development environment by: +- Checking for uv and npm. +- Installing backend and frontend dependencies. +- Installing pre-commit hooks. -2. Run `make lint`, `make format`, and `make unit_tests` before pushing to the repository. +2. Run the backend and frontend in separate terminals for development: + +```bash +# Run backend in development mode (includes hot reload) +make backend + +# In another terminal, run frontend in development mode (includes hot reload) +make frontend +``` + +The `make backend` and `make frontend` commands automatically install dependencies, so you don't need to run install commands separately. + +3. (Optional) Install pre-commit hooks to help keep your changes clean and well-formatted. `make init` installs pre-commit hooks automatically. + +```bash +uv sync +uv run pre-commit install +``` + +:::note +With pre-commit hooks installed, you need to use `uv run git commit` instead of `git commit` directly. +::: + +4. To test your changes, run `make lint`, `make format`, and `make unit_tests` before pushing to the repository. +To run all tests, including unit tests, integration tests, and coverage, run `make tests`. ### Debug The repo includes a `.vscode/launch.json` file for debugging the backend in VSCode, which is faster than debugging with Docker Compose. To debug Langflow with the `launch.json` file in VSCode: -1. Open Langflow in VSCode. -2. Press **Ctrl+Shift+D** for Windows **or Cmd+Shift+D** for Mac to open the Run and Debug view. -3. From the **Run and Debug** dropdown, choose a debugging configuration. -4. Click the green **Play** button or press F5 to start debugging. +For more information, see the [VSCode documentation](https://code.visualstudio.com/docs/debugtest/debugging#_start-a-debugging-session). -Use `launch.json` to quickly debug different parts of your application, like the backend, frontend, or CLI, directly from VSCode. +### Additional contribution guides -### Run Langflow locally - -After setting up the environment with `make init`, you can run Langflow's backend and frontend separately for development. - -Before you begin, ensure you have [uv](https://docs.astral.sh/uv/getting-started/installation/) and [Node.js](https://nodejs.org/en/download/package-manager) installed. - -1. In the repository root, install the dependencies and start the development server for the backend: - -```bash -make backend -``` - -2. Install dependencies and start the frontend: - -```bash -make frontend -``` - -This approach allows you to work on the backend and frontend independently, with hot-reloading for faster development. +- [Contribute Bundles](./contributing-bundles.md) +- [Contribute Components](./contributing-components.md) +- [Contribute Tests](./contributing-component-tests.md) +- [Contribute Templates](./contributing-templates.md) ## Contribute documentation The documentation is built using [Docusaurus](https://docusaurus.io/) and written in [Markdown](https://docusaurus.io/docs/markdown-features). +Contributions should follow the [Google Developer Documentation Style Guide](https://developers.google.com/style). ### Prerequisites * [Node.js](https://nodejs.org/en/download/package-manager) +* [Yarn](https://yarnpkg.com/) ### Clone the Langflow repository -1. Navigate to the [Langflow GitHub repository](https://github.com/langflow-ai/langflow), and then click **Fork**. +1. Fork the [Langflow GitHub repository](https://github.com/langflow-ai/langflow). 2. Add the new remote to your local repository on your local machine: - ```bash -git remote add fork https://github.com//langflow.git +git remote add FORK_NAME https://github.com/GIT_USERNAME/langflow.git ``` +Replace the following: +* `FORK_NAME`: A name for your fork of the repository +* `GIT_USERNAME`: Your Git username -3. To run the documentation locally, run the following commands: - +3. From your Langflow fork's root, change directory to the `langflow/docs` folder with the following command: ```bash cd docs -yarn install -yarn start ``` -The documentation will be available at `localhost:3000` and all the files are located in the `docs/docs` folder. +4. To install dependencies and start a local Docusaurus static site with hot reloading, run: +```bash +yarn install && yarn start +``` + +The documentation will be available at `localhost:3000` and all the files are located in the `/docs` folder. + +5. Optional: Run `yarn build` to build the site locally and ensure there are no broken links. ## Open a pull request -Once you have written and manually tested your changes with `make lint` and `make unit_tests`, open a pull request to send your changes upstream to the main Langflow repository. +To submit a pull request, do the following: 1. Open a new GitHub pull request with your patch against the `main` branch. 2. Ensure the PR title follows semantic commit conventions. For example, features are `feat: add new feature` and fixes are `fix: correct issue with X`. -3. A Langflow maintainer will review your pull request. Thanks for your contribution! Some additional guidance on pull request titles: * Ensure the pull request description clearly describes the problem and solution. If the PR fixes an issue, include a link to the fixed issue in the PR description with `Fixes #1234`. * Pull request titles appear in Langflow's release notes, so they should explain what the PR does as explicitly as possible. * Pull requests should strive to fix one thing **only**, and should contain a good description of what is being fixed. -For more information, see the [Python Developer's Guide](https://devguide.python.org/getting-started/pull-request-lifecycle/index.html#making-good-commits). +3. A Langflow maintainer will review your pull request and may request changes, so ensure you pay attention to your PRs. Thanks for your contribution! -## Additional contribution guides - -- [Contribute Bundles](./contributing-bundles.md) -- [Contribute Components](./contributing-components.md) -- [Contribute Tests](./contributing-component-tests.md) -- [Contribute Templates](./contributing-templates.md) \ No newline at end of file +For more information, see the [Python Developer's Guide](https://devguide.python.org/getting-started/pull-request-lifecycle/index.html#making-good-commits). \ No newline at end of file diff --git a/docs/docs/Get-Started/get-started-installation.md b/docs/docs/Get-Started/get-started-installation.md index 5912d76d9..6ff7861d2 100644 --- a/docs/docs/Get-Started/get-started-installation.md +++ b/docs/docs/Get-Started/get-started-installation.md @@ -129,6 +129,10 @@ It can take a few minutes for Langflow to start. After confirming that Langflow is running, create your first flow with the [Quickstart](/get-started-quickstart). +### Install Langflow from source + +To install Langflow from source, see [Install Langflow from source](/contributing-how-to-contribute#install-langflow-from-source). + ### Manage Langflow OSS versions :::important