This is the source for the Release specific part of the Apache Storm website and documentation. It is statically generated using jekyll.
This website is build using Jekyll. Make sure to have it available locally. To build and run server locally type 'jekyll serve'. The site can then be accessed at localhost:4000.
You can build the website for local testing by running
docker compose up localFirst install jekyll and bundler (assuming you have ruby installed):
gem install jekyll bundler
Fetch/update site dependencies
bundle install
Generate the site, and start a server locally:
bundle exec jekyll serve -w
The -w option tells jekyll to watch for changes to files and regenerate the site automatically when any content changes.
Point your browser to https://localhost:4000
By default, jekyll will generate the site in a _site directory.
In order to add a new release, you must have committer access to the storm-site repository at https://github.com/apache/storm-site.
You must first generate Javadoc for the new release. Check out the Storm repository from https://github.com/apache/storm, and check out the version of the code you are releasing.
You must have already installed the storm-shaded-deps module, so please run mvn clean install -pl storm-shaded-deps -am if you haven't built Storm already.
In the Storm project root run
mvn javadoc:aggregate -DreportOutputDirectory=./docs/ -DdestDir=javadocs -Dnotimestamp=true -pl '!storm-shaded-deps'
In the storm-site project, release documentation is placed under the releases directory named after the release version. See below for details about release specific documentation.
To add documentation for a new release, run the following from the Storm project root
mkdir ${path_to_storm_site}/releases/${release_name}
#Copy everything over, and compare checksums, except for things that are part of the site,
# and are not release specific like the _* directories that are jekyll specific
# assets/ css/ and README.md
rsync -ac --delete --exclude _\* --exclude assets --exclude css --exclude README.md ./docs/ ${path_to_storm_site}/releases/${release_name}
cd ${path_to_storm_site}
git add releases/${release_name}
git commit
If the release is the latest release, i.e. the release with the highest version number, you should also update the releases/current symlink to point to the new release. Run the following from the storm-site/releases directory.
ln -f -n -s ${release_name} current
Compose a new blog post announcement for the new release on the _posts folder. You can use the RELEASE_NOTES.html file generated on storm project to retrieve the specific HTML for this version.
Update the downloads page on downloads.html to point to the new version's links.
Release specific documentation is controlled by a jekyll plugin releases.rb.
The plugin will look in the releases directory for release specific docs.
Each sub directory is named after the release in question. The "current" release is pointed to by a symlink in that directory called current.
The plugin sets three configs for each release page.
- version - the version number of the release/directory
- git-tree-base - a link to a directory in github that this version is on
- git-blob-base - a link to to where on github that this version is on, but should be used when pointing to files.
The version is determined by the name of the releases/${release_name} sub-directory and branch is assumed to be a "v#{version}" which corresponds with our naming conventions. For SNAPSHOT releases you will need to override this in _data/releases.yml
The plugin also augments the site.data.releases dataset.
Each release in the list includes the following, and each can be set in _data/releases.yml to override what is automatically generated by the plugin.
- git-tag-or-branch - tag or branch name on github/apache/storm
- git-tree-base - a link to a directory in github that this version is on
- git-blob-base - a link to to where on github that this version is on, but should be used when pointing to files.
- base-name - name of the release files to download, without the .tar.gz
- has-download - if this is an official release and a download link should be created.
So if you wanted to create a link to a file on github inside the release specific docs you would create a link like
[LICENSE]([DEVELOPER.md]({{page.git-blob-base}}/LICENSE)
If you wanted to create a maven string to tell people what dependency to use you would do something like
<dependency>
...
<version>{{version}}</version>
</dependency>
If you want to refer to a javadoc for the current release use a relative path. It will be in the javadocs subdirectory.
[TopologyBuilder](javadocs/org/apache/storm/topology/TopologyBuilder.html)
This website uses the typical ASF layout. The actual website is found on the branch asf-site, any changes need to be pushed there.
You can run
docker compose up buildwhich will create a folder _site. This is the content, which needs to be copied after wards to the asf-site branch.
If you wish to see a preview for your branch, you can use asf-staging to see a copy hosted under: https://storm.staged.apache.org/
The website is automatically build on a push to main and any changes are pushed to the asf-site branch.
A preview is available via https://storm.staged.apache.org/ if you go to the GitHub Actions tab and trigger a manual staging deploy action.