Setting up a Git Repository

With the git based model, releases can be made easy using the maven-release-plugin and nexus staging repository. The following are the common guidelines for releasing from any git repository under a WSO2 user.

Note that WSO2 approval is required for setting up git repositories under a WSO2 user. Also, this is a one-time process, which does not have to be repeated.

Step 1: Creating the repository

The following guidelines refer to carbon4-kernel as the sample project being released from git:

Create a “Repository Target” in http://maven.wso2.org/nexus/ that matches the groupID of the project and add a “Pattern Expression”. This pattern expression is used by nexus to automatically determine the staging profile. Shown below are the values used when creating a "Repository Target" for the carbon4-kernel project in git.

Name: org.wso2.carbon
Repository Type: Maven2
Pattern Expression: .*/org/wso2/carbon/.*
Create a nexus “Staging Profile” for the project in http://maven.wso2.org/nexus/, if it is not already created. The name of the profile should match the project's groupID. For example, the name of the profile for the carbon4-kernel project should be org.wso2.carbon.
1. Select the "Repository Target" that was created in step 1 above as the "Repository Target" for this profile.
2. Select the “Releases” repository in http://maven.wso2.org/nexus/content/repositories/releases/ as the “Release Repository” for all staging profiles.
3. Add “WSO2 Staging” to Target Groups. Make sure that “org.wso2.carbon” staging profile is the last entry in that list. You will have to move up the newly created profiles.
4. Finally, give the “wso2-nexus-deployer” user permissions to stage the repository as follows:
  1. “Staging: Repositories (<staging-profile-name>)”
  2. “Staging: Deployer (<staging-profile-name>)”
The main reason for creating a separate staging profile and repository target is for nexus to uniquely identify artifacts belonging to a staging profile. It uses the "groupID" of the artifacts. Nexus uses pattern matching for this purpose as explained above.

Setting up the "Staging Profile" as explained in the above steps will be handled by the WSO2 Infra team, for every project in the WSO2 git repository.

Step 2: Restructuring the POM files

Follow the instructions given below to restructure the pom files. Please use carbon-deployment as a reference project.

The top level pom file is the parent pom for your project and there is no real requirement to have a separate Maven module to host the parent POM file.

Eliminate the pom files available in the component, service-stub and features directories of your project. Instead, directly call the real Maven modules from the parent pom file. For example,

<modules>
        <module>service-stubs/service-mgt</module>
        <module>service-stubs/webapp-mgt</module>
        <module>components/service-mgt</module>
        <module>components/webapp-mgt</module>
        <module>features/as-runtimes</module>
        <module>features/service-mgt</module>
        <module>features/webapp-mgt</module>
 </modules>

You can keep the same directory structure to enhance human readability.

Make sure you have defined the following repositories (including plugin repositories) on the parent pom file. These will be used to drag SNAPSHOT versions of other Carbon projects that are used as dependencies of your project.

<repositories>
       <repository>
            <id>wso2-nexus</id>
            <name>WSO2 internal Repository</name>
            <url>http://maven.wso2.org/nexus/content/groups/wso2-public/</url>
            <releases>
                <enabled>true</enabled>
                <updatePolicy>daily</updatePolicy>
                <checksumPolicy>ignore</checksumPolicy>
            </releases>
        </repository>

        <repository>
            <id>wso2.releases</id>
            <name>WSO2 internal Repository</name>
            <url>http://maven.wso2.org/nexus/content/repositories/releases/</url>
            <releases>
                <enabled>true</enabled>
                <updatePolicy>daily</updatePolicy>
                <checksumPolicy>ignore</checksumPolicy>
            </releases>
        </repository>

        <repository>
            <id>wso2.snapshots</id>
            <name>Apache Snapshot Repository</name>
            <url>http://maven.wso2.org/nexus/content/repositories/snapshots/</url>
            <snapshots>
                <enabled>true</enabled>
                <updatePolicy>daily</updatePolicy>
            </snapshots>
            <releases>
                <enabled>false</enabled>
            </releases>
        </repository>
</repositories>

<pluginRepositories>

        <pluginRepository>
            <id>wso2.releases</id>
            <name>WSO2 internal Repository</name>
            <url>http://maven.wso2.org/nexus/content/repositories/releases/</url>
            <releases>
                <enabled>true</enabled>
                <updatePolicy>daily</updatePolicy>
                <checksumPolicy>ignore</checksumPolicy>
            </releases>
        </pluginRepository>

        <pluginRepository>
            <id>wso2.snapshots</id>
            <name>Apache Snapshot Repository</name>
            <url>http://maven.wso2.org/nexus/content/repositories/snapshots/</url>
            <snapshots>
                <enabled>true</enabled>
                <updatePolicy>daily</updatePolicy>
            </snapshots>
            <releases>
                <enabled>false</enabled>
            </releases>
        </pluginRepository>

        <pluginRepository>
            <id>wso2-nexus</id>
            <name>WSO2 internal Repository</name>
            <url>http://maven.wso2.org/nexus/content/groups/wso2-public/</url>
            <releases>
                <enabled>true</enabled>
                <updatePolicy>daily</updatePolicy>
                <checksumPolicy>ignore</checksumPolicy>
            </releases>
        </pluginRepository>

</pluginRepositories>

Update the project parent pom with the correct SCM configuration as shown below.

<scm>
   <url>https://github.com/wso2/carbon4-kernel.git</url>
   <developerConnection>scm:git:https://github.com/wso2/carbon4-kernel.git</developerConnection>
   <connection>scm:git:https://github.com/wso2/carbon4-kernel.git</connection>
   <tag>HEAD</tag>
</scm>

Then, remove all the scm configurations from the child poms.

You must have a <dependencyManagement> section on the project parent pom file, which defines all your project dependencies along with versions.

Note that you cannot have <dependencyManagement> sections on any other pom file other than the parent pom. When you add dependencies in the pom files of sub-modules, ensure that you don't specify the version, because it is already specified in the parent pom file under the <dependencyManagement> section.

In the parent pom file, define the scope for all dependencies used by product integration tests. See the following examples:
Example 1: Define the dependencies required for integration tests using the "tests" scope.

<dependency>
           <groupId>org.wso2.carbon</groupId>
           <artifactId>org.wso2.carbon.aarservices.stub</artifactId>
           <version>${stub.version}</version>
           <scope>test</scope>
</dependency>
<dependency>
           <groupId>org.wso2.carbon</groupId>
           <artifactId>org.wso2.carbon.webapp.mgt.stub</artifactId>
           <version>${stub.version}</version>
           <scope>test</scope>
</dependency>

Example 2: Dependencies without scope properties.

<dependency>
            <groupId>org.wso2.carbon</groupId>
            <artifactId>org.wso2.carbon.aarservices.stub</artifactId>
</dependency>

<dependency>
            <groupId>org.wso2.carbon</groupId>
            <artifactId>org.wso2.carbon.webapp.mgt.stub</artifactId>
</dependency>

Example 3: Overwrite the dependency scope with "compile" if you need to use test dependencies with java modules like common utility modules.

<dependency>
            <groupId>org.wso2.carbon</groupId>
            <artifactId>org.wso2.carbon.aarservices.stub</artifactId>
            <scope>compile</scope>
</dependency>
<dependency>
            <groupId>org.wso2.carbon</groupId>
            <artifactId>org.wso2.carbon.webapp.mgt.stub</artifactId>
            <scope>compile</scope>
</dependency>

Update the project parent pom with the WSO2 Master parent pom as shown below. The WSO2 Mater parent pom holds all the common things that are used in almost all the repositories, such as distributionManagement, pluginManagement, repositories, pluginRepositories, etc.
```
<parent>
    <groupId>org.wso2</groupId>
    <artifactId>wso2</artifactId>
    <version>1</version>
</parent> 
```
Make sure that your parent-child pom hierarchy is followed in all the sub-modules. That is, a child sub-module cannot have a parent pom reference to an external pom. The parent pom references should be self-contained except in the above instance, where the project root pom’s parent reference is set to the WSO2 Master parent pom ("org.wso2:wso2:1").
Add the plugins given below to the <build> section in the project parent pom. The versions of these will be inherited from the WSO2 Master parent pom.
```
<plugin>
       <groupId>org.apache.maven.plugins</groupId>
       <artifactId>maven-release-plugin</artifactId>
       <configuration>
           <preparationGoals>clean install</preparationGoals>
       </configuration>
   </plugin>
   <plugin>
       <groupId>org.apache.maven.plugins</groupId>
       <artifactId>maven-deploy-plugin</artifactId>
   </plugin>
```
Note: You can add the autoVersionSubmodules configuration parameter to release the plugin configuration section, which will automatically version the sub modules. However, please note that this will cause issues with versioning if your project has an orbit sub-module. This is because, for orbit modules, we follow a different versioning convention.
Remove <distributionManagement> from the project parent pom. This step is mandatory as the repositories for the <distributionManagement> section is inherited from the WSO2 Master parent pom.
Add a server config element in the maven configuration (<MVN_HOME>/conf/settings.xml) for the nexus-releases server configuration given above. The nexus user credentials that will be used for remote artifact deployment are as follows:
```
<server>
   <id>nexus-releases</id>
   <username>username</username>
   <password>password</password>
</server>
```
Note: For the above step, you can request WSO2 Infra to create a user for the project in nexus.
Add another server config element that stores the SCM related credentials. This is an optional step, but will be useful to hide your SCM credentials when using the mvn-release-plugin.
```
<server>
   <id>scm-server</id>
   <username>username</username>
   <password>password</password>
</server>
```
After adding the above, you have to update the parent pom properties section of your project with the following property: “project.scm.id”:
```
<properties>
    <project.scm.id>scm-server</project.scm.id>
</properties>
```
Make sure that the project does not have any SNAPSHOT dependencies and update those with released versions. If there are unreleased SNAPSHOT dependencies, we will have to release them separately. This will be checked by the release plugin during the release:prepare stage.
Then, make sure that you have properly parameterized the versions of dependencies. That is, the dependencies from the carbon-identity repository should have a version parameter called ‘carbon.identity.version’. It’s unacceptable to have a versions such as ‘carbon.platform.version’ or ‘wso2carbon.version’. You need version parameters according to the repo.