-
Notifications
You must be signed in to change notification settings - Fork 758
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #21005 from praneesha/lang-issue-21004
Add Back the Contribution Guide in B.io to the Contributing.MD File
- Loading branch information
Showing
2 changed files
with
74 additions
and
161 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,195 +1,114 @@ | ||
| # Contributing to Ballerina | ||
|
|
||
| Ballerina is an open source programming language and platform for cloud-era application programmers to easily write software that just works. | ||
|
|
||
| We are an open-source project under Apache license and the work of hundreds of contributors. | ||
| 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](https://www.apache.org/licenses/LICENSE-2.0) and is nurtured by all the contributors of the Ballerina community. | ||
|
|
||
| We appreciate your help! | ||
|
|
||
| ## Getting Started | ||
|
|
||
| * Download Ballerina at [https://ballerina.io](https://ballerina.io) and go through the getting started tutorials at [https://ballerina.io/learn](https://ballerina.io/learn) | ||
| * Read our [Code of Conduct](CODE_OF_CONDUCT.md) | ||
| * Join the conversations at: | ||
| * [StackOverflow](https://stackoverflow.com/questions/tagged/ballerina): to get help with Ballerina; use Ballerina tag for any your questions there, | ||
| * [Slack](https://ballerinalang.slack.com/): for real-time discussions with the team and community, | ||
| * [Ballerina-Dev Google Group](https://groups.google.com/forum/#!forum/ballerina-dev): developer team mailing list to discuss Ballerina roadmap, features and issues on the works, and so on, | ||
| * [GitHub](https://github.com/ballerina-platform/ballerina-lang/issues): file issues, comment on other issues, send your pull requests. | ||
| * Submit issues: | ||
| * Found a security flaw? Please email [email protected] | ||
| * Submitting a bug is just as important as contributing code. Go to the Issues tab of the GitHub repo and click the New Issue button to file a bug report. | ||
| * Start with easy fix issues: | ||
| * Browse issues labeled easyfix, | ||
| * Use comments on the issue itself to indicate that you will be working on it and get guidance and help. | ||
|
|
||
| ## Communicating with the team | ||
|
|
||
| [Ballerina-Dev Google Group](https://groups.google.com/forum/#!forum/ballerina-dev) is the main Ballerina project discussion forum. | ||
|
|
||
| [StackOverflow](https://stackoverflow.com/questions/tagged/ballerina) is used for support, [Slack](https://ballerinalang.slack.com/) for real-time communications, and [GitHub](https://github.com/ballerina-platform/ballerina-lang/issues) for issues and code repositories. | ||
|
|
||
| ## Filing issues | ||
|
|
||
| If you are unsure whether you have found a bug, please consider searching existing issues in github and asking in Ballerina-Dev Google Group. | ||
|
|
||
| > IMPORTANT: Sensitive security-related issues should be reported to [[email protected]]([email protected]). For details, see the [security policy](https://ballerina.io/security/). | ||
| To file non-security issues: | ||
|
|
||
| 1. Click the **Issues** tab in the github repository, | ||
|
|
||
| 2. Click the **New Issue** button, | ||
|
|
||
| 3. Fill out all sections in the issue template and submit. | ||
|
|
||
| ## Contributing site changes, docs, and examples | ||
|
|
||
| ## Contributing code | ||
|
|
||
| ### Accepting Contributor License Agreement (CLA) | ||
|
|
||
| Before you submit your first contribution please accept our Contributor License Agreement (CLA) here. When you send your first Pull Request (PR), GitHub will ask you to accept the CLA. | ||
|
|
||
| There is no need to do this before you send your first PR. | ||
|
|
||
| Subsequent PRs will not require CLA acceptance. | ||
|
|
||
| If for some (unlikely) reason at any time CLA changes, you will get presented with the new CLA text on your first PR after the change. | ||
|
|
||
| ### Obtaining the Source Code and Building the Project | ||
|
|
||
| #### Build Prerequisites | ||
|
|
||
| **Prerequisite 1** - Install a Java Development Kit (JDK) version 8 | ||
|
|
||
| Building Ballerina requires a Java SE Development Kit (JDK) version 8 to be installed. You can download one from one of the following locations: | ||
|
|
||
| * [http://www.oracle.com/technetwork/java/javase/downloads/index.html](http://www.oracle.com/technetwork/java/javase/downloads/index.html) | ||
| * [http://openjdk.java.net/install/index.html](http://openjdk.java.net/install/index.html) | ||
|
|
||
| > NOTE: Set an environment variable `JAVA_HOME` to the path name of the directory into which you installed the JDK release. | ||
| **Prerequisite 2** - Node (v8.9.x or latest LTS release) + npm (v5.6.0 or later) | ||
|
|
||
| **Prerequisite 3** - Docker | ||
|
|
||
| #### Building from the source | ||
|
|
||
| Clone this repository using the following command. | ||
|
|
||
| ``` | ||
| git clone --recursive https://github.com/ballerina-platform/ballerina-lang.git | ||
| ``` | ||
|
|
||
| If you have forked the repository to your github account then use the following command replacing <YOUR-GITHUB-USERNAME> with your git username. | ||
|
|
||
| ```` | ||
| git clone --recursive https://github.com/<YOUR-GITHUB-USERNAME>/ballerina-lang.git | ||
| ```` | ||
|
|
||
| If you download the sources, you need to update the git submodules using the following command. | ||
|
|
||
| ``` | ||
| git submodule update --init | ||
| ``` | ||
|
|
||
| Run the gradle command `./gradlew clean build` from the Ballerina root directory: | ||
|
|
||
| Extract the Ballerina distribution created at `distribution/zip/ballerina/target/ballerina-<version>-SNAPSHOT.zip`. The `zip/ballerina` directory contains the runtime only. `zip/ballerina-tools/` contains the runtime and tools (e.g., Ballerina Composer). | ||
|
|
||
| Note: It is possible to face an IOException error stating "Too many open files". This is due to the default number of possible open files being set to a lower number on your operating system than required for Ballerina to be compiled. You may have to increase the number of open files/file descriptors (FD) on your operating system. This is OS dependent and you can search the internet on how to do this for your operating system (Windows/OSX/Linux). You could update the maximum number of open files to 1000000 (or higher). | ||
|
|
||
| ### Setting up your development environment | ||
|
|
||
| #### Setup IntelliJ IDEA | ||
|
|
||
| ##### Importing a Ballerina Project | ||
| - [Get started](#get-started) | ||
| - [Build the source code](#build-the-source-code) | ||
| - [Set up the development environment](#set-up-the-development-environment) | ||
| - [Set up the Ballerina plugins](#set-up-the-ballerina-plugins) | ||
| - [Set up the ANTLR4 plugin](#set-up-the-antlr4-plugin) | ||
| - [Submit your contribution](#submit-your-contribution) | ||
| - [Accept the Contributor License Agreement](#accept-the-contributor-license-agreement) | ||
| - [Propose changes to Ballerina](#propose-changes-to-ballerina) | ||
|
|
||
| Import the Ballerina project to IntelliJ IDEA similar to any other Gradle project. | ||
| ## Get started | ||
|
|
||
| * Navigate to `File | Open` menu. | ||
| * Browse the filesystem and Select Ballerina Project's root directory. | ||
| * If prompted to import Gradle project select `Auto import`. | ||
| * Set Project SDK as Java 1.8 | ||
| - Download [Ballerina](https://ballerina.io/downloads/) and go through the [learning resources](https://ballerina.io/learn). | ||
| - Read the <a href="https://ballerina.io/code-of-conduct">Ballerina Code of Conduct</a>. | ||
|
|
||
| ##### Useful IDEA Plugins | ||
| - Join the conversations at: | ||
|
|
||
| * ANTLR 4 - https://plugins.jetbrains.com/plugin/7358-antlr-v4-grammar-plugin | ||
| * Ballerina - https://plugins.jetbrains.com/plugin/9520-ballerina (Need IDEA 2016.3 or newer) | ||
| - [StackOverflow](https://stackoverflow.com/questions/tagged/ballerina): to get help with Ballerina (use the Ballerina tag for any of your questions) | ||
| - [Slack](https://ballerina.io/community/slack/): for real-time discussions with the team and community | ||
| - [Ballerina-Dev Google Group](https://groups.google.com/forum/#!forum/ballerina-dev): (community mailing list) to discuss Ballerina roadmap, features, and related issues | ||
| - [Twitter](https://twitter.com/ballerinalang): to tweet about Ballerina (use the “#ballerinalang” hashtag) | ||
| - [GitHub](https://github.com/ballerina-platform/ballerina-lang/issues): to file issues, join the conversations on new features, comment on other issues, and send your pull requests. | ||
|
|
||
| #### Setup Eclipse | ||
| - 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. | ||
|
|
||
| ##### Importing a Ballerina Project | ||
| >**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](#https://groups.google.com/forum/#!forum/ballerina-dev). | ||
| - Compiler, runtime, standard library, or tooling: <a href="https://github.com/ballerina-platform/ballerina-lang/issues">ballerina-lang</a> repo | ||
| - Language specification: <a href="https://github.com/ballerina-platform/ballerina-spec/issues">ballerina-spec</a> repo | ||
| - Website: <a href="https://github.com/ballerina-platform/ballerina-dev-website/issues">ballerina-dev-website</a> repo | ||
| - Security flaw: send an email to [email protected]. For details, see the <a href="https://ballerina.io/security/">security policy</a>. | ||
| All Ballerina repositories are developed as Maven or Gradle projects. So you can import any Ballerina project to Eclipse similar to any Maven or Gradle project. | ||
| - Start with GitHub issues that can be fixed easily: | ||
| - Browse issues labeled "good first issue" in the <a href="https://github.com/ballerina-platform/ballerina-lang/issues">ballerina-lang</a> repo. | ||
| - Use comments on the issue itself to indicate that you will be working on it and get guidance and help. | ||
|
|
||
| * Navigate to **File** → **Import..** | ||
| * Select **Existing Maven Projects** under **Maven** | ||
| * Next, browse the file system, and open the Maven module. | ||
| ## Build the source code | ||
|
|
||
| ##### Installing ANTLR4 plugin | ||
| If you are working with the grammar, it would be useful to have ANTLR 4 IDE plugin installed for Eclipse. To install this using Eclipse marketplace: | ||
| For instructions, see <a href="https://ballerina.io/learn/installing-ballerina/#installing-from-source">Installing from source</a>. | ||
|
|
||
| 1. Navigate to **Help** → **Eclipse Marketplace** | ||
| ## Set up the development environment | ||
|
|
||
| 2. Search for **antlr4** | ||
| See the below sections to set up the required plugins in your preferred IDEs/Editors. | ||
|
|
||
| 3. Install ANTLR 4 IDE plugin (which supports antlr 4.x version). | ||
| ### Set up the Ballerina plugins | ||
|
|
||
| To open the plugin views: | ||
| Currently, Ballerina has the below plugins developed for IntelliJ IDEA and VS Code. | ||
| - [Ballerina plugin for IntelliJ IDEA](https://plugins.jetbrains.com/plugin/9520-ballerina) | ||
|
|
||
| For installation instructions, see [Ballerina IntelliJ Plugin Documentation](https://ballerina.io/learn/intellij-plugin/). | ||
| - [Ballerina plugin for VS Code](https://marketplace.visualstudio.com/items?itemName=ballerina.ballerina) | ||
|
|
||
| For installation instructions, see [Ballerina VS Code Documentation](https://ballerina.io/learn/vscode-plugin). | ||
|
|
||
| 1. Navigate to **Window** → **Show View** → **Other**. | ||
| ### Set up the ANTLR4 plugin | ||
|
|
||
| 2. Under **ANTLR4** section, select and enable **Parse Tree** view and **Syntax Diagram** views. | ||
| 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](https://www.antlr.org/tools.html). | ||
|
|
||
| ### Working With the Ballerina Grammar | ||
| ## Submit your contribution | ||
|
|
||
| Ballerina grammar has been implemented using ANTLR4. It is recommended to have some basic understanding on ANTLR4 grammar syntax and concepts, before working with the Ballerina grammar. “Parr, Terence (January 15, 2013), The Definitive ANTLR 4 Reference” is a good reference to get started with. | ||
| 1. Do your changes in the source code. | ||
|
|
||
| <details> | ||
| <summary>Contributing to Ballerina Grammer:</summary> | ||
|
|
||
| Ballerina grammar can be found under [`<ballerina>/compiler/ballerina-lang/src/main/resources/grammar/`](https://github.com/ballerina-platform/ballerina-lang/tree/master/compiler/ballerina-lang/src/main/resources/grammar) in the Ballerina repository. It consists of two files: | ||
| 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](https://www.oreilly.com/library/view/the-definitive-antlr/9781941222621/). | ||
|
|
||
| * BallerinaLexer.g4 - Contains the lexer rules for Ballerina grammar. 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. | ||
| [Ballerina grammar](https://github.com/ballerina-platform/ballerina-lang/tree/master/compiler/ballerina-lang/src/main/resources/grammar) consists of two files: | ||
|
|
||
| > TIP: If you want to check and validate a grammar rule you just wrote, you can use the ANTLR 4 plugin of your IDE. See Setting up your development environment section for more details. | ||
| - **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. | ||
|
|
||
| #### Generating Parsers | ||
| 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. | ||
|
|
||
| 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, first download the `antlr-complete-4.5.3.jar` file. Then navigate to `<ballerina>/compiler/ballerina-lang/src/main/resources/grammar/`, and execute the following command: | ||
| ``` | ||
| java -jar <path-to-antlr-jar>/antlr-4.5.3-complete.jar *.g4 -package org.wso2.ballerinalang.compiler.parser.antlr4 -o ../../java/org/wso2/ballerinalang/compiler/parser/antlr4/ | ||
| ``` | ||
| >**Tip:** Download the [antlr-complete-4.5.3.jar](https://jar-download.com/artifacts/org.antlr/antlr4/4.5.3/source-code) file and replace `<PATH-TO-ANTLR-JAR>` in the below command with the location in which you saved it. | ||
| The above command will autogenerate some Java classes. Out of the autogenerated classes, `BallerinaParserBaseListener.java` in particular is important, as the Ballerina AST builder is written on top of it. Thus, if any new rules are added to the BallerinaParser.g4, above command will generate new methods in the `BallerinaParserBaseListener.java`, and you need to override those newly added methods inside `BLangParserListener.java` accordingly. | ||
| ```bash | ||
| 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/ | ||
| ``` | ||
|
|
||
| ### Ballerina Compiler | ||
| https://medium.com/@sameera.jayasoma/ballerina-compiler-design-3406acc2476c | ||
| **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. | ||
|
|
||
| ### Creating a Patch for Review | ||
| For more information about the Ballerina compiler, go to [Ballerina Compiler — Design](https://medium.com/@sameerajayasoma/ballerina-compiler-design-3406acc2476c?). | ||
|
|
||
| #### Fork the Repo | ||
| #### Make Your Changes | ||
| #### Add Unit Tests | ||
| </details> | ||
|
|
||
| Build process automatically runs all the tests. | ||
| 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). | ||
|
|
||
| #### Commit to Your Fork | ||
| >**Tip:** Follow these commit message requirements: | ||
|
|
||
| We 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 | ||
|
|
||
| * Separate subject from 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](https://chris.beams.io/posts/git-commit/). | ||
|
|
||
| Please find details at: [https://chris.beams.io/posts/git-commit/](https://chris.beams.io/posts/git-commit/) | ||
| ## Accept the Contributor License Agreement | ||
|
|
||
| ## Proposing Changes To Ballerina | ||
| You need to Accept the Ballerina Contributor License Agreement (CLA) here when prompted by GitHub while sending your first Pull Request (PR). Subsequent PRs will not require CLA acceptance. | ||
|
|
||
| Start with the discussion in the Ballerina-Dev Google Group. | ||
| If the CLA gets changed for some (unlikely) reason, you will be presented with the new CLA text when sending your first PR after the change. | ||
|
|
||
| Once there is enough consensus around the proposal, you will likely be asked to file an Issue in GitHub and label it as Proposal, to continue the discussion on details there. | ||
| ## Propose changes to Ballerina | ||
|
|
||
| Start the discussion on the changes you propose in the [Ballerina-Dev Google Group](https://groups.google.com/forum/#!forum/ballerina-dev). 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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters