Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
..
Failed to load latest commit information.
_blog
_case-studies
_committers
_docs
_includes
_layouts
_meetups
_menu
_powered-by
_releases
_talks
archive
community
contribute
css
fonts
img
js
learn
less
meetups
powered-by
startup
talks
Gemfile
Gemfile.lock
Makefile
README.md
_config.yml
index.md
index.md.bak
sitemap.xml

README.md

Setup

Samza's documentation uses Jekyll to build a website out of markdown pages. Prerequisites:

  1. You need Ruby installed on your machine (run ruby --version to check)
  2. Install Bundler by running sudo gem install bundler
  3. To install Jekyll and its dependencies, change to the docs directory and run bundle install

To serve the website on localhost:4000:

bundle exec jekyll serve --watch --baseurl ""

To compile the website in the _site directory, execute:

bundle exec jekyll build

To test the site, run:

bundle exec jekyll serve --watch --baseurl ""

Versioning

If you're working with versioned content (anything in the learn or img directories), you'll also need to run a script that generates the appropriate directories:

  _docs/local-site-test.sh

The local-site-test.sh script must be run every time a change is made to versioned content locally in order to trigger a refresh with Jekyll.

Keep in mind that versioned content in older versions links to samza.apache.org, not the localhost:4000. This is because they are not updated by your branch and are using the values in SVN instead.

To add a new version, change the version number in _config.yml. All links in pages should use {{site.version}}, not hard-coded version number.

Javadocs

To auto-generate the latest Javadocs, run:

bin/generate-javadocs.sh

Publish

To build and publish the website to Samza's Apache SVN repository, run:

bin/publish-site.sh "updating welcome page" criccomini

This command will re-build the Javadocs and website, checkout https://svn.apache.org/repos/asf/samza/site/ locally, copy the site into the directory, and commit the changes.

Sanity-check a couple of links in the website corresponding to the latest release. For example, when releasing Samza 1.0.0, verify that http://samza.apache.org/learn/documentation/1.0.0/ and http://samza.apache.org/learn/documentation/latest/ links work.

Release-new-version Website Checklist

Assume we want to release x.x.x and the next release is y.y.y in master, need to work on two branches: x.x.x and master.

Following can be done when updating the gradle.properties file

  1. in x.x.x branch,

    • if this is a major release, modify the docs/_config.yml to make both the "version" and "latest-release" properties to x.x.x

    • remove "git checkout latest" line and the "-SNAPSHOT" version suffix in each of the tutorials

      • docs/startup/hello-samza/versioned/index.md
      • docs/learn/tutorials/versioned/hello-samza-high-level-code.md
      • docs/learn/tutorials/versioned/hello-samza-high-level-yarn.md
      • docs/learn/tutorials/versioned/hello-samza-high-level-zk.md
      • docs/learn/tutorials/versioned/samza-rest-getting-started.md
  2. in master branch,

    • if this is a major release, modify the docs/_config.yml to make the "latest-release" to x.x.x

    • if this is a major release, add the x.x.x release to Archive category in docs/_layouts/default.html and x.x.x release part in docs/archive/index.html

    • update the download page (docs/startup/download/index.md) to use x.x.x release

      • Add an entry to the Sources releases and Samza Tools section to use the new x.x.x release
    • update the version number in "tar -xvf ./target/hello-samza-y.y.y-dist.tar.gz -C deploy/samza" in each of the tutorials (and search for other uses of version x.x.x which may need to be replaced with y.y.y)

      • docs/startup/hello-samza/versioned/index.md
      • docs/learn/tutorials/versioned/hello-samza-high-level-yarn.md
      • docs/learn/tutorials/versioned/hello-samza-high-level-zk.md
      • docs/learn/tutorials/versioned/samza-rest-getting-started.md

After apache mirrors pick up the new release,

  1. in x.x.x branch, run bin/publish-site.sh "updating welcome page" criccomini

  2. in master branch, run bin/publish-site.sh "updating welcome page" criccomini