Creating a Carbon Kernel Patch

According to the WSO2 patch application process, the first step is to create a kernel patch by changing the code base and generating JAR files corresponding to those changes. This page explains the public patching model for Carbon kernel patches. These patches can be applied to a Carbon server as explained in Applying a Patch to the Kernel. Note that patch releases of WSO2 products based on Carbon are done using this public patching model. See Shipping a Kernel Patch with Distribution for details on how a patch is shipped with a product distribution.

Follow the steps given below to create a kernel patch.

Creating a JIRA issue for the kernel patch

Each patch has many fixes, so for each fix, you create a separate issue in the Carbon project of the public WSO2 JIRA database (http://wso2.org/jira). Be sure that each JIRA issue provides detailed information about that fix in the patch. Thereafter, add the links of the created JIRA issue to the README.txt file of the patch as described in creating a patch below.

Setting up the development environment

Before you do any development using the Carbon source code, be sure you have met the Installation Prerequisites and that you also have Subversion (SVN) and Apache Maven installed in your environment. You place your kernel patch fix in the kernel/branches/<version-number>/patches directory, which is where all patch-related information is stored for the kernel branch.

Example: Branch in svn/git for Kernel 4.1.0.

Creating a patch

1. Create the relevant patch folder (patch0001) under the kernel/branches/<version-number>/patches directory in svn/git.

2. Use the SVN copy function to copy the relevant components that have to be fixed into your patch0001 folder.
   

   Keep in mind the following:
   

   • When creating fixes, API changes are not allowed.

   • This patching process is only allowed in the repository/component/plugins directory.

3. Add the following .txt files to the patch0001 directory: 

   File  Name	Description
   README	This file includes the following details: 1. Patch ID (for example, WSO2-CARBON-PATCH-<version>-001). 2. Kernel version (for example, WSO2 CARBON<version>). 3. Associated public JIRAs. 4. Details about the fix.
   LICENSE	Details about Apache License 2.0 (http://www.apache.org/licenses/LICENSE-2.0.html)
   wso2carbon-version	Details about the Carbon server version (for example, WSO2 Carbon Framework v<version>patch001)

   The patch directory structure should now look like this:
   

4. If you are patching a component at the dependency level, create the dependencies directory (if it does not already exist) under kernel/branches/<version-number>/patches/patch0001.
5. Use the SVN copy function to copy into the dependencies folder the relevant dependency component that needs to be patched.
6. If the dependency includes an Orbit POM, create an orbit directory (if it does not already exist) under kernel/branches/<version-number>/patches/patch0001.

7. Use the SVN copy function to copy into the orbit folder the relevant orbit POM component that needs to be patched.

8. In the kernel/branches/<version-number>/patches/patch0001/distribution directory, create the assembly file (bin.xml), if it has not already been created. This file is responsible for aggregating and creating the patch file, that is, to copy the license, README, and wso2carbon-version.txt files along with the relevant, patched JARs from the target directories to the composite patch directory.
   
   Example assembly file: 
   

   <assembly>
       <includeBaseDirectory>true</includeBaseDirectory>
       <baseDirectory></baseDirectory>
       <id>carbon-patch-0001</id>
       <formats>
           <format>zip</format>
       </formats>
       <files>
           <file>
               <source>../org.wso2.carbon.core/target/org.wso2.carbon.core-4.1.0.jar</source>
               <outputDirectory>WSO2-CARBON-PATCH-4.1.0-0001/patch0001</outputDirectory>
               <destName>org.wso2.carbon.core_4.1.0.jar</destName>
               <fileMode>644</fileMode>
           </file>
           <file>
               <source>../wso2carbon-version.txt</source>
               <outputDirectory>WSO2-CARBON-PATCH-4.1.0-0001</outputDirectory>
               <fileMode>644</fileMode>
           <filtered>true</filtered>
           </file>
           <file>
               <source>../README.txt</source>
               <outputDirectory>WSO2-CARBON-PATCH-4.1.0-0001</outputDirectory>
               <fileMode>644</fileMode>
           <filtered>true</filtered>
           </file>
           <file>
               <source>../LICENCE.txt</source>
               <outputDirectory>WSO2-CARBON-PATCH-4.1.0-0001</outputDirectory>
               <fileMode>644</fileMode>
               <filtered>true</filtered>
           </file>
       </files>
   </assembly>

   For more information on the Maven assembly plugin, go to http://maven.apache.org/plugins/maven-assembly-plugin/.  
   For function definitions, go to http://maven.apache.org/plugins/maven-assembly-plugin/assembly.html.

9. Create the root POM  file in the kernel/branches/<version-number>/patches/patch0001/distribution directory, if it has not already been created. The root POM file builds the whole structure and calls the assembly plugin. When the POM file is created, first the components are built, and then the assembly plugin is called to create the patch ZIP file under the distribution directory.
   
   Example root POM file:

   <project xmlns="http://maven.apache.org/POM/4.0.0"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
   
       <parent>
           <groupId>org.wso2.carbon</groupId>
           <artifactId>carbon-parent</artifactId>
           <version>4.1.0</version>
           <relativePath>../../parent/pom.xml</relativePath>
       </parent>
   
       <modelVersion>4.0.0</modelVersion>
       <artifactId>WSO2-CARBON-PATCH-4.1.0</artifactId>
       <version>0001</version>
       <packaging>pom</packaging>
       <name>Distribution-Aggregate</name>
       <description>WSO2 Carbon Patch 0001 - Distribution</description>
       <url>http://wso2.org</url>
   
       <modules>
       <module>org.wso2.carbon.core</module>
       </modules>
   
       <build>
           <plugins>
               <plugin>
                   <groupId>org.apache.maven.plugins</groupId>
                   <artifactId>maven-assembly-plugin</artifactId>
                   <version>2.4</version>
                   <executions>
                       <execution>
                           <id>2-dist</id>
                           <phase>package</phase>
                           <goals>
                               <goal>attached</goal>
                           </goals>
                           <configuration>
                               <outputDirectory>distribution</outputDirectory>
                               <descriptors>
                                   <descriptor>${basedir}/bin.xml</descriptor>
                               </descriptors>
                               <appendAssemblyId>false</appendAssemblyId>
                           </configuration>
                       </execution>
                   </executions>
               </plugin>
           </plugins>
       </build>
   </project>

Sample patch directory

For example, if you want to patch the Axis2 kernel along with some other Carbon component (e.g., org.wso2.carbon.xxxx), the file structure should be as follows: