This document contains information targeted for developers who want to contribute to Red Hat JBoss Enterprise Application Platform developer projects.
-
Join the Mailing list: Sign up for the JBoss developer mailing list.
-
Contribute a Quickstart: Find out how to contribute a quickstart.
-
Create a Quickstart README.adoc File: Instructions on how to create a well structured and useful
README.adoc
file. -
Build the README.html Files: Build the README HTML file from its AsciiDoc source.
-
Build the Application Server: Build the application server from source and install the artifacts for the BOMs.
-
Create a Quickstart Cheat Sheet: Learn how to create a
cheat sheet
for your quickstart. -
Copy a Quickstart to Another Repository and Preserve Its History: Copy a quickstart from another location and preserve the commit history.
To monitor and participate in the latest development discussions, join the JBoss developer mailing list here: https://lists.jboss.org/mailman/listinfo/jbossdeveloper
-
To demonstrate Jakarta EE technologies.
-
To provide developers with working examples and instructions that are easy to follow.
-
To provide code examples to be copied by developers and used as the basis for their own projects.
To contribute to the quickstarts, fork the WildFly quickstart repository to your own GitHub, clone your fork, check out a topic branch from the master
branch, commit your work and push to your own repository, and submit pull requests back to the master
branch.
If you don’t have the GitHub client (git
), get it from: http://git-scm.com/
This document details the steps needed to contribute to the JBoss EAP / WildFly quickstarts. For other Red Hat product quickstarts, you need to replace the GitHub repository URL with the correct repository location.
-
Fork the WildFly quickstart repository for the appropriate product. This creates the project under your own GitHub ID. The following table lists the quickstart repository URLs and the resulting GitHub URL created by the fork.
Product Repository URL Forked Repository URL https://github.com/YOUR_USER_NAME/quickstart.git
https://github.com/YOUR_USER_NAME/jboss-brms-quickstarts.git
https://github.com/YOUR_USER_NAME/jboss-jdg-quickstarts.git
https://github.com/YOUR_USER_NAME/jboss-mobile-quickstarts.git
https://github.com/YOUR_USER_NAME/jboss-on-quickstarts.git
https://github.com/jboss-developer/jboss-picketlink-quickstarts
https://github.com/YOUR_USER_NAME/jboss-picketlink-quickstarts.git
-
Clone your forked repository. This creates and populates a directory on your local file system, for example
quickstart/
with the default remote repository nameorigin
.git clone https://github.com/YOUR_USER_NAME/quickstart.git
-
Navigate to the newly created directory, for example:
cd quickstart/
-
Add the remote
upstream
repository so you can fetch any changes to the original forked repository.git remote add upstream https://github.com/wildfly/quickstart.git
-
Get the latest files from the
upstream
repository.git fetch upstream
-
Check out a local topic branch to work with your new quickstart, features, changes, or fixes.
ImportantAlways work with the current developer branch of the quickstart repository. The is the branch that automatically displays in the dropdown when you browse to product quickstart directory. The default developer branch for the WildFly quickstarts is the master
branch.-
Fetch the latest source from Git, then check out the latest source code from the development branch of the upstream repository into your own branch using the following syntax.
git fetch upstream git checkout -b TOPIC_BRANCH_NAME upstream/master
For example:
git fetch upstream git checkout -b abc-quickstart upstream/master
-
If you are fixing a Bugzilla or JIRA, it is a good practice to use the number in the branch name. For new quickstarts or other fixes, try to use a good description for the branch name. The following are examples of Git checkout commands:
git checkout -b Bz-98765432 upstream/master git checkout -b JDF-9876543 upstream/master git checkout -b add-xyz-quickstart upstream/master
-
-
Contribute new code or make changes to existing files. Make sure that you follow the General Guidelines below.
-
Test your changes in 2 ways. Be sure to fix any checkstyle or build issues before you continue.
-
Run the Maven command line to build and deploy the quickstart.
-
Import the quickstart into Red Hat CodeReady Studio and make sure it builds and deploys with no errors or warnings.
-
-
Use the
git add
command to add new or changed file contents to the staging area.-
If you create a new quickstart, you can add files using the subfolder and file names. The following is an example of new quickstart folders and files you might want to stage:
git add src/ git add pom.xml git add README.adoc
NoteIt is probably best not to add the entire quickstart root folder because you might unintentionally add classes or other target files that should not be in source control. -
If you only modified a few files, use
git add FILE_NAME
for every file you create or change. For example:git add README.adoc
-
-
Use the
git status
command to view the status of the files in the directory and in the staging area and ensure that all modified files are properly staged:git status
-
Commit your changes to your local topic branch.
git commit -m 'Description of change...'
-
Update your branch with any changes made upstream since you started.
-
Fetch the latest changes from upstream.
git fetch upstream
-
Rebase to apply any updates to your branch.
git rebase upstream/master
-
If anyone has committed changes to files that you have also changed, you might see conflicts. Resolve the conflicted files, add them using
git add
, and continue the rebase:git add CONFLICTED_FILE_NAME git rebase --continue
-
If there were conflicts, it is a good idea to test your changes again to make they still work.
-
-
Push your local topic branch to your GitHub forked repository. This creates a branch on your Git fork repository with the same name as your local topic branch name.
git push origin HEAD
NoteThe above command assumes your own remote Git repository is named origin
. You can verify your forked remote repository name using the commandgit remote -v
. -
Browse to the TOPIC_BRANCH_NAME branch on your forked Git repository and create a Pull Request. Give it a clear title and description.
-
The sample project should be formatted using the JBoss EAP profiles found at http://github.com/jboss/ide-config/tree/master/
-
Code should be well documented with good comments. Please add an author tag (@author) to credit yourself for writing the code.
-
You should use readable variable names to make it easy for users to read the code.
-
The package must be
org.jboss.quickstarts.<product-type>
, for example:org.jboss.quickstarts.eap
,org.jboss.quickstarts.jdg
,org.jboss.quickstarts.brms
, ororg.jboss.quickstarts.fuse
. -
The quickstart project or folder name should match the quickstart name. Each sample project should have a unique name, allowing easy identification by users and developers.
-
The quickstart project or folder name should be located in the root directory of the product quickstarts repository and should not be nested under other quickstarts or folders. For example, if you create quickstart "foo" for the JBoss EAP quickstarts, it should appear here:
YOUR_PATH/quickstart/foo
. -
The quickstart directory structure should follow standard Java project rules:
-
All directories and packages containing Java source files should be placed in a
src/main/java/
directory, -
All Java source files should use package names.
-
Index pages, JSF, and HTML files should be placed in a
src/main/webapp/
directory. -
Any
beans.xml
,faces-config.xml
, and other related configuration files should be placed in asrc/main/webapp/WEB-INF/
directory. -
Resources such as images and stylesheets and the should be placed in the
src/main/webapp/resources
directory.
-
-
The
<name>
in the quickstartpom.xml
file should follow the template:${qs.name.prefix} QUICKSTART_NAME - OPTIONAL_SUBFOLDER_NAME
where:-
${qs.name.prefix}
is a property defined in the parent POM file that specifies the target product information, for exampleJBoss EAP Quickstart:
. -
QUICKSTART_NAME
is the quickstart folder name -
OPTIONAL_SUBFOLDER_NAME
is the name of any nested subfolder that contains apom.xml
file.The following are a few examples of quickstart pom files and the correct name tags:
Quickstart POM File <name> Element Value greeter/pom.xml
${qs.name.prefix} greeter
kitchensink-ear/pom.xml
${qs.name.prefix} kitchensink-ear
kitchensink-ear/ear/pom.xml
${qs.name.prefix} kitchensink-ear - ear
kitchensink-ear/ejb/pom.xml
${qs.name.prefix} kitchensink-ear - ejb
kitchensink-ear/web/pom.xml
${qs.name.prefix} kitchensink-ear - web
-
-
The
<artifactId>
in the quickstartpom.xml
file should match the quickstart name. For example, the<artifactId>
for thegreeter
quickstart in the EAP project isgreeter
. -
The quickstart parent POM file now includes
<repositories/>
and<pluginRepositories/>
elements to make it easier for developers to build the quickstarts without requiring additional Maven configuration. The quickstartpom.xml
file contains entries for the following repositories.Repository Description Repository ID and URL The online JBoss EAP product repository
ID: jboss-enterprise-maven-repository
The JBoss developer early access repository
ID: jboss-enterprise-maven-repository-ea
See the WildFly parent
pom.xml
file for an example of how to configure the<repositories/>
and<pluginRepositories/>
elements in a quickstartpom.xml
file. -
If you create a quickstart that uses a database table, make sure the name you use for the table is unique across all quickstarts.
-
The project must follow the structure used by existing quickstarts such as the
numberguess
quickstart. A good starting point would be to copy thenumberguess
quickstart project. -
You should be able to import the sample project into Red Hat CodeReady Studio/JBoss Tools and deploy it from there.
-
Maven POM files must be used. No other build system is allowed unless the purpose of the quickstart is to show another build system in use. If using Maven it should:
-
Not inherit from another POM except for the top-level parent POM.
-
Maven POMs must use the WildFly BOM/POM imports
-
The POMs must be commented, with a comment each item in the POM
-
Import the various BOMs defined in the JBoss EAP repositories. You should not declare dependencies directly. If you do need additional artifacts, contact the Quickstart team to get them added to a BOM.
-
Use the WildFly Maven Plugin to deploy the example.
-
-
The sample project must contain a
README.adoc
file using thetemplate/README.adoc
file as a guideline.-
Many common instructions are included in AsciiDoc files located in the shared-doc/ folder of the quickstart repository. Include those files if they contain the correct instructions for your quickstart.
-
Be aware that some of these AsciiDoc include files require that you define a document attribute to determine how to generate the instructions.
-
The
template/README.adoc
file shows the basic table of contents layout. -
When in doubt, try to find an existing quickstart that is similar to yours that you can use for guidance.
-
Be sure to build the README.html file from its AsciiDoc source to make sure it renders correctly.
-
-
Do not forget to add your quickstart to the
modules
section in the parentpom.xml
file. -
The project must target Jakarta EE 8.
-
CDI should be used as the programming model
-
Avoid using a
web.xml
file if possible. Use afaces-config.xml
to activate JSF if needed. -
Any tests should use JUnit.
-
-
If the quickstart persists to a database, you must use a unique datasource JNDI name and connection URL for the application and for any tests that it provides. Do not use the JNDI name
java:jboss/datasources/ExampleDS
. Failure to use unique names can result in aDuplicateServiceException
when more than one quickstart is deployed to the same server. -
Be sure to test the quickstart in Red Hat CodeReady Studio, which strictly enforces Jakarta EE coding rules!
-
If possible, create a cheat sheet for the quickstart to guide users and developers through the example. See Create a Quickstart Cheat Sheet for more information.
There are multiple quickstarts based on the `kitchensink
quickstarts example. Each showcases different technologies and techniques including pure Jakarta EE, JSF, HTML5, and GWT.
If you wish to contribute a kitchensink variant is it important that you follow the look and feel of the original so that useful comparisons can be made. This does not mean that variants can not expand, and showcase additional functionality. Multiple variants already do that. These include mobile interfaces, push updates, and more.
Below are rules for the look and feel of the variants:
-
Follow the primary layout, style, and graphics of the original.
-
Projects can have three to four lines directly under the JBoss EAP banner in the middle section to describe what makes this variant different. How projects use that space is up to them, but options include use of content such as as plain text, bullet points, and so on.
-
Projects can have their logo in the left side of the banner. The sidebar area can contain a section with links to the related projects, for example a wiki or tutorials. This logo should be below any JBoss EAP link areas.
If appropriate for the technology, the application should expose RESTful endpoints following the example of the original kitchensink
quickstart. This should also include the RESTful links in the member table.
JBoss Developer Framework is licensed under the Apache License 2.0, as we believe it is one of the most permissive Open Source license. This allows developers to easily make use of the code samples in JBoss Developer Framework.
There is no need to sign a contributor agreement to contribute to JBoss Developer Framework. You just need to explicitly license any contribution under the AL 2.0. If you add any new files to JBoss Developer Framework, make sure to add the correct header.
The following sections contain the correct header for various file types that you can copy and paste into your source files.
/**
* JBoss, Home of Professional Open Source
* Copyright 2018, Red Hat, Inc. and/or its affiliates, and individual
* contributors by the @authors tag. See the copyright.txt in the
* distribution for a full listing of individual contributors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
* http://www.apache.org/licenses/LICENSE-2.0
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
<!--
JBoss, Home of Professional Open Source
Copyright 2018, Red Hat, Inc. and/or its affiliates, and individual
contributors by the @authors tag. See the copyright.txt in the
distribution for a full listing of individual contributors.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
# JBoss, Home of Professional Open Source
# Copyright 2018, Red Hat, Inc. and/or its affiliates, and individual
# contributors by the @authors tag. See the copyright.txt in the
# distribution for a full listing of individual contributors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
# http://www.apache.org/licenses/LICENSE-2.0
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
--
-- JBoss, Home of Professional Open Source
-- Copyright 2018, Red Hat, Inc. and/or its affiliates, and individual
-- contributors by the @authors tag. See the copyright.txt in the
-- distribution for a full listing of individual contributors.
--
-- Licensed under the Apache License, Version 2.0 (the "License");
-- you may not use this file except in compliance with the License.
-- You may obtain a copy of the License at
-- http://www.apache.org/licenses/LICENSE-2.0
-- Unless required by applicable law or agreed to in writing, software
-- distributed under the License is distributed on an "AS IS" BASIS,
-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-- See the License for the specific language governing permissions and
-- limitations under the License.
--
<%--
JBoss, Home of Professional Open Source
Copyright 2018, Red Hat, Inc. and/or its affiliates, and individual
contributors by the @authors tag. See the copyright.txt in the
distribution for a full listing of individual contributors.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
--%>
The quickstart README.adoc
file must follow a strict format that is consistent across all of the quickstarts. This not only looks more professional, it also makes it much easier for developers to try out the quickstarts.
A template for creating a README.adoc
file for a new quickstart is located in the template folder of the WildFly and JBoss EAP quickstarts. It includes instructions for creating the required metadata as well as the content.
The quickstart shared-doc
folder contains files with instructions for common procedures that you can include in your project’s README.adoc
file. Some of these procedures can be customized by defining document attributes.
The easiest approach to get started with a new README file is to copy the README.adoc
file for a quickstart that uses similar instructions, and then edit the file for the new quickstart. Be sure to build the README.html file to verify that the README.adoc
file is formatted and renders correctly.
Follow these instructions to build the quickstart README.html
files from the source README.adoc
files.
-
Navigate to the root directory of the quickstarts and type the following command to install the parent artifact.
$ mvn clean install
-
Navigate to the directory of the quickstart and run the following command.
$ mvn clean generate-resources -Pdocs
TipYou can build all of the quickstart README files by running the above command in the root folder of the quickstarts. This also builds a table in the root README.html file that contains information about and links to each of the available quickstarts.
If you see errors like Non-resolvable import POM
or Could not resolve dependencies for project
when you build the README.html
file, it could mean that the quickstart uses a newly implemented WildFly application server feature and the artifacts have not yet been published to Maven. If that happens, you can try building the server and the BOMs as described below.
Follow these steps to build the application server and install the BOM artifacts.
-
Clone the WildFly Application Server source from GitHub.
-
Build the server using the following command.
$ mvn clean install -DskipTests -Denforcer.skip=true -Dcheckstyle.skip=true
-
Clone the WildFly BOMs source from GitHub.
-
Build the BOMs using the following command.
$ mvn clean install
You should now be able to build the quickstarts.
-
Cheat sheets function as a tutorial and provide a step by step guide through a quickstart.
-
They provide a way to step through and explain the code in an interactive way.
-
They can provide an in-depth analysis of specific sections of code.
You can create a cheat sheet using the Eclipse Wizard or you can copy and modify an existing cheat sheet from another quickstart. This section describes how to create a cheat sheet using the Eclipse wizard.
Important
|
Be sure your project folder is located outside of the Eclipse workspace before you begin this process. |
-
Import your quickstart into Red Hat CodeReady Studio.
-
From the menu, choose
File
-→Import
-→Maven
-→Existing Maven Projects
, then clickNext
. -
Navigate to your quickstart, select it, then click
OK
. -
Click
Finish
.
-
-
Create the cheat sheet.
-
Select the imported quickstart project.
-
From the menu, choose
File
-→New
-→Other
-→User Assistance
-→Cheat Sheet
, then clickNext
. -
Select the quickstart folder, give it a name 'cheatsheet.xml', and choose
Simple Cheat Sheet
. -
Click
Finish
. When it prompts you to open the cheatsheet for the quickstart project, clickYes
.
-
-
Populate the cheatsheet with useful information to help a user understand the quickstart.
-
Expand the
Title
in the content section on the left. -
Select the
Title
field and modify it to something useful, for example:helloworld
-
Select the
intro
field and add introduction text to theBody
, for example:This quickstart demonstrates the use of CDI 1.0 and Servlet 3.0. It is a simple application that can be used to verify the JBoss EAP server is configured and running correctly.
-
Select
item
, then underCommand
, clickbrowse
and select 'Get current project' underUncategorized
. This adds the following XML to the cheat sheet.<command required="true" returns="currentProject" serialization="org.jboss.tools.project.examples.cheatsheet.getProjectForCheatsheet"/>
This command allows you to use the variable
${currentProject}
instead of a hard-coded path name and ensures your cheat sheet will work regardless of the project location.
-
-
Add an
item
for each file or class you want to describe.-
This is dependent on the quickstart features you plan to demonstrate.
-
Provide a good description.
-
Add subitems to describe code sections and provide the line numbers that are referenced.
-
-
Test your cheat sheet by opening it in JDBS.
-
Go through each step and make sure the descriptions are valid.
-
Click on each link to make sure it opens the file and highlights the correct lines of code.
-
-
When you finish testing the cheat sheet, rename the file from
cheatsheet.xml
to.cheatsheet.xml
and make sure it is located in the root directory of the quickstart. -
Add the
.cheatsheet.xml
file usinggit add
, commit the change, push it to your forked repository, and issue a pull request. -
If your cheat sheet is for the quickstart based on an archetype, it automatically generates the cheat sheet for the archetype. However, you must add an
<include>.cheatsheet.*</include>
to the fileset for the root directory in the corresponding archetype’sarchetype-metadata.xml
file. See thejboss-javaee6-webapp-archetype
archetype for an example.
-
If your project folder is located in the Eclipse workspace when you generate your cheat sheet using the Eclipse wizard, it will generate an invalid project name and attempts to open source code will fail. Be sure your project folder is located outside the Eclipse workspace before you begin.
-
The cheat sheet should be created in the root of the quickstart directory and named
.cheatsheet.xml
. Eclipse does not let you name the file with a leading '.', so you need to rename it after it is created. -
Make sure you add the 'Get current project' command and use the replaceable
${currentProject}
value to avoid hard-coding the project path. This ensures that if the quickstart folder is moved, the cheat sheet will work as expected. -
Do not use the
<action>
tag if it can be avoided. It is more fragile than the<command>
tag, which uses parameters names instead of indexes. -
Try to highlight the most important features and code for the quickstart. Pay particular attention to areas that might confuse developers. Cheat sheets require that users execute or skip each step, so you don’t want to bore developers with the code that has no impact on the purpose of the quickstart.
-
Make sure
<?xml version="1.0" encoding="UTF-8"?>
is the first line in the.cheatsheet.xml
file, before the license information. This enables the cheat sheet to open automatically when you import the project into Red Hat CodeReady Studio.
You can find additional help about cheat sheets at the following locations:
Note
|
The following instructions are based on information in this blog: http://blog.neutrino.es/2012/git-copy-a-file-or-directory-from-another-repository-preserving-history |
This example copies the xyz-quickstart
quickstart that is currently located in the jboss-sandbox-quickstart
repository into the WildFly quickstart
repository, preserving its commit history.
-
Navigate to the parent directory of the quickstart you want to copy.
$ cd ~/jboss-sandbox-quickstarts
-
Make sure you have downloaded the latest source from the sandbox repository that contains the quickstart and then check out a branch to work in.
$ git fetch upstream $ git checkout -b copy-xyz-quickstart upstream/master
-
Create a temporary directory to contain the quickstart patch files.
$ mkdir -p ~/temp/qsPatchFolder
-
Create a
QS_SOURCE
environment variable that defines the quickstart source path.$ export QS_SOURCE=~/jboss-sandbox-quickstarts/xyz-quickstart/
-
Execute the following command to create the quickstart patch files in the temporary quickstart patch folder.
$ git format-patch -o ~/temp/qsPatchFolder $(git log $QS_SOURCE|grep ^commit|tail -1|awk '{print $2}')^..HEAD $QS_SOURCE
-
Navigate to parent directory where you want to move the quickstart.
$ cd ~/quickstart
-
Fetch the latest source code and check out a branch to work in.
$ git fetch upstream $ git checkout -b merge-xyz-quickstart upstream/11.x
-
Merge the patches into the destination directory.
$ git am ~/temp/qsPatchFolder/*.patch
-
Push the changes to your own Git.
-
Verify that the target quickstarts directory now contains the
xyz-quickstart
quickstart folder and files. -
Verify that the commit history is included.
-
-
Issue a pull to the upstream repository, verify it is correct, and merge.