Search

Contributing to JBoss Developer Framework

If you are interested in contributing to any of the projects that make up JBoss Developer Framework (quickstarts, examples, BOMs, migration guides, tools), then read on! We're serious about quality in JBoss Developer Framework, and we are strict about good quality code and documentation. But don't let that you put that off! If you follow this guide, then you should be in good shape :-)
  • Each sample project should have a unique name, allowing easy identification by users and developers
  • A sample project should have a simple build that the user can quickly understand. If using maven it should:
    1. Not inherit from another POM
    2. Import the various BOMs, either directly from a project, or from JBoss BOMs, to determine version numbers. You should aim to have no dependencies declared directly. If you do, work with the jdf team to get them added to a BOM.
    3. Use the JBoss AS Maven Plugin to deploy the example
  • The sample project should be importable into JBoss Developer Studio/JBoss Tools and be deployable from there
  • The sample project should contain a README.md file, explaining:
    • What the sample project demonstrates
    • How to build and deploy it
    • How to access it, and what the user should expect to see
    • How to to run the tests
    • How to deploy it to OpenShift, if necessary
    • Any special requirements (e.g. different server profile, changes to default server config)
  • The sample project should be formatted using the JBoss AS profiles found at http://github.com/jboss/ide-config/tree/master/
  • When writing asciidoc, and using delimited blocks, we recommend making the block 72 characters wide

Required accounts

JBoss Developer Framework uses a number of external services, a list of which follows. Some are SaaS and some are traditional hosting.

You'll need the right username and password for the services. Contact the project lead to get them.

You'll need access to some of these to perform releases.

Publishing builds to Maven

Some builds require you to publish artifacts to Maven:

  1. You must have gpg set up and your key registered, as described at http://www.sonatype.com/people/2010/01/how-to-generate-pgp-signatures-with-maven/
  2. You must provide a property gpg.passphrase in your settings.xml in the release profile e.g.

     <profile>
          <id>release</id>
          <properties>
              <gpg.passphrase>myPassPhrase</gpg.passphrase>
          </properties>
     </profile>
    
  3. You must have a JBoss Nexus account, configured with the server id in settings.xml with the id jboss-releases-repository e.g.

     <server>
         <id>jboss-releases-repository</id>
         <username>myUserName</username>
         <password>myPassword</password>
     </server>
    

Tool required to build jdf

Unlike many Java frameworks, JBoss Developer Framework has adopted the best tools it can find, regardless of the language in which they are written. So you'll need an array of Rubygems, Python eggs and more to build the site and guides. A number of Bash scripts hold it all together.

You'll need Bash 3 to run the scripts.

Unfortunately, this setup isn't overly friendly to Windows developers. We're looking at ways to address this.

Quickstarts

The quickstarts use Redcarpet to process the markdown, the same processor used by GitHub. This builds on the basic markdown syntax, adding support for tables, code highlighting, relaxed code blocks etc). We add a couple of custom piece of markup - [TOC] which allows a table of contents, based on headings, to be added to any file, and [Quickstart-TOC], which adds in a table listing the quickstarts.

To render the quickstarts README's you will need, a working Ruby and Python install, with the various gems and eggs set up. The easiest way to get it all working is to use the setup.sh script provided, which will install the correct gems and eggs. TODO put this script somewhere better. TODO add redcarpet to the script.

Just run

./dist/release-utils.sh -m

To render all markdown files to HTML.

Guides

The examples and migration guides use AsciiDoc.

To render the examples and migration guides, you'll need AsciiDoc, pygments and dblatex. The easiest way to get it all working is to use the setup.sh script provided, which will install the correct eggs, and AsciiDoc. TODO put this script somewhere better.

jdf site

The jdf site is built using awestruct, and requires a number of gems and eggs, as well as AsciiDoc.

At the time of writing, the site requires the gems: hpricot, awestruct, nokogiri, json, git, vpim, rest-client and pygments.rb. It also requires the eggs: pygments and yuicompressor. Check the setup.sh script for an up to date list. The easiest way to get it all working is to use the setup.sh script provided, which will install the correct gems and eggs.

Having got your environment correctly set up, run

awestruct -d

to run awestruct in development mode, and serve the site at http://localhost:4242. Note that current the jdf site doesn't work with awestruct 0.4.x.

When it comes to pushing changes, you can use the publish.sh script. There are three targets:

  • ./publish.sh -d will push the site to http://site-jdf.rhcloud.com, which we use as sandbox, for developing new features and sections for the site. You'll need access to the jdf OpenShift account, as described above.
  • ./publish.sh -s will push the site to http://jboss.org/jdf/stage, which use for staging changes to the site. Stage is normally reserved for verifying minor updates to the site, or for final verification before a major update. You'll need access to the jdf account on filemgmt.jboss.org.
  • ./publish.sh -p will push the site to http://jboss.org/jdf, the production site. You'll need access to the jdf account on filemgmt.jboss.org.

If you want to contribute a quickstart, follow these steps:

  1. Make sure you have reviewed the General Guidelines for JBoss Developer Framework.
  2. A template quickstart provided, that contains prompts for the content of the README.md and pom.xml. The template is located template/.
  3. Take a look at the quickstart ideas page (TODO link it), and put your name and email in the Owner/Email column and enter the date you hope to deliver the quickstart in the Target Date column.
  4. Take a look at Maven POM Versions Checklist if you want to add dependencies to your project
  5. Don't forget to update the pom.xml in the quickstart root directory. Add your quickstart to the 'modules' section.
  6. Each quickstart should specify metadata, using the conventions layed down. This allows the jdf site to parse the metadata, and allow users to easily search the quickstarts. The template README contains more. TODO Check it does.
  7. When your quickstart is ready for review, send a pull request to notify the JBoss Developer Framework team that your quickstart is ready for review. You can easily do this by clicking the 'Pull Request' at the top right side of your github page.

Testing the quickstarts

Most of the quickstarts require JBoss Enterprise Application Platform or JBoss AS only in standalone mode. Some require the "standalone-full" profile, some require XTS, some require Postgres and some require other quickstarts to be deployed. Profiles are used in the root POM to separate out these groups, allowing you to test the quickstarts easily. For example, to run those that require only standalone mode:

mvn clean install jboss-as:deploy jboss-as:undeploy -Parq-jbossas-remote -P-requires-postgres,-requires-full,-complex-dependencies,-requires-xts

Or, to run those only those quickstarts that require the full profile

mvn clean install jboss-as:deploy jboss-as:undeploy -Parq-jbossas-remote -P-requires-postgres,-default,-complex-dependencies,-requires-xts

And so on.

Quickstarts in other repositories

If your quickstarts are stored in another repository, you may wish to merge them in from there, rather than contribute them from source. If you plan to do this, discuss first with the JBoss AS Quickstarts team, as they will want to review all commits to your repo going forward.

To do this

  1. Add the other repo as a remote

    git remote add -f <other repo> <other repo url>
    
  2. Merge from the tag in the other repo that you wish to use. It is important to use a tag, to make tracking of history easier. We use a recursive merge strategy, always preferring changes from the other repo, in effect overwriting what we have locally.

    git merge <tag> -s recursive -Xtheirs --no-commit
    
  3. The merge is not committed, so any updates to the README.md and parent POM can be made. Having made these, perform the merge. We suggest updating the commit message to "Merge <Other Project Name> '<Tag>'".

    git commit
    
  4. Review and push to upstream

    git push upstream HEAD:master
    

Kitchensink variants

There are multiple quickstarts based on the kitchensink example. Each showcases different technologies and techniques including pure EE6, 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 l&f of the variants:

  • Follow the primary layout, style, and graphics of the original.
  • Projects can have 3-4 lines directly under the AS/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 plain text, bullet points, etc....
  • 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, wiki, tutorials, etc...
      • This should be below any AS/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.

If you want to contribute an example, follow these guidelines:

  • As an example is a large piece of work, we strongly encourage you to discuss your planned example on the dev list before starting.
  • Make sure you have reviewed the general guidelines for sample projects, to understand the basic guidelines you should follow.
  • Each example lives in its own repository. Take a look at TicketMonster as template repository.
  • Take a look at Maven POM Versions Checklist if you want to add dependencies to your project
  • When your quickstart is ready for review, let the JBoss Develoepr Framework team know on the dev list.

If you want to contribute a new stack, in the form of a BOM, follow these guidelines:

  • It can be tricky to work out when to add a new stack, rather than extend an existing stack. We strongly encourage you to discuss your planned BOM on the dev list before starting.
  • Each BOM is a child module of the parent BOM module. Copy an existing module as a template. Remember to give it a unique, and descriptive name. You should follow the conventions defined by the existing BOMs when naming it. All BOMs live in the same repository.
  • Most BOMs build on the base Java EE stack, and as such, import it. This is reflected in the name of the BOM "jboss-javaee6-with-XXX".
  • The BOM should contain a README.md file, explaining:
    • What the stack described by the BOM includes
    • An example of its usage
    • Any notes about plugins included in the stack
  • The BOM should be formatted using the JBoss AS profiles found at https://github.com/jboss/ide-configs/tree/master/ide-configs
  • When your BOM is ready for review, send a pull request.

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.

Java

/*
 * JBoss, Home of Professional Open Source
 * Copyright <Year>, 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.
 */

XML

<!--
 JBoss, Home of Professional Open Source
 Copyright <Year>, 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

 # JBoss, Home of Professional Open Source
 # Copyright 2012, 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.

Make sure you have set up your environment correctly to build the relevant project. Then, follow these steps:

Quickstarts

  1. Make sure you have access to rsync files to filemgmt.jboss.org/download_htdocs/jbossas
  2. Release the archetypes
  3. Regenerate the quickstart based on archetypes

    dist/release-utils.sh -r
    
  4. Release

    dist/release.sh -s <old snapshot version> -r <release version>
    

    This will update the version number, commit and tag, build the distro zip and upload it to <download.jboss.org>. Then it will reset the version number back to the snapshot version number.

TicketMonster

TODO

JBoss BOMs

To release, simply run:

./release.sh -s <old snapshot version> -r <release version>

This will update the version number, commit and tag and publish the BOMs to the JBoss Maven repository, and prompt to close and promote the Maven Nexus staging repository. Then it will reset the version number back to the snapshot version number. The artifacts will be replicated to Maven central within 24 hours.

jdf site

To release, simply run:

./release.sh -s <old snapshot version> -r <release version>

This will update the version number, commit and tag and publish the site to http://jboss.org/jdf. Then it will reset the version number back to the snapshot version number.