In a previous post, “How to Get Started Contributing to TomEE or any Open Source Project”, we explained the general workflow – things to do and steps to avoid – that can help you join and maximize your contribution to an Open Source Project. In this post, we will walk you through the technical steps one can follow to contribute to the Apache TomEE Website.
It’s common knowledge in any Content Management System (CMS), that the complexity of information organization is directly proportional to the amount, type and format of information an organization want’s to provide to the users. For Open Source Projects that want to provide examples, tutorials, documentation and source code, the usage of README files has been the defacto standard for providing to users guidance in collaboration and project usage. But the complexity increases when this task needs to be automated with CMS.
The Apache TomEE Site generator is a project in constant development that started 2 years ago to overcome this complexity. The following sections cover the technical steps needed to contribute to the project.
Information Workflow and Architecture
The TomEE site generator has a dependency on the TomEE project because the TomEE documentation and examples live next to the code in the same TomEE repository. The complexity increases because TomEE repository also provides different branches that correspond to each release including examples and documentation for tomee-8.0 , tomee-7.1, and documentation (Javadoc) related to microprofile-2.0 and jakartaee-8.0.
The CMS logic and static content management are provided by the TomEE site generator with the help of different frameworks: Asciidoctor, JGit, and JBake. In terms of prerequisites, the required software for working with the project are:
- Java 8
- Maven 3.3.9 or greater
- Git 2.7 or greater
Fork, Clone, and Run
The first step is to Fork the project into your GitHub account by navigating in a browser to https://github.com/apache/tomee-site-generator/ and click the Fork option in the top-right corner of the page.
Now you are able to create a local clone of your fork by typing on a terminal:
git clone https://github.com/YOUR-USERNAME/tomee-site-generator.git
It’s recommended that you configure Git to sync your fork with the original (upstream) repository:
cd tomee-site-generator
git remote add upstream https://github.com/apache/tomee-site-generator.git
To validate your setup, type:
git remote -v
You should get an output similar to:
origin https://github.com/YOUR-USERNAME/tomee-site-generator.git (fetch)
origin https://github.com/YOUR-USERNAME/tomee-site-generator.git (push)
upstream https://github.com/apache/tomee-site-generator.git (fetch)
upstream https://github.com/apache/tomee-site-generator.git (push)
To build and run the website in developer mode run the following command line:
mvn compile -Djbake.http=true
The website will be available on http://localhost:8080 after seeing a message in the logs similar to:
INFO: Deployed Application(path=)
Started on http://localhost:8080
Understanding the generated artifacts
When we build the website two folders are automatically generated
--tomee-site-generator/
------ repos/
------ target/
Execute the command line
tree repos/ -d -L 1
You should see all 37 directories downloaded from the internet repositories configured in Configuration.java class. Here is a snippet of directory listings:
├── common-annotations-api-EE4J_81.0
├── concurrency-api-EE4J_81.0
├── ejb-api-EE4J_81.0
├── interceptor-api-EE4J_81.0
├── jakartaee-8.0
├── jax-rpc-api-EE4J_81.0
...
├── security-api-EE4J_81.0
├── servlet-api-EE4J_81.0
├── tomee-7.0
├── tomee-7.1
├── tomee-8.0
└── websocket-api-EE4J_81.0
The target directory is generated by maven and contains two extra dirctories:
target/
├── apache-tomee266360256870392619-home
├── apache-tomee2741994937009924247-home
├── apache-tomee5559448424345223533-home
├── apache-tomee7034278256599706357-home
├── classes
├── generated-sources
├── generated-test-sources
├── javadocs
├── jbake
├── maven-archiver
├── maven-status
├── site-1.0-SNAPSHOT
├── surefire-reports
└── test-classes
The jbake directory contains the static content in .adoc and .md format processed from the repos folder. Part of this processed information is represented in the index.adoc files for the examples and other website sections like:
ls target/jbake/content/tomee-8.0/
docs/
es/
examples/
index.adoc
Notice that internationalization also is part of this process, in the above terminal output the /es folder contains all the examples in Spanish. More on how to contribute to translation will be cover later in this article.
The site-1.0-SNAPSHOT directory contains the actual HTML code generated from jbake folder content.
How to contribute new Examples and documentation
Contributions are done in the Tomee repo because that’s the place from were the TomEE Site Generator processes the README files. The git directory downloaded, for example, at tomee-site-generator/repos/master/examples/ demonstrates that this is actually a downloaded from TomEE master branch: https://github.com/apache/tomee/tree/master/examples
Since the TomEE site generator only processes the example REAMDE files, it’s recommended that you create a new example, it’s code, and README file on your local clone of TomEE and not the TomEE site generator.
Example Translation contributions
As described above, the Examples are part of the TomEE repository. Details about how to translate TomEE examples into different languages can be found in the TomEE repository:
https://github.com/apache/tomee/tree/master/examples#translation
Format and conventions
The preferred format is asciidoc with the following conventions for each document:
= My New Page
:jbake-date: 2017-03-16
:jbake-type: page
:jbake-status: published
:jbake-tomeepdf:
- One point
- Another point
=== Subtitle
Some content.
How to contribute with website static content
If you want to add a new document called videos, for example, to the section http://tomee.apache.org/community you just need to create the file /tomee-site-generator/src/main/jbake/content/community/videos.adoc with the following content:
= Videos
:jbake-date: 2010-02-07
:jbake-type: page
:jbake-status: published
:icons: font
=== Video tutorial 1
This is a new page.
And add the link for the new page in the community tomee-site-generator/src/main/jbake/content/community/index.adoc file:
= Community
:jbake-date: 2016-03-16
:jbake-type: page
:jbake-status: published
=== Contribute
- link:contributing/contribution-tips.html[Contribution tips]
- link:contributing/workflow.html[Contribution workflow]
- link:sources.html[Apache TomEE]
- link:contributing/website.html[This website]
- link:contributors.html[TomEE Wall Of Fame]
- link:videos.html[Video tutorials for contribution]
=== Social Media: cause contributing is not only about coding
Facebook, Twitter, Google+: if that speaks to you just follow this link:social.html[TomEE on Social Media].
=== Support
For more information about available support for TomEE please have a look on:
link:../security/support.html[Support] page.
Then you just need to rebuild the website:
mvn compile -Djbake.http=true
The new page should be listed in the Community index: http://localhost:8080/community/
And the new page should be available also directly: http://localhost:8080/community/videos.html
Productivity hint:
For development and short redeployment cycles you can delete the repos folder:
rm -rf repos/
And update the Configuration.java class to generate only the content from one repository and one specific branch:
package org.apache.tomee.website;
public class Configuration {
public static Source[] getSources() {
return new Source[]{
new Source("https://gitbox.apache.org/repos/asf/tomee.git", "master", "tomee-8.0", true)
};
}
}
Format and conventions
Is the same as described for documentation and examples.
Contributing to the Documentation Generation Process
The main logic used by JBake to generate the static content can be found in the sources.prepare(); call from the JBake.java code:
@RequiredArgsConstructor(access = PRIVATE)
public class JBake {
public static void main(final String[] args) throws Exception {
...
final Source[] website = org.apache.tomee.website.Configuration.getSources();
final Sources sources = new Sources(new File("target/jbake"), new File("repos"), new File("src/main/jbake"), destination, website);
sources.prepare();
...
The Sources.java class is the heart of the code that merges and transforms several documentation sources into one unique tree. This is the class responsible for:
- Creation of the source folder and download of the repositories configured in Configuration.java class.
- Creation of the
target/jbake/contentsubfolders containing the docs, examples, javadocs, and theindex.adocfor the different sections generated. This is also the class involved in organizing the example’s internationalization.
Wrapping Up
In this article, you discovered two different ways to contribute to the Apache TomEE Website: Documentation and Site Generation. If you want to find out more about the Contribution Workflow and Contributors Guidelines, check the Community section from the website and enjoy coding, reporting bugs, and reaching out with the vibrant TomEE community.
