Contributing to ByteChef

Thanks for taking the time to contribute to ByteChef! We're a very welcoming community and while it's very much appreciated if you follow these guidelines it's not a requirement.

How can I contribute?

There are many ways in which you can contribute to ByteChef.

Report a bug

Report all issues through GitHub Issues using the Report a Bug template. To help resolve your issue as quickly as possible, read the template and provide all the requested information.

File a feature/component request

We welcome all feature requests, whether it's to add new functionality, improve existing connectors or to suggest a brand new connector. File your feature request through GitHub Issues using the Feature Request template for improvements or Connector Request for improvements to the existing components or for the new ones.

Improve the documentation

You can help by suggesting improvements to our documentation using the Documentation Improvement template or check Step-by-step guide to contributing!

Close a Bug / Feature issue

Find issues where we need help. Search for issues with either good first issue and/or help wanted labels. Check out the following Code Contribution Guide to begin.

Contributing Code Changes

Please review the following sections before proposing code changes.

License

By contributing, you agree that your contributions will be licensed under the terms of the ByteChef project licenses.

Code of Conduct

This project and everyone participating in it is governed by the ByteChef Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to support@bytechef.io.

Step-by-step guide to contributing

We Use GitHub Flow, So All Code Changes Happen Through Pull Requests

Pull requests are the best way to propose changes to the codebase (we use Git-Flow). We actively welcome your pull requests:

Fork the repo and create a new branch from the develop branch.
Branches are named as issue_number-issue_name
If you're working on the client codebase, go through Client Side. If you're working on the server codebase, go through Server Side. If you're working on the documentation, go through Documentation
Once you are confident in your code changes, create a pull request in your fork to the develop branch in the bytechefhq/bytechef base repository.
If you've changed any APIs, please mention it in the pull request and ensure backward compatibility.
Link the issue of the base repository in your Pull request description. Guide
When you raise a pull request, we automatically run tests on our CI. Please ensure that all the tests are passing for your code change. We will not be able to accept your change if the test suite doesn't pass.

Client Side

Run locally. Code is located in BYTECHEF_HOME/client.
Add your changes.
Please add tests for your changes. Client-side changes require Vitest/Playwright tests.
When you finish adding your changes, run format and check inside the client directory:
```
./npm run format
./npm run check
```
If there are no errors, you can continue through the steps.

Server Side

Run locally. Code is located in BYTECHEF_HOME/server. Components are located at BYTECHEF_HOME/server/libs/modules/components.
Add your changes. If you are adding a component, you can do that Manually or with a Connector Genarator
Please add tests for your changes. Server-side changes require JUnit/Integration tests.
If you are working on a component, you need to (re)generate the .json file. The .json file is located in ./src/test/resources/definition/.json. If such file exists, you have to delete it. Open a file located in ./src/test/java/com/bytechef/component/... that ends with the postfix ComponentHandlerTest. By running all tests if that file, the new .json file will be automatically generated. Running it when a .json file already exists will check if the autogenerated file matches the current one.
When you finish adding your changes, run spotlessApply and check inside the server directory or in the root directory of your component (if you worked on a component):
```
./gradlew spotlessApply
./gradlew check
```
If there are no errors, you can continue through the steps.

Documentation

Documentation is located in BYTECHEF_HOME/docs. To run it, you need to run the commands below from the folder:
```
./npm install
./npm run dev
```
If you are documenting a component, they are located at BYTECHEF_HOME/server/libs/modules/components.
- If a README.md file doesn't exist in BYTECHEF_HOME/server/libs/modules/components/component_name/src/main/resources, you need to create it.
- run generateDocumentation when you're done. Everything in the README.md will be appended at the end of that components' documentation.
Add your changes.

Setup ByteChef platform for local development and testing

ByteChef platform consists of three major parts. User interface is implemented with Node, ReactJS and TypeScript. Backend microservices are implemented in Java programming language and Spring framework. Dependent infrastructure PostgreSQL, RabbitMQ, Redis. Each part could be encapsulated in Docker container to reduce efforts.

How to run platform

Prerequisites

Docker
Java - GraalVM for JDK 21.0.2+
Gradle - V8.5+. - Comes as part of the project as Gradle Wrapper
Node v20+

Run from command line

Open terminal application.
Make sure java -version and JAVA_HOME references Java JDK 21+
Clone the ByteChef repository to local directory. For the purposes of this guide, will call it BYTECHEF_HOME.
```
git clone https://github.com/bytechefhq/bytechef.git
cd bytechef
```
Change working directory to the BYTECHEF_HOME/server folder.
Start up the docker container with dependent infrastructure
```
docker compose -f docker-compose.dev.infra.yml up -d
```
Compile codebase:
```
../gradlew clean compileJava
```
Start the ByteChef server instance by running:
```
../gradlew -p apps/server-app bootRun
```
Change working directory to the BYTECHEF_HOME/client folder.
Install dependencies.
```
npm install
```
Serve with hot reload.
```
npm run dev
```

Note:

User interface application connects to the microservices server at the predefined URL http://127.0.0.1:9555. If microservices backend API server is not present, your page will load with errors. The API server starts on default port 9555. To configure the API server in details, please follow Setup With docker instructions. The API server status is available at the endpoint: http://localhost:9555/swagger-ui/index.html. Type it in the browser's address bar to get Swagger UI with the list of API endpoints.

If ran for the first time the API server automatically populate database with required data and demo projects. Subsequent runs against existing database would trigger table updates on PostgreSQL.

Backend Microservices Developemnt Tasks

This section explains how you can set up a development environment for ByteChef server instance. As the server codebase is written in Java and is powered by Spring, you need Java and Gradle installed to build the code. You also need one instance of PostgreSQL and Redis each to run ByteChef server instance.

Local Setup

This section doesn't provide instructions to install Java and Gradle because these vary between different operating systems and distributions. Please refer to the documentation of your operating system or package manager to install these tools.

Steps for setup

Setting up local development infrastructure using Docker

Use docker-compose.dev.infra.yml for running required infrastructure (PostgreSQL, Redis):

docker compose -f docker-compose.dev.infra.yml up -d

Rebuild a docker image of the locally built server instance.

docker compose -f docker-compose.dev.server.yml down --rmi local
docker compose -f docker-compose.dev.server.yml up -d

Server Development tasks

Running Spotless Apply

This will source format your code so that it passes check. Running it in the module you worked on (example: BYTECHEF_HOME/server/libs/modules/components/logger) will only format the module you worked on. This will make it run slightly faster. It is recommended to run this command from the root when working on components.

./gradlew spotlessApply

Running Gradle Check

This will check run multiple sonars, tests and check source formatting. Before pushing, this needs to build successfully. Running it in the module you worked on (example: BYTECHEF_HOME/server/libs/modules/components/logger) will only check the module you worked on. This will make it run a lot faster. For this reason it is recommended to run check on only the modules you worked on if possible.

./gradlew check

Running Tests

This will run tests and integration tests. Before pushing, all tests need to pass successfully.

./gradlew test && ./gradlew testIntegration

Generating Documentation

This will autogenerate documentation for all components and flows. Running it in the module you worked on (example: BYTECHEF_HOME/server/libs/modules/components/logger) will only autogenerate documentation for the module you worked on. This will make it run slightly faster.

./gradlew generateDocumentation

Client Development tasks

Running Source Formatting

npm run format

Running Lint

npm run lint

Running Typecheck

npm run typecheck

Running Check

npm run check

Running Build

npm run build

Running Tests

npm run test

Initial login credentials:

username: admin@localhost.com
- password: admin
username: user@localhost.com
- password: user

Troubleshooting

Turn antiviruses off

Sometimes gradle won't run any tasks because an antivirus is preventing it from writing in your temporary files. It is mostly a Windows related problem.

Check your ports

Docker is listening to ports 5432, 6397 and 1025 for its services. If you have any other services listening on those ports, you have to turn them off.

To check which ports you are listening to, type:

sudo lsof -i -P -n | grep LISTEN

If you have Postgres, Redis or Mailhog installed locally, and they are listening to one of those ports, you should either uninstall them or change the ports they are listening to.

Out of date schema

If you see Either revert the changes to the migration, or run repair to update the schema history in the terminal log when starting the server, execute the following command which will remove the out of date schemas:

For server setup with Docker:

docker compose -f server/docker-compose.dev.server.yml down -v

For server local setup:

docker compose -f server/docker-compose.dev.infra.yml down -v

spotlessApply generates unwanted files

If you ran our source formatting for java code (./gradlew spotlessApply) and a bunch of files were generated, it might be your git configuration.

Run git config --list --local in your command line. If core.filemode is true, set it to false:

git config core.filemode false

If you are using windows, you need to switch LF endings to CRLF endings:

git config core.autocrlf true

"File name too long" / "Clone succeeded but checkout failed"

git config --system core.longpaths true

Questions?

Contact us on Discord or mail us at support@bytechef.io.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly