Rules of Thumb for fixing a JIRA at WSO2
Since WSO2 is an open source technology provider, anyone can contribute to its products if they are interested. This is about how you can contribute to our product-is in WSO2. While testing our Product-is, if you come across an issue, you are free to report the issue in the public Jira and contribute to our product.
To access our public Jira, first you need to have an account at WSO2. You can create an account here.
There are some rules of thumb for everyone for fixing a JIRA issue. I got to know those practices when I got my first bug-fix at WSO2 . Those rules help other developers to understand easily about the issue with the bug and the fix you made. These things are not mandatory but these are some best practices for a bug-fix.
20 Things you need to consider !
The steps that you should follow are given below.
- When you get a bug-fix, first make it assigned to you , made it in-progress .
2. So you can see the description of the bug in the JIRA. Then you should reproduce the bug according to the steps mentioned there. That means, you must try to produce that bug in the affected environment specially in the affected version mentioned in the JIRA .
- If you can’t reproduce the issue with the steps mentioned, seek help by sending a mail to dev@wso2.org. (If you want to send mail to dev@wso2.org, send a request mail to dev-request@wso2.org with subject as “subscribe”. Refer this )
3. Once you reproduced the issue, you can fill or change entries in the JIRA, like Type, Priority, Component/s, Labels etc, if any of them are not filled.
4. Then you should fork the repository. So it won’t affect the main repository. Because if you fork the main repository, you can merge that with the main repository after you fix the bug, without affecting the main repository.
5. Later you should clone your fork.
Eg: Clone the forked repository into your local machine using
- git clone <url> <directory>
- git clone https://github.com/piraveena/carbon-identity-framework.git
6. Then you point the pull url to the wso2 repository. This we do in order to indicate from which git repo you are going to pull the changes.
- git remote set-url <name> <url>
git remote set-url origin https://github.com/wso2/carbon-identity-framework
7. Point the push url to the your forked repository.This we do in order to indicate from which git repo you are going to pull the changes.
This we do in order to indicate that you are going to push changes to your repo.
- git remote set-url — push <name> <url>
git remote set-url -push origin https://github.com/piraveena/carbon-identity-framework.git
These set pull-url and push-url are (step 6 and 7) are important. Because it will indicate that you are going to pull changes from WSO2 main repo and push your changes to your repo.
If you forget to do these steps, then there are some possibilities of pushing your changes directly to main repo belongs to WSO2
8.Then you should narrow down the issue. Sometimes this is the most challenging step. That means, Once you reproduced the issue, now we know its not working as expected. So you have to pinpoint where the fix should be done and what the fix is. There are around 60 GitHub repository that contains the code of identity server. Its quite complex to find the correct repository for a novice. If you are wondering where the relevant code located, drop a mail to dev@wso2.org
9. Checkout to the correct branch (Eg : master). At sometimes the code in the master does not match with the release product jars. So you need to checkout to correct branch to debug. (For example, we use 5.x.x branch in product-is. So you should checkout to that branch from master)
- To figure out correct component branch, go to product repository (https://github.com/wso2/product-is) , select correct version tag (v5.3.0), open the root pom.xml file.
- Under the <properties> tag there are list of versions that indicates dependent component versions of each repository. Naming convention is hyphen (-)in the repository name replaced with dot (.)
- And suffix with “.version”.. For example https://github.com/wso2/carbon-identity-frameworkversion used in https://github.com/wso2/product-is/blob/v5.3.0/pom.xml listed as. <carbon.identity.framework.version>5.7.5</carbon.identity.framework.version>
10. Then create a fix-branch usually the fix-branch have the convention of JIRA ID.
- You should see the JIRA and check the ID of your bug-fix. In my case, it was IDENTITY-6153. You can see that ID in the JIRA.
- Likewise you can name your branch similar to the ID of the JIRA. So in the command line, you should use the command as “git branch IDENTITY-6153” and checkout to that branch using “git checkout IDENTITY-6153”.
- Or else you can create a new branch and checkout using a single git command “ git checkout -b IDENTITY-6153 master”
11. Then you should fix the bug and make sure that it follows the coding practices of WSO2.
12.After fixing the issue, test your code by building the jar and copy it into the product (copy it into the patch directory by creating a directory inside the patch directory)and restart the server.
13. After fixing the bug, write suitable automated tests(unit testing, OSGi testing, integration testing) to make sure the the flow you fixed does not broken by some other developer, even by yourself (:-)) in the future. Then run full test suite available to component, product to make sure the fix you have done does not break other flows.
14. After running the test cases, if that is successful, then commit the fix with commit message.
- The the git command is git commit -m “commit message”.
- so the commit message should be like this.
- IDENTITY<id of JIRA>:<space><a suitable title>
- So in my case, I used as git commit -m “IDENTITY-6153: Fix <OAuth2RevokeEPUrl> tag in identity.xml”
- If you feel that the fix needs some explanation add it as a long commit message. For adding a long commit, you can use, git commit and then add title and description for your commit message.
15. Then you should rebase with branch you originally derived from (Ex:-master). Because if someone pushed changes to that branch before creating your pull request, you will get the merge conflicts. So the git command will be “git rebase master” if the derived branch is master.
16. Then you can push to your repository by using fix-branch.
- Eg: git push -u origin IDENTITY-6153
17. Then create a pull request (PR) with the title same as the commit message you already used.
18. After creating the pull request, you should assign referees. Your pull request will be merged with the main repository after reviewed by at least one person.
- If there are any issues in your PR, the the reviewer will comment and you need to update your PR. Till the reviewer approve you PR, this will continue as a loop. Your PR will be merged with the main repository by the product team after a reviewer approves your PR.
19. Then you should comment in JIRA indicating the PR. It should be like Fixed with <link of the PR>. To get that link of the PR, click on view changes and copy the URL.
- Eg : Fixed with https://github.com/wso2/carbon-identity-framework/pull/936/files/89325413bd84f8bcbc1ae8e20d225d029a0de32f
20. If the fix introduces any UI changes or Documentation changes create JIRAs for them.
Following these rules of thumb will makes others to resolve the conflicts they face when they play with our WSO2 products. So I hope you all will follow and make life of others easy.
If you have any issues about how to contribute to product-is, feel free to drop a mail to dev@wso2.org..!
Learn, code!
