How to contribute

    • Ensure the bug was not already reported by searching on GitHub under .
    • If you’re unable to find an open issue addressing the problem, open a new one. Be sure to include a title and clear description, as much relevant information as possible, and a code sample or an executable test case demonstrating the expected behavior that is not occurring.

    Welcome to contribute code to provide features or fix bugs.

    We use GitHub pull request to review proposed code changes. So you’ll need to obtain a GitHub account before making code contribution.

    1. Fork eKuiper to your private repository. Click the button in the top right corner of eKuiper repository.
    2. Clone the repository locally from your personal fork. git clone https://github.com/<Github_user>/ekuiper.git.
    3. Add eKuiper repo as additional Git remote so that you can sync between local repo and eKuiper.

    You can use your favorite IDE or editor to develop. You can find information in editor support for Go tools in .

    Create a branch in your fork

    You’ll work on your contribution in a branch in your own (forked) repository. Create a local branch, initialized with the state of the branch you expect your changes to be merged into. The master branch is active development branch, so it’s recommended to set master as base branch.

    1. $ git fetch upstream
    2. $ git checkout -b <my-branch> upstream/master

    Code conventions

    • Use go fmt to format your code before commit code change. eKuiper Github Action CI pipeline reports error if it’s not format by go fmt.
    • Configuration key in config files uses camel case format.

    Take GoLand as an example, developers can debug the code:

    1. Debug the whole program. Make sure all directories mentioned in build_prepare sections are created in your eKuiper root path. Add your breakpoints. Open cmd/kuiperd/main.go. In the main function, you’ll find a green triangle in the ruler, click it and select debug. Then create your stream/rule that would run through your breakpoint, the debugger will pause there.
    2. To debug a small portion of code, we recommend writing a unit test and debug it. You can go to any test file and find the same green triangle to run in debug mode. For example, pkg/cast/cast_test.go TestMapConvert_Funcs can run as debug.

    Debug edgex code

    Users can modify edgex source/sink code to meet their requirement. In this case, the best practice is letting the other services running in docker mode but eKuiper run locally. Users can follow these steps to set up the environment.

    expose message bus

    eKuiper subscribe messages by topic and by default edgex is using redis as message bus. This guide will use redis as example to show how to expose message bus. In the docker-compose file, find the redis service and in ports part change 127.0.0.1:6379 to 0.0.0.0:6379, then restart all the services.

    1.  database:
    2.     container_name: edgex-redis
    3.     environment:
    4.       CLIENTS_CORE_COMMAND_HOST: edgex-core-command
    5.       CLIENTS_CORE_DATA_HOST: edgex-core-data
    6.       CLIENTS_SUPPORT_NOTIFICATIONS_HOST: edgex-support-notifications
    7.       CLIENTS_SUPPORT_SCHEDULER_HOST: edgex-support-scheduler
    8.       DATABASES_PRIMARY_HOST: edgex-redis
    9.       EDGEX_SECURITY_SECRET_STORE: "false"
    10.       REGISTRY_HOST: edgex-core-consul
    11.     hostname: edgex-redis
    12.     image: redis:6.2-alpine
    13.     networks:
    14.       edgex-network: {}
    15.     ports:
    16.     - 0.0.0.0:6379:6379/tcp
    17.     read_only: true
    18.     restart: always
    19.     security_opt:
    21.     user: root:root
    22.     volumes:
    23.     - db-data:/data:z

    change edgex local config

    Change edgex source config according to message bus type, the following table is message bus configuration the file locates in etc/sources/edgex.yaml.

    Take the redis as example, the following config will let eKuiper connect to 10.65.38.224’s 6379 port.

    After changing this, redis will listen on the host 6379 port, developers can connect to the machine that edgex runs remotely by the server address. For example, the host ip address is 10.65.38.224 , users can connect to this machine by the ip address.

    enable eKuiper console log and set rest api port

    Change the config file in etc/kuiper.yaml, set the console log true and set eKuiper rest api port to 59720

    1. basic:
    2.   # true|false, with debug level, it prints more debug info
    3.   debug: false
    4.   # true|false, if it's set to true, then the log will be print to console
    5.   consoleLog: true
    6.   # true|false, if it's set to true, then the log will be print to log file
    7.   fileLog: true
    8.   # How many hours to split the file
    9.   rotateTime: 24
    10.   # Maximum file storage hours
    11.   maxAge: 72
    12.   # CLI ip
    13.   ip: 0.0.0.0
    14.   # CLI port
    15.   port: 20498
    16.   # REST service ip
    17.   restIp: 0.0.0.0
    18.   # REST service port
    19.   restPort: 59720
    20.   # true|false, when true, will check the RSA jwt token for rest api
    21.   authentication: false
    22.   #  restTls:
    23.   #    keyfile: /var/https-server.key
    25.   prometheus: false
    26.   prometheusPort: 20499
    27.   # The URL where hosts all of pre-build plugins. By default it's at packages.emqx.net
    28.   pluginHosts: https://packages.emqx.net
    29.   # Whether to ignore case in SQL processing. Note that, the name of customized function by plugins are case-sensitive.
    30.   ignoreCase: true

    run locally

    Testing

    The eKuiper project leverages Github actions to run unit test & FVT (functional verification test), so please take a look at the PR status result, and make sure that all of testcases run successfully.

    • Write Golang unit testcases to test your code if necessary.
    • A set of FVT testcases will be triggered with any PR submission, so please make sure that these testcases can be run successfully.

    Licensing

    All code contributed to eKuiper will be licensed under Apache License V2. You need to ensure every new files you are adding have the right license header.

    The sign-off is to certify the origin of the commit. It is required to commit to this project. If you set your user.name and user.email git configs, you can sign your commit automatically with git commit -s. Each commit must be signed off.

    Syncing

    Periodically while you work, and certainly before submitting a pull request, you should update your branch with the most recent changes to the target branch. We prefer rebase than merge to avoid extraneous merge commits.

    1. git fetch upstream
    2. git rebase upstream/master

    Then you can push to your forked repo. Assume the remove name for your forked is the default origin. If you have rebased the git history before the last push, add -f to force pushing the changes.

    Submitting changes

    The master branch is active development branch, so it’s recommended to set master as base branch, and also create PR against master branch.

    Organize your commits to make a committer’s job easier when reviewing. Committers normally prefer multiple small pull requests, instead of a single large pull request. Within a pull request, a relatively small number of commits that break the problem into logical steps is preferred. For most pull requests, you’ll squash your changes down to 1 commit. You can use the following command to re-order, squash, edit, or change description of individual commits.

    1. git rebase -i upstream/master

    Make sure all your commits comply to the .

    You’ll then push to your branch on your forked repo and then navigate to eKuiper repo to create a pull request. Our GitHub repo provides automatic testing with GitHub action. Please make sure those tests pass. We will review the code after all tests passed.

    Each commit message consists of a header, a body and a footer. The header has a special format that includes a type, a scope and a subject:

    1. <type>(<scope>): <subject>
    2. <BLANK LINE>
    3. <body>
    4. <BLANK LINE>
    5. <footer>

    The header with type is mandatory. The scope of the header is optional. This repository has no predefined scopes. A custom scope can be used for clarity if desired.

    The footer should contain a if any.

    Example 1:

    1. fix(script): correct run script to use the right ports
    3. Previously device services used wrong port numbers. This commit fixes the port numbers to use the latest port numbers.
    5. Closes: #123, #245, #992

    Revert

    If the commit reverts a previous commit, it should begin with revert:, followed by the header of the reverted commit. In the body it should say: This reverts commit <hash>., where the hash is the SHA of the commit being reverted.

    Type

    Must be one of the following:

    • feat: New feature for the user, not a new feature for build script
    • fix: Bug fix for the user, not a fix to a build script
    • docs: Documentation only changes
    • style: Formatting, missing semi colons, etc; no production code change
    • refactor: Refactoring production code, eg. renaming a variable
    • chore: Updating grunt tasks etc; no production code change
    • perf: A code change that improves performance
    • test: Adding missing tests, refactoring tests; no production code change
    • build: Changes that affect the CI/CD pipeline or build system or external dependencies (example scopes: travis, jenkins, makefile)
    • ci: Changes provided by DevOps for CI purposes.
    • revert: Reverts a previous commit.

    Scope

    There are no predefined scopes for this repository. A custom scope can be provided for clarity.

    Subject

    The subject contains a succinct description of the change:

    • use the imperative, present tense: “change” not “changed” nor “changes”
    • don’t capitalize the first letter
    • no dot (.) at the end

    Body

    Just as in the subject, use the imperative, present tense: “change” not “changed” nor “changes”. The body should include the motivation for the change and contrast this with previous behavior.

    The footer should contain any information about Breaking Changes and is also the place to reference GitHub issues that this commit Closes.

    Breaking Changes should start with the word with a space or two newlines. The rest of the commit message is then used for this.

    Besides coding, other types of contributions are a great way to get involved. Welcome to contribute to this project by promoting it to the open source community and the world.

    The promotion contributions include but not limit to:

    • Integrate of eKuiepr to your open source project
    • Organize workshops or meetups about the project
    • Answer questions about the project on issues, slack or maillist
    • Offer to mentor another contributor