Committers and contributors are all welcomed and encouraged to update the Mahout website.
Mahout uses Jekyll to build the website. A script
is executed by Jenkins after any change is detected in the master branch of the official Apache repository (
e.g. after any PR is merged ). As such it is important that you, and any reviewers stage site changes locally before
committing.
The process for updating the website is as follows:
git clone http://github.com/apache/mahout
See Building from Source for more details.
Jekyll uses Kramdown to compile markdown into HTML.
Kramdown syntax is very similar to standard markdown, but with a few subtle diferences, please review to the Kramdown syntax guide.
Mahout is a highly mathematical project, and contributors will often want to use LaTeX Mathematics
to explain concepts. While in some environments this is signalled to the compiler with \( ... \) in Kramdown
LaTeX portions are signalled with enclosing $ characters, e.g. $$ ... $$
This step actually can be done while you are editing. Then you can see you changes in near-real time (pending browser refreshes).
In the terminal,
cd website
bundle exec jekyll serve
By default this will serve the website locally at http://127.0.0.1:4000/. You can open your favorite browser and make sure your changes look the way you expect them to.
Once you’re sure everything is right, you commit your code, push to your github.com account (preferably on a branch other than trunk
then click “OpenPR”). This process closely follows How To Contribute- Making Changes with an exception that for WEBSITE ONLY changes we relax the requirement to open a JIRA ticket. That is to say, small
website changes such as fixing a broken link or typo, do not require a specific JIRA issues, and where you would normally
commit with a message like MAHOUT-XXXX The thing I did (where XXXX is the assosciated JIRA number), you can instead
simply create a message like WEBSITE Typos in how-to-update-the-website.md. There’s nothing to stop you from making a
JIRA issue, it simply isn’t required.
The same goes for when you open a PR (where conventionally one includes the JIRA issue, you can again title WEBSITE to indicate
there is no JIRA)
A committer will be along shortly to review your changes, please be patient. In the meantime, feel free to help us out by reviewing other contributors PRs. (Here’s a little secret, this is a great way to signal to us that you’re interested in becoming a committer too, as PR reviews is a big part of a committer’s job).
Once everything is confirmed to be in order, the committer will merge your pull request.
No further action is needed, this section is here to deliniate from the old CMS system and Jekyll builds of other projects. Jenkins
will execute build_site.sh upon merging. This will build the website and
copy it to the asf-site branch, where mahout.apache.org is served from.