CONTRIBUTING.md

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
• Build the source code
• Set up the development environment
  • Set up the Ballerina plugins
  • Set up the ANTLR4 plugin
• Submit your contribution
• Accept the Contributor License Agreement
• Propose changes to Ballerina

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
  • 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 Slack channel.

  • Compiler, runtime, standard library, or tooling: ballerina-lang repo
  • Language specification: ballerina-spec repo
  • Website: ballerina-dev-website repo
  • Security flaw: send an email to security@ballerina.io. For details, see the security policy.

• 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 Building 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

Set up the Ballerina plugin for VS Code

For installation instructions, see Ballerina VS Code Documentation.

Submit your contribution

1. Do your changes in the source code.

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 Slack channel. 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.