Skip to content

Commit

Permalink
Docs: Contributing folder (#4415)
Browse files Browse the repository at this point in the history 
* issues

* contributing

* telemetry-cleanup

* name

* name

* pr-guidance

* Apply suggestions from code review

Co-authored-by: KimberlyFields <[email protected]>

* code-review

* move-discussions

* have-written

* why-to-run-locally

* clarify-how-to-contribute

* add-custom-component-page

* Apply suggestions from code review

Co-authored-by: KimberlyFields <[email protected]>

* update-join-the-community-age

---------

Co-authored-by: KimberlyFields <[email protected]>
  • Loading branch information
@mendonk @KimberlyFields
mendonk and KimberlyFields authored Nov 12, 2024
1 parent ab71e2f commit bcd7617
Show file tree
Hide file tree
Showing 6 changed files with 123 additions and 193 deletions.
48 changes: 11 additions & 37 deletions docs/docs/Contributing/contributing-community.md
View file
Original file line number Diff line number Diff line change
@@ -1,52 +1,26 @@
---
title: Community
sidebar_position: 3
title: Join the Langflow community
sidebar_position: 5
slug: /contributing-community
---



## 🤖 Join **Langflow** Discord server {#80011e0bda004e83a8012c7ec6eab29a}
## Join the Langflow Discord server

Join the [Langflow Discord Server](https://discord.gg/EqksyE2EX9) to ask questions and showcase your projects.

---


Join us to ask questions and showcase your projects.


Let's bring together the building blocks of AI integration!


Langflow [Discord](https://discord.gg/EqksyE2EX9) server.


## 🐦 Stay tuned for **Langflow** on Twitter {#6a17ba5905ad4f7aa5347af7854779f6}


---
## Follow Langflow on X

Follow [@langflow_ai](https://twitter.com/langflow_ai) on X to get the latest news about Langflow.

Follow [@langflow_ai](https://twitter.com/langflow_ai) on **Twitter** to get the latest news about **Langflow**.
## Star Langflow on GitHub

You can [star Langflow in GitHub](https://github.com/langflow-ai/langflow).

## ⭐️ Star **Langflow** on GitHub {#c903a569934643799bf52b7d1b3514e1}


---


You can "star" **Langflow** in [GitHub](https://github.com/langflow-ai/langflow).


By adding a star, other users will be able to find it more easily and see that it has been already useful for others.


## 👀 Watch the GitHub repository for releases {#d0a089ed717742308bd17430e5ae6309}


---
By adding a star, other users will be able to find Langflow more easily, and see that it has been already useful for others.

## Watch the GitHub repository for releases

You can "watch" **Langflow** in [GitHub](https://github.com/langflow-ai/langflow). If you select "Watching" instead of "Releases only" you will receive notifications when someone creates a new issue or question. You can also specify that you only want to be notified about new issues, discussions, PRs, etc. so you can try and help them solve those questions.
You can [watch Langflow in GitHub](https://github.com/langflow-ai/langflow). If you select **Watching** instead of **Releases only** you will receive notifications when someone creates a new issue or question. You can also specify that you want to be notified only about new issues, discussions, and PRs so you can try to help solve those issues.

24 changes: 24 additions & 0 deletions docs/docs/Contributing/contributing-components.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
---
title: Contribute components
sidebar_position: 4
slug: /contributing-components
---


New components are added as objects of the [CustomComponent](https://github.com/langflow-ai/langflow/blob/dev/src/backend/base/langflow/custom/custom_component/custom_component.py) class.

Any dependencies are added to the [pyproject.toml](https://github.com/langflow-ai/langflow/blob/main/pyproject.toml#L148) file.

### Contribute an example component to Langflow

Anyone can contribute an example component. For example, if you created a new document loader called **MyCustomDocumentLoader**, you can follow these steps to contribute it to Langflow.

1. Write your loader as an object of the [CustomComponent](https://github.com/langflow-ai/langflow/blob/dev/src/backend/base/langflow/custom/custom_component/custom_component.py) class. You'll create a new class, `MyCustomDocumentLoader`, that will inherit from `CustomComponent` and override the base class's methods.
2. Define optional attributes like `display_name`, `description`, and `documentation` to provide information about your custom component.
3. Implement the `build_config` method to define the configuration options for your custom component.
4. Implement the `build` method to define the logic for taking input parameters specified in the `build_config` method and returning the desired output.
5. Add the code to the [/components/documentloaders](https://github.com/langflow-ai/langflow/tree/dev/src/backend/base/langflow/components) folder.
6. Add the dependency to [/documentloaders/__init__.py](https://github.com/langflow-ai/langflow/blob/dev/src/backend/base/langflow/components/documentloaders/__init__.py) as `from .MyCustomDocumentLoader import MyCustomDocumentLoader`.
7. Add any new dependencies to the [pyproject.toml](https://github.com/langflow-ai/langflow/blob/main/pyproject.toml#L148) file.
8. Submit documentation for your component. For this example, you'd submit documentation to the [loaders page](https://github.com/langflow-ai/langflow/blob/main/docs/docs/Components/components-loaders.md).
9. Submit your changes as a pull request. The Langflow team will have a look, suggest changes, and add your component to Langflow.
13 changes: 13 additions & 0 deletions docs/docs/Contributing/contributing-github-discussion-board.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
---
title: Ask for help on the Discussions board
sidebar_position: 3
slug: /contributing-github-discussions
---

If you're looking for help with your code, consider posting a question on the Langflow [GitHub Discussions board](https://github.com/langflow-ai/langflow/discussions). The Langflow team cannot provide individual support via email. The team also believes that help is much more valuable if it's shared publicly, so that more people can benefit from it.

Since the Discussions board is public, please follow this guidance when posting your code questions.

* When 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.

* When you include long code, logs, or tracebacks, wrap them in `<details>` and `</details>` tags. This [collapses the content](https://developer.mozilla.org/en/docs/Web/HTML/Element/details) so the contents only becomes visible on click, making the issue easier to read and follow.
21 changes: 2 additions & 19 deletions docs/docs/Contributing/contributing-github-issues.md
View file
Original file line number Diff line number Diff line change
@@ -1,24 +1,7 @@
---
title: GitHub Issues
title: Request an enhancement or report a bug
sidebar_position: 2
slug: /contributing-github-issues
---



Our [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.


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.

- **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.
- **Sharing long blocks of code or logs:** If you need to include long code, logs or tracebacks, you can wrap them in `<details>` and `</details>`. 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.

## Issue labels {#e19eae656c914ce7aedc4f55565cc0bc}


---


[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.

The [Issues page in the Langflow repo](https://github.com/langflow-ai/langflow/issues) is kept up to date with bugs, improvements, and feature requests. Labels are used to help with sorting and discovery of issues of interest. For an overview of the system Langflow uses to tag issues and pull requests, see the Langflow repo's [labels page](https://github.com/langflow-ai/langflow/labels).
182 changes: 69 additions & 113 deletions docs/docs/Contributing/contributing-how-to-contribute.md
View file
Original file line number Diff line number Diff line change
@@ -1,160 +1,116 @@
---
title: How to contribute?
title: Contribute to Langflow
sidebar_position: 1
slug: /contributing-how-to-contribute
---

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 code or documentation to this project, follow the [fork and pull request](https://docs.github.com/en/get-started/quickstart/contributing-to-projects) workflow.

:::info
## Contribute code

This page may contain outdated information. It will be updated as soon as possible.
Develop Langflow locally with [uv](https://docs.astral.sh/uv/getting-started/installation/) and [Node.js](https://nodejs.org/en/download/package-manager).

:::
### Prerequisites

* [uv(>=0.4)](https://docs.astral.sh/uv/getting-started/installation/)
* [Node.js](https://nodejs.org/en/download/package-manager)

### Clone the Langflow Repository

1. Navigate to the [Langflow GitHub repository](https://github.com/langflow-ai/langflow), and then click **Fork**.

👋 Hello there!
2. Add the new remote to your local repository on your local machine:

We welcome contributions from developers of all levels to our open-source project on [GitHub](https://github.com/langflow-ai/langflow). If you'd like to contribute, please check our contributing guidelines and help make Langflow more accessible.
```bash
git remote add fork https://github.com/<your_git_username>/langflow.git
```

### Prepare the development environment

1. Create development hooks.

As an open-source project in a rapidly developing field, we are extremely open to contributions, whether in the form of a new feature, improved infra, or better documentation.
```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.

2. Run `make lint`, `make format`, and `make unit_tests` before pushing to the repository.

To contribute to this project, please follow a ["fork and pull request"](https://docs.github.com/en/get-started/quickstart/contributing-to-projects) workflow. Please do not try to push directly to this repo unless you are a maintainer.
### 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:

## Local Development {#0388cc3c758d434d994022863a6bafa9}
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.

Use `launch.json` to quickly debug different parts of your application, like the backend, frontend, or CLI, directly from VSCode.

---


You can develop Langflow using docker compose, or locally.


We provide a `.vscode/launch.json` file for debugging the backend in VSCode, which is a lot faster than using docker compose.


Setting up hooks:


`make init`


This will install the pre-commit hooks, which will run `make format` on every commit.


It is advised to run `make lint` before pushing to the repository.


## Run Locally {#5225c2ef0cd6403c9f6c6bbd888115e0}


---


Langflow can run locally by cloning the repository and installing the dependencies. We recommend using a virtual environment to isolate the dependencies from your system.


Before you start, make sure you have the following installed:

- Poetry (&gt;=1.4)
- Node.js

Then, in the root folder, install the dependencies and start the development server for the backend:


`make backend`


And the frontend:


`make frontend`
### Run Langflow locally

After setting up the environment with `make init`, you can run Langflow's backend and frontend separately for development.
Langflow recommends using a virtual environment like [venv](https://docs.python.org/3/library/venv.html) or [conda](https://anaconda.org/anaconda/conda) to isolate dependencies.

## Docker Compose {#b07f359414ff4220ac615afc364ee46e}
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:

---


The following snippet will run the backend and frontend in separate containers. The frontend will be available at `localhost:3000` and the backend at `localhost:7860`.


`docker compose up --build# ormake dev build=1`


## Documentation {#5f34bcaeccdc4489b0c5ee2c4a21354e}


---


The documentation is built using [Docusaurus](https://docusaurus.io/). To run the documentation locally, run the following commands:


`cd docsnpm installnpm run start`

```bash
make backend
```

The documentation will be available at `localhost:3000` and all the files are located in the `docs/docs` folder. Once you are done with your changes, you can create a Pull Request to the `main` branch.
2. Install dependencies and start the frontend:

```bash
make frontend
```

## Submitting Components {#9676353bc4504551a4014dd572ac8be8}


---


New components are added as objects of the [CustomComponent](https://github.com/langflow-ai/langflow/blob/dev/src/backend/base/langflow/interface/custom/custom_component/custom_component.py) class and any dependencies are added to the [pyproject.toml](https://github.com/langflow-ai/langflow/blob/dev/pyproject.toml#L27) file.


### Add an example component {#8caae106c853465d83183e7f5272e4d8}


You have a new document loader called **MyCustomDocumentLoader** and it would look awesome in Langflow.

1. Write your loader as an object of the [CustomComponent](https://github.com/langflow-ai/langflow/blob/dev/src/backend/base/langflow/interface/custom/custom_component/custom_component.py) class. You'll create a new class, `MyCustomDocumentLoader`, that will inherit from `CustomComponent` and override the base class's methods.
2. Define optional attributes like `display_name`, `description`, and `documentation` to provide information about your custom component.
3. Implement the `build_config` method to define the configuration options for your custom component.
4. Implement the `build` method to define the logic for taking input parameters specified in the `build_config` method and returning the desired output.
5. Add the code to the [/components/documentloaders](https://github.com/langflow-ai/langflow/tree/dev/src/backend/base/langflow/components) folder.
6. Add the dependency to [/documentloaders/__init__.py](https://github.com/langflow-ai/langflow/blob/dev/src/backend/base/langflow/components/documentloaders/__init__.py) as `from .MyCustomDocumentLoader import MyCustomDocumentLoader`.
7. Add any new dependencies to the outer [pyproject.toml](https://github.com/langflow-ai/langflow/blob/dev/pyproject.toml#L27) file.
8. Submit documentation for your component. For this example, you'd submit documentation to the [loaders page](https://github.com/langflow-ai/langflow/blob/dev/docs/docs/components/loaders).
9. Submit your changes as a pull request. The Langflow team will have a look, suggest changes, and add your component to Langflow.

## User Sharing {#34ac32e11f344eab892b94531a21d2c9}


---

This approach allows you to work on the backend and frontend independently, with hot-reloading for faster development.

You might want to share and test your custom component with others, but don't need it merged into the main source code.
## Contribute documentation

The documentation is built using [Docusaurus](https://docusaurus.io/) and written in [Markdown](https://docusaurus.io/docs/markdown-features).

If so, you can share your component on the Langflow store.
### Prerequisites

* [Node.js](https://nodejs.org/en/download/package-manager)

1. [Register at the Langflow store](https://www.langflow.store/login/).
### Clone the Langflow repository

1. Navigate to the [Langflow GitHub repository](https://github.com/langflow-ai/langflow), and then click **Fork**.

2. Undergo pre-validation before receiving an API key.
2. Add the new remote to your local repository on your local machine:

```bash
git remote add fork https://github.com/<your_git_username>/langflow.git
```

3. To deploy your amazing component directly to the Langflow store, without it being merged into the main source code, navigate to your flow, and then click **Share**. The share window appears:
3. To run the documentation locally, run the following commands:

```bash
cd docs
npm install
npm run start
```

![](./683296796.png)
The documentation will be available at `localhost:3000` and all the files are located in the `docs/docs` folder.

## Open a pull request

4. Choose whether you want to flow to be public or private. You can also **Export** your flow as a JSON file from this window. When you're ready to share the flow, click **Share Flow**. You should see a **Flow shared successfully** popup.
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.

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!

5. To confirm, navigate to the **Langflow Store** and filter results by **Created By Me**. You should see your new flow on the **Langflow Store**.
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).
Loading

0 comments on commit bcd7617

Please sign in to comment.