How to contribute to OpenWhisk
OpenWhisk is a serverless, open source cloud platform that executes functions in response to events at any scale. It is currently a reference implementation of event-driven architecture as an Apache incubator project. If you are interested in joining the community and making contributions, this article aims to provide a one-stop instruction, walking you through the processes of how to join Apache OpenWhisk community, how to communicate with the community, how to set up the development environment for OpenWhisk, how to contribute your code to OpenWhisk, etc. After reading this document, the audience should be hassle-free in starting to contribute to OpenWhisk from scratch.
1. Joining the OpenWhisk community as a developer:
The first step you need to do is to sign and submit an Apache CLA (Contributor License Agreement). The detailed instruction can be found via this link: http://www.apache.org/licenses/#clas.
As an individual contributor, you need to fill in the agreement: www.apache.org/licenses/icla.pdf, with you signature. Then, either email or fax it to Apache. This step is mandatory for all contributors no matter you work in a company or as a freelancer.
- Email: Make sure you send it to the email address at secretary@apache.org if you decide to email. Please specify a unique Apache ID in the agreement, and mention the project name OpenWhisk, you would like to work on in the email content. After the email is sent, please wait for a couple of days. The secretary may ask you some further questions(e.g. which project you are about to work on, your Apache ID is occupied, etc. Hope not, but just keep it as a reminder.). If you have not received anything over a week, remind them by sending further emails. When your license is accepted and your Apache ID is created, you should receive an email with your valid Apache ID and gain the login access to the website https://id.apache.org/ with your Apache ID.
- Fax: The fax number can be found inside the agreement itself, if you decide to send it by facsimile.
As a corporate, assigning employees to work on an Apache project, please refer to another agreement: http://www.apache.org/licenses/cla-corporate.txt.
2. Communication with the OpenWhisk community:
Believing in meritocracy, OpenWhisk attracts contributors from all over world as an open source project, so how could you find them? It is natural that you will receive comments for the issues you opened and the pull requests you committed, and conduct the communication via more comments back and forth. However, we will come back to this in later sections of code contribution. During this section, we focus on the general channels for communication.
Mail list: The Dev Mailing List is where we discuss the development of Apache OpenWhisk. The address is dev@openwhisk.incubator.apache.org.
To subscribe to the list, send a message to: dev-subscribe@openwhisk.incubator.apache.org.
To remove your address from the list, send a message to: dev-unsubscribe@openwhisk.incubator.apache.org.
All the mails are archived in this link: http://mail-archives.apache.org/mod_mbox/incubator-openwhisk-dev/
Slack channel: To instantaneously reach out to the OpenWhisk developers for questions or help, the slack channel broadcasts at https://openwhisk-team.slack.com/. For sure you need to register yourself in slack before joining it.
If you would like to receive updates regarding OpenWhisk, you can follow the OpenWhisk Twitter account: https://twitter.com/openwhisk.
3. Creating online accounts:
The code of OpenWhisk and other extended projects are hosted on github. In order to work on OpenWhisk, you need to have a user account in github.
Visit https://github.com/, click on the “sign up” button on the top right:
Then, follow the instructions to create your account:
When your account is created, log in the github website. The most important thing is to configure an SSH key for your account. You can go to the setting page of your account or directly visit https://github.com/settings/keys. The key will be used to submit your pull request for OpenWhisk. Keep the private key on your workstation and upload the public key.
4. Setting up the local development environment:
No matter which operating system you choose, make sure you install git and configure git in your local environment. Mac OS and Ubuntu are the Top two operating systems I highly recommend as they have been well supported by OpenWhisk.
Git installation and configuration:
The official website of git is located at https://git-scm.com, where you can probably find everything you need. For those, who are the fans of command lines, it is sufficient to go through the installation guide via https://git-scm.com/book/en/v2/Getting-Started-Installing-Git, and the basic configuration over here https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup.
The OpenWhisk project and all the other supporting projects are hosted on github. You can find all of them via this link: https://github.com/openwhisk. Currently OpenWhisk is working on decoupling the modules out of the core OpenWhisk project, which is the reason you may see some projects staying there as the frames for more code to come in. Please refer to the different project links for detailed information about what they are used for.
Downloads of the code:
As a developer, there are some steps ahead. The instruction can be applied to any OpenWhisk project. We take openwhisk core project(https://github.com/openwhisk/openwhisk) as the example in this tutorial:
First, fork the repository of the project. Since we are about to submit new pull requests for merge, it is necessary to maintain the project repository under your own account. On the top right corner of openwhisk project, you can see a “fork” button. Click on it and follow the instructions, a forked repo will be created under your account.
Then, download the code into your local workstation. Open the terminal on your machine, go to the folder you choose as the workspace, and git clone the openwhisk code in your repository via the command: git clone git@github.com:<your github name>/openwhisk.git. You can find the download link shown as below:
Click on the green button of clone and download. The link of Use HTTPS/Use SSH as you see can be used to flip-flop between HTTPS and SSH links. Here copy the SSH link.
For example, my github name is houshengbo, and this is how I download the openwhisk code.
Go to the openwhisk directory you have just cloned. Check the git variables via the command: git remote -v.
Normally you only get one variable named origin set to the link of the openwhisk in the repository under your account. However, we need to add the link for the original repository in order to do further sync-ups. Copy the original SSH link for openwhisk: git@github.com:openwhisk/openwhisk.git, as you can find it the same way as in your repository.
Run the command: git remote add upstream git@github.com:openwhisk/openwhisk.git, and check with the command git remote -v to see if the link has been added.
You should be able to see the variable upstream already added for the original repository link of openwhisk.
Make sure the master branch of your repository is synchronized with the original master branch both locally and remotely. You do not have to do it as frequent as every three or five minutes. Take this as the opportunity to update to the latest code, and be aware that this is a mandatory step before you submit any pull request for merge. We will come back into this topic in the following section.
Unless you are specially interested in a certain project or component, you can download the code of openwhisk and openwhisk-catalog to deploy a local openwhisk environment with the basic functionalities. For more information regarding OpenWhisk installation and configuration, please refer to https://github.com/openwhisk/openwhisk/blob/master/tools/macos/README.md for Mac or https://github.com/openwhisk/openwhisk/blob/master/tools/ubuntu-setup/README.md for Ubuntu.
Installation of Java and Scala:
The backbone of OpenWhisk is developed in Scala. All the test cases are written in Scala. Since OpenWhisk also uses Java libraries as dependences, Java environment should be ready, before installing Scala.
Go to the website http://www.oracle.com/technetwork/indexes/downloads/index.html#java to download and install the standard Java SDK. After verifying Java is completely installed with the command java –version. You can find the document about Scala language via the link: https://www.scala-lang.org/. Please visit the download page: https://www.scala-lang.org/download/, to get the correct Scala package to fit your OS. Verify Scala on your machine with the command scala in your terminal.
Installation of Gradle:
Gradle is used as the build tool to modulize every major openwhisk projects. Go to the website https://gradle.org/install for instructions to install Gradle. Verify it via the command gradle -v in the terminal.
Installation of Go(optional):
The CLI of OpenWhisk is written in Go language. If the CLI is what you are interested, you need to install Go as well. Please visit the website of Go https://golang.org/dl/ to install it.
Configure JAVA_HOME variable for you workstation(optional):
This step is not mandatory, but it is suggested to make sure that you have a valid Java environment.
If you are using Mac, open the terminal, edit the file ~/.bash_profile with nano or vim by adding export JAVA_HOME=$(/usr/libexec/java_home. Then run the command source ~/.bash_profile to export the variable. You can check the variable with the command echo.
If you are using Ubuntu, please edit the file ~/.bashrc with gedit or nano by adding export JAVA_HOME=$(update-java-alternatives -l | head -n 1 | cut -f3 -d' '), and run the command source ~/.bashrc.
Development environment:
If you are really a geek or hacker, skip this part, because I know you are proficient in writing code in pure text without any assistance. However, if you are a conservative developer as I am, I suggest you choose an IDE you are in favor of. I pick up two IDEs: eclipse and intelliJ, as the examples in this tutorial, hoping you will love it if you come from the same Java background as I do.
Eclipse configuration:
When you use eclipse as the IDE to develop OpenWhisk, I suggest you download the version for Java EE, since EGit plugin is included. The download page is located at the page http://www.eclipse.org/downloads/eclipse-packages/. After eclipse is downloaded and installed, there are several other plugins you need to install as well.
Scala IDE plugin:
Start Eclipse, click on the menu Help, and choose Eclipse Marketplace.
Type in scala ide in the search field, and click go.
Find Scala IDE in the available list, and install it by clicking on install, if it is not installed in your eclipse. Follow the instructions step by step to finish the installation.
Buildship Gradle Integration plugin:
Go to the Eclipse Marketplace, and type in buildship gradle as the key word to search.
Install it by clicking on the install button at the bottom right, if it is not installed in your eclipse. Follow the instructions step by step to finish the installation.
Goclipse plugin(optional):
You can install the goclipse plugin the same way as installing Scala IDE and Buidship Gradle, if you plan to work on the CLI for OpenWhisk. Simply type in the key word goclipse in the Eclipse Marketplace and install it.
Import the openwhisk project into eclipse:
You have to have all the above plugins good in shape before import the openwhisk project.
Start eclipse, select the File menu, and click Import:
Select the Gradle STS project to import:
Use the browse button to locate the path of the openwhisk direcory, and click build model to build the project. When the build is done, you should see all the available modules to be imported:
Click finish button to import all the modules. When this is done, you are ready to code with openwhisk in eclipse.
IntelliJ configuration:
If you choose IntelliJ as your IDE to develop OpenWhisk, you can find the download link in this webpage: https://www.jetbrains.com/idea/. The community version is qualified as the development environment.
Configure JDK as the default SDK for all the projects:
This is very important, because the openwhisk is build on top of JVM. Otherwise you will not be able to import the project correctly.
On the bottom right, select Configure > Project Defaults > Project Structure:
Click on Project tab on the left, there is no SDK selected if you start IntelliJ for the first time. Click on the button New... to choose JDK, and click OK on the bottom right to save the changes.
Import the openwhisk project into IntelliJ:
Start the IntelliJ, select Import Project as below:
Navigate to the openwhisk folder on your machine, select the folder and click OK:
Select Import project from external model, choose gradle as the model, and click next:
Select Use default gradle wrapper, though it is the default one. Click finish.
All the available modules available will be listed. Select all of them, and click OK.
You should see the openwhisk project is imported.
One of the greatest convenience IntelliJ offers is that you can install the missing SDKs or libraries on the fly when you open the files with the binding suffixes. The main components of OpenWhisk are developed in Scala. When you open a scala file for the first time, ItelliJ will prompt you the necessary scala setup choice on the top right corner: setup scala sdks. Click on it.
If Scala SDK is not available in the SDK list, you can click on the download button to download the selected version.
After you hit OK to start the download, you can see the progress. You need to wait for some time in order to finish the download depending on your network connectivity.
When it has been finished, we should be able to see scala sdk is available, click on the OK button to enable it.
It is the similar way to install any other SDK or library in IntelliJ, each time you open a file with missing configurations.
5. Contributing code to OpenWhisk:
After the development environment is set up on your machine, you are well armed with firepower to shoot some issues for OpenWhisk. There are many ways that you can make contribution to OpenWhisk, e.g. opening an issue, fixing an issue with your pull request, submitting proposals to implement, improving the documentation, answering the questions raised in the community, etc. This tutorial focuses how to report an issue and submit pull request to resolve this issue.
Report an issue:
Every OpenWhisk project has a tab page to report issues. For the main OpenWhisk, you can visit the following link to check all the issues: https://github.com/openwhisk/openwhisk/issues.
If you find a valid issue for OpenWhisk and it has not been reported yet, please click the green button New Issues located close to the top right, to reach the page for the issue description.
As you can see, there is a detailed introduction to describe the issue you have, try to give the description as comprehensive as possible. The most important remark is how to reproduce it under what kind of environment you are using.
Make sure you give a precise title, and add the description to the issue. Technically you are OK to submit the issue by clicking on the green button Submit new issue at the bottom.
Then you issue can listed as an open issue, which has a valid issue number. For example, it is 2012 for my test issue.
On the right panel to the issue, you can see the issue can be better triaged, which can help other developers in the community grasp it quickly. If you are confident in resolving it by your own, do not hesitate to assign it to yourself, or someone you know, who can be designated to fix it, simply by clicking on the setting icon for Assignees.
It works the same way if you add a label to your issue, to put your issue into the correct category.
You can always find the issue you opened in the issue list of OpenWhisk, and track it to see if there are comments from the community. To find your issue quickly, you can always filter all the issues by author. It can be done by clicking Author and selecting your name at the top of name list, on the tab page of Issues:
One common case you are probably going to meet is that the folks from in the community ask you for more elaboration for the issue. Please remember to response in a timely fashion and always be nice.
Submit a pull request:
Following-up the issue you opened, you know how to fix it. Here is the guidance for you to maintain your local workspace. By walking through the previous instructions, you have already created your OpenWhisk workspace with two git variable: origin and upstream as bellows:
Origin is the fork in your repository, and upstream is original repository. You are currently on the master branch if you access your openwhisk directory for the first time:
Do not conduct any changes to your master branch. It is used to sync up with the original openwhisk code. Create a new branch to work on for your issue by running the command: git checkout -b <branch_name>. Do not forget the -b for creating new branches. Try to give the issue a straightforward name. In this tutorial, we use my-first-issue.
After you run the command, you have been switch to the new branch my-first-issue. You can always switch to any existing branch in your work directory by the command git checkout <branch_name>, after the change is committed locally. Remember there is no -b for existing branches.
On the new branch, feel free to add the necessary changes into the code with your talent. When this step is done, make sure you add necessary test cases for your changes and commit the change, by running the command: git commit -a, in your terminal, and add the commit message to your issue. Based on my experience, the first paragraph is a concise introduction to the commit, then further paragraphs contain detailed description to the changes. Finally marks the issue number for trace convenience.
When you are working with the commit message on the terminal, use “control + O” to write out the message, and then use “control + X to quit”. I know under Ubuntu the terminal works this way by default. Under Mac, you probably need to configure nano as the editor to make it work this way with the command: git config --global core.editor "nano". Anyway, feel free to use any other editors. After this, you are able to see your change is committed locally.
Rebase your work: This is a very important step before committing any change to OpenWhisk. Make sure your branch is based on top of the latest openwhisk code, in order to remove further code conflicts, when being merged into code base by other committers.
How to sync up your local master with the remote master? Run the following commands in your terminal:
- git fetch upstream
- git checkout master
- git merge upstream/master
- git push origin master
After you these commands, your local master and the code base in your fork repository should be already synchronized with the latest openwisk code. Then make sure you have switched to your work branch by git checkout <branch_name> and run the command to rebase your work branch: git rebase -i master. Pick the commit as you need, and commit the rebase via control+O and control+X, which may vary if you use other editors.
If there is no conflict, you should receive a successful rebase. Otherwise, you need to resolve manually the files with the conflicts. After that, you need to continue your rebase by adding the files with conflicts: git add <file with conflicts>, and then run git rebase –continue to finish the rebase.
Submit your branch into your fork repository via the command: git push origin <branch_name>.
You should be able to see this branch in your own fork repository, as indicated below:
Create a pull request for your branch: If your branch is submitted into your fork, you are ready to submit it as a pull request for the code base to merge. First go to the tab page of pull requests:
Then, click the green button new pull request on the right, and reach the page of comparing changes.
Please click the link: compare across forks, and select your fork head and your branch name. Finally, click the green button create pull request.
You can once again change the title for your pull request and description into something different from what is in your commit message, but it is your choice. Click the button create pull request to submit your pull request for openwhisk:
You can see you pull request is submitted to openwhisk:
Actively keep your eyes on the latest comments from the community regarding your pull request. The reviewers may ask you to do further amendments to comply with the code standard, cover more logic, etc. In case that you need to modify your branch, you can choose either to continue working on your commit via the command git commit -a — amend or submit a new commit via git commit -a. No matter which approach you take, when a new change has been done, go through the same process staring with syncing-up your local master again to resubmit your branch as the pull request.
For more detailed information regarding the contribution to openwhisk with git, please refer to the link: https://github.com/openwhisk/openwhisk/wiki/Contributing:-Git-guidelines. Enjoy working with OpenWhisk!
