Skip to content

Latest commit

 

History

History
113 lines (73 loc) · 7.85 KB

CONTRIBUTING.md

File metadata and controls

113 lines (73 loc) · 7.85 KB
Raw

Contributing to Ballerina

Ballerina is an open source programming language and platform for cloud-era application programmers to easily write software. It is licensed under the Apache License and is nurtured by all the contributors of the Ballerina community.

We appreciate your help!

Get started

  • Download Ballerina and go through the learning resources.

  • Read the Ballerina Code of Conduct.

  • Join the conversations at:

    • StackOverflow: to get help with Ballerina (use the Ballerina tag for any of your questions)
    • Slack: for real-time discussions with the team and community
    • Ballerina-Dev Google Group: (community mailing list) to discuss Ballerina roadmap, features, and related issues
    • Twitter: to tweet about Ballerina (use the “#ballerinalang” hashtag)
    • GitHub: to file issues, join the conversations on new features, comment on other issues, and send your pull requests.

  • Submitting a bug is just as important as contributing to code. Report an issue in the relevant repo out of the GitHub repos listed below.

    Tip: If you are unsure whether you have found a bug, search existing issues in the corresponding repo on GitHub and raise it in the Ballerina-Dev Google Group.

  • Start with GitHub issues that can be fixed easily:

    • Browse issues labeled "good first issue" in the ballerina-lang repo.
    • Use comments on the issue itself to indicate that you will be working on it and get guidance and help.

Build the source code

For instructions, see Installing from source.

Set up the development environment

See the below sections to set up the required plugins in your preferred IDEs/Editors.

Set up the Ballerina plugins

Currently, Ballerina has the below plugins developed for IntelliJ IDEA and VS Code.

Set up the ANTLR4 plugin

This plugin will be useful to check and validate a grammar rule you wrote. For instructions on installing the ANTLR4 plugin based on your preferred IDE/Editor (which supports ANTLR 4.x version), go to ANTLR Documentation.

Submit your contribution

  1. Do your changes in the source code.

    Contributing to Ballerina Grammer:

    Ballerina grammar has been implemented using ANTLR plugin version 4.5.3. To get a basic understanding of ANTLR grammar syntax and concepts before working with Ballerina grammar, go to Parr, Terence (January 15, 2013), The Definitive ANTLR 4 Reference.

    Ballerina grammar consists of two files:

    • BallerinaLexer.g4: contains the lexer rules for Ballerina grammar. The lexer is responsible for tokenizing an input Ballerina source code.
    • BallerinaParser.g4: contains the parser rules. Parser listens to the token stream generated by the lexer. High level grammar productions/abstractions are defined in the parser using those tokens.

    Once a change is done to any of the grammar files, the lexer and the parser need to be re-generated. To generate the lexer and the parser, navigate to the <BALLERINA_PROJECT_ROOT>/compiler/ballerina-lang/src/main/resources/grammar/ directory, and execute the below command.

    Tip: Download the antlr-complete-4.5.3.jar file and replace <PATH-TO-ANTLR-JAR> in the below command with the location in which you saved it.

    java -jar <PATH-TO-ANTLR-JAR>/antlr-4.5.3-complete.jar *.g4 -package org.wso2.ballerinalang.compiler.parser.antlr4 -o <BALLERINA_PROJECT_ROOT>/compiler/ballerina-lang/src/main/java/org/wso2/ballerinalang/compiler/parser/antlr4/

    Info: The above command will autogenerate some Java classes. The Ballerina AST builder is written on top of the auto-generated BallerinaParserBaseListener.java class. Thus, if any new rules are added to the BallerinaParser.g4, the above command will generate new methods in the BallerinaParserBaseListener.java and you need to override those newly-added methods inside the BLangParserListener.java accordingly.

    For more information about the Ballerina compiler, go to Ballerina Compiler — Design.

  2. Add unit tests accordingly. (The build process will automatically execute all the tests.)

  3. Commit the changes to your fork and push them to the corresponding original repo by sending a Pull Request (PR).

    Tip: Follow these commit message requirements:

    • Separate subject from the body with a blank line
    • Limit the subject line to 50 characters
    • Capitalize the subject line
    • Do not end the subject line with a period
    • Use the imperative mood in the subject line
    • Wrap the body at 72 characters
    • Use the body to explain what and why vs. how

    For more information, go to How to Write a Git Commit Message.

  4. Accept the Contributor License Agreement (CLA)

    You need to Accept the Ballerina Contributor License Agreement (CLA) when prompted by a GitHub email notification after sending your first Pull Request (PR). Subsequent PRs will not require CLA acceptance.

    If the CLA gets changed for some (unlikely) reason, you will be presented with the new CLA text after sending your first PR after the change.

Propose changes to Ballerina

Start the discussion on the changes you propose in the Ballerina-Dev Google Group. Once there is enough consensus around the proposal, you will likely be asked to file an issue on GitHub and label it as 'Proposal' to continue a detailed discussion there.