This document covers the various ways that a contribution can be made to JBoss Developer. If you need any help understanding any of the steps, or you want to discuss you contribution, then contact us.
#jboss-developer room on the irc.freenode.net IRC serverTo fix an issue:
Assign the JIRA issue to yourself if it isn't already
Fork the project. This creates the www.jboss.org project in your own Git with the default remote name 'origin'.
Clone your fork. This creates and populates a directory in your local file system.
git clone https://github.com/<your-username>/www.jboss.org.git
Change to the www.jboss.org directory.
Add the remote upstream repository so you can fetch any changes to the original forked repository.
git remote add upstream https://github.com/jboss-developer/jwww.jboss.org.git
Get the latest files from the upstream repository.
git fetch upstream
Create a local topic branch to work with your new quickstart, features, changes, or fixes.
git checkout -b <topic-branch-name> * 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 DEVELOPER-123
Contribute new code or make changes to existing files.
Use the git add command to add new or changed file contents to the staging area.
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. Make sure you put the JIRA ID in the commit message. This is used by our CI automation to comment and transition the JIRA Issue.
git commit -m 'DEVELOPER-123 Description of change...'
Update your branch with any changes made upstream since you started.
git fetch upstream
Apply those changes to your branch
git rebase upstream/master
If anyone has commited changes to files that you have also changed, you may see conflicts.
Resolve the conflicted files, add them using git add, and continue the rebase:
git add
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 will create 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 remote repository is named 'origin'. You can verify your forked remote repository name using the command `git remote -v`.
The Pull request will then be reviewed by the JBoss Developer team, and you may be requested to make changes. To make a change:
Push your branch to your fork on GitHub:
git push origin DEVELOPER-123
Currently we have a number of different types of developer materials that can be searched from www.jboss.org/developer-materials. These are described as follows:
The following sections summarise how to contribute developer materials.
To contribute a new Quickstart to JBoss Developer:
To contribute an update (e.g bug-fix, typo-fix etc) to an existing quickstart:
If you have a repository of quickstarts that you think would be appropriate for JBoss Developer, then contact us.
A demo is aimed more at demonstrating the features of a product, than at showing how to use a single API or use case. It is also more flexible in its structure and scope. This is in contrast to a quickstart that must follow a very strict structure and needs to be limited to using a minimal amount of technologies.
See the Demos contributing guide for more details.
If you have a Tutorial that you think would be appropriate for JBoss Developer, then contact us.
This process is used for contributing details of a Vimeo or YouTube video.
JBoss Developer account.+ Collections
Miscellaneous if it relates to no product. Note: You will see several albums, only those entitled Red Hat JBoss ... are product albums.Add the URL of the video to the "YouTube Videos" sheet of this spreadsheet: https://docs.google.com/spreadsheets/d/1QbjVeU9avP8hcnaruiLtuanQVpkdClIYtgFSmaC_K9c/edit#gid=1504333800
Note: YouTube videos cannot yet be associated with products.
create
Developer materials, such as quickstarts and tutorials (Ticket Monster) can be updated to use a new version by completing the following steps. EAP quickstarts are used here as an example:
Go to your checkout of this repo and create a new branch for the change:
git checkout -b DEVELOPER-123
Change to the directory containing the developer materials to update:
cd _eap-quickstarts
Fetch the changes to the quickstart repo
git fetch origin --tags
Checkout the new tag
git checkout 6.2.0.GA
Move back to root directory
cd ..
Add and commit the changes
git add .
git commit -m "DEVELOPER-123 Update EAP quickstarts t0 version 6.2.0.GA"
Push the branch to your fork of this repo. Assumed to be 'orgin'
git push origin DEVELOPER-123
If Ticket Monster has released a new version, the download link in ticket-monster.adoc and the documentation link in _layouts/ticket-monster.html.slim need to be manually updated as well. Follow the above process for creating a git branch and assigning a JIRA ticket. Open the ticket-monster.adoc file and find the correct DOWNLOAD IT link, retreive the new link from GitHub and modify the document. Then follow the above instructions for adding the change, pushing the branch and creating a new pull request.
A particular developer material can be highlighted on the main developer materials page. For example, notice the banner visible on the Developer Materials page. To change this:
On approval of the change:
_config/featured_items.yml. Changing:
2.1 image_url: This is the address of the graphic created by the DESIGN JIRA issue and linked in the DEVELOPER issue.
2.2 title: The title of the item being linked to.
2.3 text: A short description of the item being linked to. Most likely the text from the image.
2.4 url: A url to the developer material's details page on www.jboss.org.The product pages are those linked from www.jboss.org/products. This section covers the various contributions that can be made to these pages.
description for the release. E.g: Minor release of JBoss EAP 6.x series
tag_line for the release. E.g: Features an updated administrative console that includes a new homepage and exposes the new JBoss EAP patching feature. Also includes domain recovery improvements and support for CDI injection with PicketLink. Try it today!
date of the release.First add the downloads to the Download Manager.
The following steps are currently required, but will no longer be when the downloads are automatically fetched from the download manager.
product.yml file. As an example here is JBoss EAP's product.yml
current_version: field in the product.yml only if you are adding a GA release (i.e. not an Alpha or Beta).http://www.jboss.org/download-manager/file into the associated Short URL field of the download item in the Download Manager. Take a look at existing downloads for examples. Remember the preceding / character. A particular developer material can be highlighted on each product's developer materials page. For example, notice the banner visible on the EAP Developer Materials page. To change this:
On approval of the change:
featured_items entry in the product's product.yml file (e.g. for EAP: /products/eap/_common/product.yml). Changing:
2.1 image_url: This is the address of the graphic created by the DESIGN JIRA issue and linked in the DEVELOPER issue.
2.2 title: The title of the item being linked to.
2.3 text: A short description of the item being linked to.
2.4 url: A url to the developer material's details page on www.jboss.org.Other changes to the product pages should go through the following process. Multiple changes should be done separately, rather than grouped together as one big change. This makes it easier to discuss the changes individually and aids scheduling of non-trivial changes. If you are requesting a series of text changes, then putting them in a single issue will probably be fine.
See the EAP Product Overview Page on the right-hand-side for an example of the training links.
featured_training.adoc file. E.g. see EAP's featured_training.adoc file.See the EAP Product Overview Page on the right-hand-side for an example of the Webinars links.
/images/products/. You can probably grab a thumbnail from the webinar's details page.featured_webinar.adoc file. E.g. see EAP's featured_webinar.adoc file. Use existing links as an example of the format.See the EAP Community Page, towards the bottom is a list of all upstream projects included in this product. To add or remove from this list:
upstream_projects key in the product's product.yml file. As an example, here is JBoss EAP's product.yml
Upto three videos can be added to the 'Featured Videos' area. To add/remove them:
To add/remove item(s) in the 'More Resources' area of the 'Resources' page:
resources.adoc file to add/remove the item. See JBoss EAP's resources.adoc file for an example.The upstream projects page is located at http://www.jboss.org/projects. This section covers details on how to make changes to the data visible on this page.
If you provided a project properties file:
projects page.Otherwise, the data is being pulled from the project's Magnolia page:
projects page.By default, project data is pulled from the project's Magnolia page. To start using a project.properties file for your project:
To change the icon currently displayed for a project on www.jboss.org/projects:
design account, upload it to the project's directory on filemgmt.jboss.org. For example, the AeroGear logo is located at: filemgmt.jboss.org:/static_htdocs/aerogear/images/aerogear_200x150.png. Take care to follow the exact format as the image links are generated.This section covers miscellaneous contributions that can be made.
To have a new Event added to the Events page and (optionally) the homepage:
If you don't have access:
To add a book to www.jboss.org/books:
If a book entry on www.jboss.org/books is missing data or is displaying incorrect data, then:
To request a change to the banner on the homepage:
On approval of the change:
.large-24.slide section represents an individual banner in the carousel in the order it shows on the site.
2. Either replace an existing item, or add a new one in the right place.
3. Remember to remove any old images if you remove the item from the carousel.
4. Remember to set the link, image and alt text for the banner you are adding.The simplest way to create a solution is to use the default template and drop in pieces of text and images into the place-holders. Look at the example solution code for what is required.
See the Unified Push Solution's code for an example that uses an entirely custom layout. The Docker Solution code provides an example of where the default layout was used, but with an additional custom layout section at the bottom. Look at the live Docker page and notice that above the "Available Docker Images" title is using the default layout and under this title is a custom layout.
To create a solution:
solution.yml fileThis file is used to configure various aspects of your solution.
The following table describes the purpose of each key. Note: items marked with a (*) are required.
| Key | Value |
|---|---|
| name* | The name is used as a short title to identify your solution in a variety of places on the site. Keep it short and human readable. |
| sub_title | An optional sub-title that will appear under the main title on the Solution's main page. |
| long_description* | A long description to show when the user clicks on the Solution in the all Solutions page. |
| overview_links | An optional list of links to show when the user clicks on the Solution in the all Solutions page. |
| speech_bubble | An optional speech bubble to show towards the top of the Solution's main page. |
| image_link | An optional link to display under the Solution's logo towards the top of the Solution's main page. |
| related_solutions | An optional list of related solutions to show down the right-hand side of the Solution's main page. Solution IDs are used to identify each related Solution. |
index.adoc FileThis file provides the majority of the content to that is displayed on the Solution's main page. A default layout is used.
Note that level two headings (identified by the preceding '==') are keys used to identify fragments of content. Headings at a greater level than two (E.g '===') can be used to place headings in your content. The following table describes the purpose of each key. Note: all items are optional.
| Key | Value |
|---|---|
| Overview | Content to replace the 'speech bubble' if it was removed from the solution.yml file. |
| Left Section | Content to be placed in the left-hand side of the double column area. |
| Right Section | Content to be placed in the right-hand side of the double column area. |
| Extra Section Title | The title to use for an extra section that is displayed under the double column area |
| Extra Section | The content to place under the extra section title |
Note: The solution logo will only appear on the Solution's main page if either the 'speech bubble' or 'overview text' is provided.
Custom layouts can be added below the content displayey by the default template. This is automatically added when the Solution's template is present. For example, create: _partials/solution-partial-mysolution.html.slim. See the other _partials/solution-partial-*.html.slim files for examples.
You can fully customise the layout of the Solution's main page by removing all the optional sections from the index.adoc file and the speech_bubble from the solution.yml file and then provide a layout file in the _partials directory.
Microsites can either be single paged or multi-paged. Take a look at the following mockups to see which variation meets your needs.
| Type | Description | Resources |
|---|---|---|
| Single Page | A single page microsite, with no sub-navigation | Live, Source |
| Multi-page | A multiple-page microsite with a single level of sub-navigation | Live, Source |
Before creating a Microsite, please contact us to ensure that a 'Microsite' is the right place for your content.
The following constraints are imposed on JBoss Developer Microsites in order to retain consistency and to make them fit within the JBoss Developer brand.
To create a new single page microsite at www.jboss.org/<microsite_id>:
microsite.html.slim to <microsite_id>.html.slim
Note: This section is un-tested as JBoss Developer doesn't currently host any multi-page microsites.
To create a new multi-page microsite at www.jboss.org/<microsite_id>:
<microsite_id> directorymicrosite-multi-page.html.slim to <microsite_id>/index.html.slim
nav: section of <microsite_id>/index.html.slim to specify the navigation to each of the sub pages<microsite_id>/index.html.slim for each of the sub-pages. E.g. <microsite_id>/my_subpage.html.slim./images/<microsite_id>/<microsite_id>_microsite_hero.jpg
Create a Sass Stylesheet at stylesheets/_<microsite_id>.scss. You can add your own styles here, but do so with care as this stylesheet will be loaded for the entire JBoss Developer site. Minimally, this stylesheet needs to specify the banner graphic and should contain the following. Replace the <microsite_id> text with the id of your Microsite.
.wide-hero.<microsite_id> {
background: cdn('../images/<microsite_id>/<microsite_id>_microsite_hero.jpg');
}
Import the stylesheet into stylesheets/app.scss by adding the following import line after the existing imports:
@import "<microsite_id>";
Add the following line to the header section of <microsite_id>.html.slim (for single page microsites) or <microsite_id>/index.html.slim for multi-page microsites.
hero_class: <microsite_id>
This documentation covers http://www.jboss.org/heroes/
If you have a general change that doesn't fall into the categories above, create a JIRA issue.
contact us for general feedback that doesn't constitute a bug report or feature request.
If you find a bug on www.jboss.org or if you have a feature request, please file a JIRA issue.