Contributing to the Code Base

Anyone (not just committers) can share contributions to WSO2's open-source software products. Your work will be recognized: if your contribution - feature enhancement, bug fix, or other improvements - is accepted, your name will be included as an author in the official commit logs. Read on for details on how you can contribute.

WSO2 GitHub guidelines

  • Fork the correct WSO2 Git repository

    When contributing to WSO2 code base by way of a patch, make sure you identify the correct Git repository that needs to be forked. For more information on WSO2 Git repositories, see WSO2 GitHub Repositories. If you still are not sure which repository to fork, send an email to dev@wso2.org so that a WSO2 team member can advise you.

  • Do not build any dependencies

    You do not need to build any dependencies, as everything you need will be automatically fetched from the Maven repository (Nexus) when you are building the product on your machine. Make sure the build server has an active Internet connection to download dependencies while building.

  • Sync the fork with the upstream repository before issuing a pull request

    If you are working with a branch instead of a tag, there is a high possibility that the forked repository may differ from the upstream repository (the remote repository that you forked) because it will likely have changed since you forked it. Therefore, always sync the forked repository with the upstream repository before issuing a pull request to prevent the request from being rejected. (Tags are static by definition, so the files in a tag should not have changed, making this step unnecessary when working with a tag instead of a branch.)

Contributing your code

Follow these instructions to contribute to the WSO2 code base. Be sure to follow the WSO2 GitHub Guidelines above.

  1. Fork the respective code base to your Git account.

  2. Clone the code base to your local machine, and then change to the local directory where the code was cloned.

    git clone <GITHUB_REPOSITORY_URL>

    cd <REPOSITORY_NAME>

    For example, if the repository is wso2-synapse:

    git clone https://github.com/wso2/wso2-synapse.git

    cd wso2-synapse

  3. Set your working directory by doing one of the following:

    • To work with code on a project that is under development, set your working directory to the appropriate branch using the checkout command as follows:

      git checkout <REMOTE_BRANCH>

      For example, to work with a branch named refactoring:

      git checkout refactoring

    • To work with code in a project that was already released, set your working directory to the appropriate tag for that release using the checkout command as follows:

      git checkout tags/<TAG_NAME> -b <LOCAL_BRANCH>

      For example, to work with the v5.1.0 tag, which represents the IS 5.1.0 product release:

      git checkout tags/v5.1.0 -b v5.1.0

    Tip: To help avoid confusion, set the local branch name to the same name as the remote branch.

  4. Build the product using Maven. For details, see Using Maven to Build WSO2 Products.

  5. If you need to add a new file to the repository:

    1. Add the new file.

      git add <FILE_NAME>

      For example:

      git add mycode.java

    2. Commit the newly added file to your local repository.

      git commit -m "<COMMIT_MESSAGE>"

      For example:

      git commit -m "Add a new file"

  6. If you need to update an existing file in the repository:

    1. Open the file that you want to update and make the necessary changes.

    2. Commit the changes to your local repository.

      git commit -m "<COMMIT_MESSAGE>" -a

      For example:

      git commit -m "Update the clauses in the terms and conditions file" -a

  7. If you are working with a branch instead of a tag, sync the upstream repository with your local branch.

    git remote add <REMOTE_NAME> <UPSTREAM_GIT_REPO_URL>

    git fetch <REMOTE_NAME>

    git merge <REMOTE_NAME/BRANCH_NAME>

    For example:

    git remote add wso2_upstream

    https://github.com/wso2/wso2-synapse.git

    git fetch wso2_upstream

    git merge wso2_upstream/refactoring

  8. Push the changes to your own Git repository.

    git push

  9. Send a Git pull request to the WSO2 Git repository.

  10. Create a patch that includes the URL of your Git pull request, as follows:

    1. Log in to WSO2's public JIRA system with your WSO2 user account credentials. If you do not have a WSO2 user account yet, you can quickly register for free at: https://wso2.com/user/register.

    2. Click Create issue.

    3. Select the project associated with your code changes, select Patch for the issue type, and then fill in the rest of the information describing the changes you submitted in your Git pull request and submit the JIRA. Be sure to include the URL of that pull request in the description. Also be sure to fill out and submit a contributor license agreement.

Your pull request will be authorized after it has been reviewed by the team lead, release manager, or responsible person for the corresponding Git repository.

© WSO2