Permalink
Fetching contributors…
Cannot retrieve contributors at this time
612 lines (498 sloc) 31.3 KB

JBoss Developer Contributing Guide

This document contains information targeted for developers who want to contribute to Red Hat JBoss Enterprise Application Platform developer projects.

Join the Mailing list

To monitor and participate in the latest development discussions, join the JBoss developer mailing list here: https://lists.jboss.org/mailman/listinfo/jbossdeveloper

Contribute a Quickstart

Purpose of the Quickstarts

  1. To demonstrate Java EE technologies.

  2. To provide developers with working examples and instructions that are easy to follow.

  3. To provide code examples to be copied by developers and used as the basis for their own projects.

Basic Steps

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.

  1. 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/wildfly/quickstart

    https://github.com/YOUR_USER_NAME/quickstart.git

    https://github.com/jboss-developer/jboss-brms-quickstarts

    https://github.com/YOUR_USER_NAME/jboss-brms-quickstarts.git

    https://github.com/jboss-developer/jboss-jdg-quickstarts

    https://github.com/YOUR_USER_NAME/jboss-jdg-quickstarts.git

    https://github.com/jboss-developer/jboss-mobile-quickstarts

    https://github.com/YOUR_USER_NAME/jboss-mobile-quickstarts.git

    https://github.com/jboss-developer/jboss-on-quickstarts

    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

  2. Clone your forked repository. This creates and populates a directory on your local file system, for example quickstart/ with the default remote repository name origin.

    git clone https://github.com/YOUR_USER_NAME/quickstart.git
  3. Navigate to the newly created directory, for example:

    cd quickstart/
  4. 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
  5. Get the latest files from the upstream repository.

    git fetch upstream
  6. Check out a local topic branch to work with your new quickstart, features, changes, or fixes.

    Important
    Always 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
  7. Contribute new code or make changes to existing files. Make sure that you follow the General Guidelines below.

  8. 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 Developer Studio and make sure it builds and deploys with no errors or warnings.

  9. 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
      Note
      It 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
  10. 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
  11. Commit your changes to your local topic branch.

    git commit -m 'Description of change...'
  12. 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.

  13. 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
    Note
    The above command assumes your own remote Git repository is named origin. You can verify your forked remote repository name using the command git remote -v.
  14. Browse to the TOPIC_BRANCH_NAME branch on your forked Git repository and create a Pull Request. Give it a clear title and description.

General Guidelines

  • 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, or org.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 a src/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 quickstart pom.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 example JBoss EAP Quickstart:.

    • QUICKSTART_NAME is the quickstart folder name

    • OPTIONAL_SUBFOLDER_NAME is the name of any nested subfolder that contains a pom.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 quickstart pom.xml file should match the quickstart name. For example, the <artifactId> for the greeter quickstart in the EAP project is greeter.

  • 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 quickstart pom.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 quickstart pom.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 the numberguess quickstart project.

  • You should be able to import the sample project into Red Hat Developer 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 Java EE spec 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 the template/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 parent pom.xml file.

  • The project must target Java EE 7 or Java EE 8.

    • CDI should be used as the programming model

    • Avoid using a web.xml file if possible. Use a faces-config.xml to activate JSF if needed.

    • Any tests should use Arquillian.

  • If the quickstart persists to a database, you must use a unique datasource JNDI name and connection URL for the application and for any Arquillian tests that it provides. Do not use the JNDI name java:jboss/datasources/ExampleDS. Failure to use unique names can result in a DuplicateServiceException when more than one quickstart is deployed to the same server.

  • Be sure to test the quickstart in Red Hat Developer Studio, which strictly enforces Java 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.

Kitchensink variants

There are multiple quickstarts based on the `kitchensink quickstarts example. Each showcases different technologies and techniques including pure Java 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.

License Information and Contributor Agreement

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.

Java, Javascript and CSS 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.
 */

HTML, XML, XSD and XHTML 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.
 -->

Properties files and Bash Scripts

 # 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.

SQL 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.
--

JSP 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.
--%>

Create a Quickstart README File

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.

Build the README.html Files

Follow these instructions to build the quickstart README.html files from the source README.adoc files.

  1. Navigate to the root directory of the quickstarts and type the following command to install the parent artifact.

    $ mvn clean install
  2. Navigate to the directory of the quickstart and run the following command.

    $ mvn clean generate-resources -Pdocs
    Tip
    You 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.

Build the Application Server

Follow these steps to build the application server and install the BOM artifacts.

  1. Clone the WildFly Application Server source from GitHub.

  2. Build the server using the following command.

    $ mvn clean install -DskipTests -Denforcer.skip=true -Dcheckstyle.skip=true
  3. Clone the WildFly BOMs source from GitHub.

  4. Build the BOMs using the following command.

    $ mvn clean install

You should now be able to build the quickstarts.

Create a Quickstart Cheat Sheet

Purpose of the Cheat Sheets

  • 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.

Basic Steps to Create a Cheat Sheet

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.
  1. Import your quickstart into Red Hat Developer Studio.

    1. From the menu, choose File -→ Import -→ Maven -→ Existing Maven Projects, then click Next.

    2. Navigate to your quickstart, select it, then click OK.

    3. Click Finish.

  2. Create the cheat sheet.

    1. Select the imported quickstart project.

    2. From the menu, choose File -→ New -→ Other -→ User Assistance -→ Cheat Sheet, then click Next.

    3. Select the quickstart folder, give it a name 'cheatsheet.xml', and choose Simple Cheat Sheet.

    4. Click Finish. When it prompts you to open the cheatsheet for the quickstart project, click Yes.

  3. Populate the cheatsheet with useful information to help a user understand the quickstart.

    1. Expand the Title in the content section on the left.

    2. Select the Title field and modify it to something useful, for example: helloworld

    3. Select the intro field and add introduction text to the Body, 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.
    4. Select item, then under Command, click browse and select 'Get current project' under Uncategorized. 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.

  4. 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.

  5. Test your cheat sheet by opening it in JDBS.

    1. Go through each step and make sure the descriptions are valid.

    2. Click on each link to make sure it opens the file and highlights the correct lines of code.

  6. 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.

  7. Add the .cheatsheet.xml file using git add, commit the change, push it to your forked repository, and issue a pull request.

  8. 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’s archetype-metadata.xml file. See the jboss-javaee6-webapp-archetype archetype for an example.

Quickstart Cheatsheet General Guidelines

  • 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 Developer Studio.

Find Quickstart Cheatsheet Help

You can find additional help about cheat sheets at the following locations:

Copy a Quickstart to Another Repository and Preserve Its History

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.

  1. Navigate to the parent directory of the quickstart you want to copy.

    $ cd ~/jboss-sandbox-quickstarts
  2. 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
  3. Create a temporary directory to contain the quickstart patch files.

    $ mkdir -p ~/temp/qsPatchFolder
  4. Create a QS_SOURCE environment variable that defines the quickstart source path.

    $ export QS_SOURCE=~/jboss-sandbox-quickstarts/xyz-quickstart/
  5. 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
  6. Navigate to parent directory where you want to move the quickstart.

    $ cd ~/quickstart
  7. 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
  8. Merge the patches into the destination directory.

    $ git am ~/temp/qsPatchFolder/*.patch
  9. 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.

  10. Issue a pull to the upstream repository, verify it is correct, and merge.