Note: If you are not building the thirdparty project from source, this is not the right page. Please follow the instructions in Uploading a Thirdparty Artifact
This page describes the process for patching (optional), building, and releasing a thirdparty project to the JBoss.org Maven repository.
For example, your project depends on a project from Apache and the Apache project has a known issue which you want to fix, but you are unable to apply the changes in a timely manner to the upstream Apache project.
For an example of a forked project, see the JBoss fork of Apache Xalan-J (https://github.com/jboss/xalan-j).
Step 1 Getting the Sources
The first step is to locate the upstream sources, and prepare a public repository to share any source changes. It is recommended to use git for any forked project because this will allow upstream changes to be easily tracked and incorporated into future releases. If the upstream sources are available at github, the repository can be forked to the jboss account or another public github account, and then cloned locally.
The next step is to create a branch at the point in history where the patches need to be applied. For example, you may want to branch from the "apache-1.0.1" release tag of the project.
git checkout -b jboss-1.0.1 apache-1.0.1
Step 2 Update the Project Build
The next step is to update the project build script (for example build.xml or pom.xml) to use a unique release version. The new project version should include a "jbossorg-<n>" qualifier.
Where x.y.z is the upstream version, and "n" is the number of times this project has been patched and released at jboss.org. The table below provides some examples.
|Patched?||Upstream Version||JBoss Version|
|Yes (first release)||1.0.1||1.0.1.jbossorg-1|
|Yes (second release)||1.0.1||1.0.1.jbossorg-2|
|Yes (first release)||1.0.1-beta-1||1.0.1-beta-1-jbossorg-1|
Note dot vs dash: The first character of the jbossog qualifier should be a dot if the upstream version does not already have a qualifier. If the upstream version already uses a qualifier, then a dash should be used instead. The reason for this is to maintain compatibility with the OSGi specification for version strings.
If the project does not contain existing POM files, these files should be created in a subdirectory called "maven" and added to source control. If the project does include POM files, these files should contain the minimum required configuration (Maven Project Configuration Requirements).
The scm information in the pom should be updated to point to the location of the forked sources if these sources are available in a public scm.
Step 3 Apply Patches and Build
The next step is to apply patches (if any) and then build the project.
As a courtesy to the members of the community (and to comply with the copyright licenses in many cases), the java source jar and the full source zip file should be uploaded to the repository along with the jar files. This source zip should use the classifier "source-release" and file type "zip".
For example, to upload the source jar (containing java sources):
mvn deploy:deploy-file -DpomFile=pom.xml -Dfile=commons-httpclient-3.1-1-jbossorg-sources.jar -DrepositoryId=jboss-releases-repository -Durl=https://repository.jboss.org/nexus/service/local/staging/deploy/maven2/ -Dclassifier=sources -Dpackaging=jar
To upload the full source zip (should include the POM and all sources required to rebuild the project):
mvn deploy:deploy-file -DpomFile=pom.xml -Dfile=commons-httpclient-3.1-1-jbossorg-source-release.zip -DrepositoryId=jboss-releases-repository -Durl=https://repository.jboss.org/nexus/service/local/staging/deploy/maven2/ -Dclassifier=source-release -Dpackaging=zip
Rebuilding for specific jvm targets
If the upstream project is being rebuilt in order to support a currently unavailable platform, an additional qualifier should be added to the version string. For example, if the upstream commons-httpclient jar only supports jdk1.5 and you want to build a jar using jdk1.6, the version string would include "-jdk_1_6".
Step 4 Deploy to the Repository and Release
The final step is to deploy the project to the JBoss.org Maven repository.
If the project uses a Maven based build, the "altDeploymentRepository" parameter of the maven deploy plugin can be used.
mvn deploy -DaltDeploymentRepository=jboss-releases-repository::default::https://repository.jboss.org/nexus/service/local/staging/deploy/maven2/
If the project build uses Ant or another build tool, the files can be deployed using the "deploy-file" goal of the maven deploy plugin. The poms should be created and added to source control in a "maven" directory. The binary, java-sources, and full sources should all be uploaded to the repository.
mvn deploy:deploy-file -DpomFile=maven/pom-myproject.xml -Dfile=build/myproject.jar -DrepositoryId=jboss-releases-repository -Durl=https://repository.jboss.org/nexus/service/local/staging/deploy/maven2/ mvn deploy:deploy-file -DpomFile=maven/pom-myproject.xml -Dfile=build/myproject-sources.jar -Dclassifier=sources -DrepositoryId=jboss-releases-repository -Durl=https://repository.jboss.org/nexus/service/local/staging/deploy/maven2/ mvn deploy:deploy-file -DpomFile=maven/pom-xalan.xml -Dfile=build/myproject-sources.zip -Dpackaging=zip -Dclassifier=source-release -DrepositoryId=jboss-releases-repository -Durl=https://repository.jboss.org/nexus/service/local/staging/deploy/maven2/
Once the files have been deployed, the steps to close and release the staging repository are described in Maven Deploying a Release