Skip to content

Latest commit

 

History

History
234 lines (165 loc) · 10.8 KB

CONTRIBUTING.md

File metadata and controls

234 lines (165 loc) · 10.8 KB
Raw

Contributing to ByteChef

Thanks for taking the time for contribution to ByteChef! We're 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 [email protected].

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:

  1. Fork the repo and create a new branch from the develop branch.
  2. Branches are named as bug/fix-name or feature/feature-name
  3. To work on the client codebase, go through Client Side and Setup with Docker
  4. To work on the server codebase, go through Server Side and Local Setup
  5. Please add tests for your changes. Client-side changes require Vitest/Playwright tests while server-side changes require JUnit/Integration tests.
  6. When you finish adding your changes, run the following commands inside the client directory if you worked on the client codebase: 
    ./npm run format
./npm run check
    and/or inside the server directory if you worked on the server codebase: 
    ./gradlew spotlessApply
./gradlew check
  7. 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.
  8. If you've changed any APIs, please call this out in the pull request and ensure backward compatibility.
  9. Link the issue of the base repository in your Pull request description. Guide
  10. 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.
  11. Documentation: When new features are added or there are changes to existing features that require updates to documentation, we encourage you to add/update any missing documentation in the /docs folder. To update an existing documentation page, you can simply click on the Edit this page button on the bottom left corner of the documentation page.

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

Run from command line

  1. Open terminal application.

  2. Make sure java -version and JAVA_HOME references Java JDK 21+

  3. Clone the ByteChef repository to local directory we will call BYTECHEF_HOME.

    git clone https://github.com/bytechefhq/bytechef.git
cd bytechef

  4. Change working directory to the BYTECHEF_HOME/server folder.

  5. Start up the docker container with dependent infrastructure

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

  6. Compile codebase:

    ../gradlew clean compileJava

  7. Change working directory to the BYTECHEF_HOME/server/apps/server-app folder.

  8. Start the ByteChef server instance by running:

    ../../../gradlew bootRun

  9. Change working directory to the BYTECHEF_HOME/client folder.

  10. Install dependencies.

    npm install

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

User Interface 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

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.

Setup with Docker

Build and run the server codebase in a Docker container. This is the easiest way to get the server instance up and running if you are more interested in contributing to the client codebase.

Other useful Commands

Stop locally built server instance.

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

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

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

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

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

Running Source Formatting for Java Code

./gradlew spotlessApply

Running Check

./gradlew check

Running Tests

./gradlew test && ./gradlew testIntegration

Troubleshooting

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

Questions?

Contact us on Discord or mail us at [email protected].