Project Doc: MXNet Website 2.0 - Project Outline
Github Issue: https://github.com/apache/incubator-mxnet/issues/17798
Contributors: Sandeep Krishnamurthy, Connor Goggins
Introduction
With my latest changes, the MXNet website will support seamless switching between API versions 0.11.0, 0.12.1, 1.0.0, 1.1.0, 1.2.1, 1.3.1, 1.4.1, 1.5.0, 1.6, and master. Currently, no higher-order releases are ready for publication, but when they are this document will outline how to add the website builds for these future releases to the master website.
There are two options when it comes to adding releases to the master website, both of which are outlined in this document. The faster route is to create a static artifact, but if future changes to the release are expected it may make more sense to create a dynamic pipeline configuration for the release in question.
In addition, it is also required to update the Apache redirect rules that set the default website version. Please see following "Update Website Default Version" section for more details.
Also note: when hosting previews on an EC2 instance, follow the instructions here to configure the server. To make all routes work properly in the latest versions of the website (>= 1.6), it is also important to modify the file /etc/httpd/conf/httpd.conf and change all instances of AllowOverride none to AllowOverride All.
Static Artifact Publication
Add Menu Options
First, in the files header.html and header_top.html in the release branch, add an HTML <a> tag within the <div class="dropdown-content">. The contents of this new HTML <a> tag should be in the same format as the tags for other API versions. Your <a> tag should be under the <a> tag for master and above the <a> tag for the previous highest-order release (assuming your release is the new highest-order release - for older releases, add the new <a> tag so that the increasing version number order is preserved). Change the inline styling for color so that your new tag is the only one with orange-colored text (HTML color code #FF4500).
Add the new <a> tag to the same files in the master branch as well. For these additions on the master branch, the new tag color should be black (HTML color code #000000) while the master <a> tag should remain the only option with orange-colored text. You should then create a PR with your changes to the master branch.
Jenkins Artifact Generation
Navigate to the connor-website-build-master pipeline on the dev Jenkins instance and configure the pipeline to build your release branch. The compressed release artifact will be generated by this pipeline. Download the artifact, clone the artifact repository, and decompress the artifact into a subfolder within the versions/ folder with the title x.y.z/ (where x.y.z is the version number of the new release). Test the artifact repository for functionality with your changes on a local web server (with the web root at the root of the repository). Once you have confirmed that your changes work properly within the context of the artifact repository, create a PR for the artifact repository with your new artifact directory, compress the entire versions/ directory of the repository into versions.zip, and upload the compressed file to the MXNet Static Artifacts bucket.
Integrating with Production
Once both of your PRs are merged, trigger the restricted-website-build-master pipeline on the Jenkins prod instance. After this pipeline finishes, it will automatically trigger the restricted-website-publish-master pipeline. Your changes should be visible on the production website once the website publication pipeline finishes executing.
Dynamic Pipeline Setup
Add Menu Options
The process for completing this step should be the same as in the above instructions for Static Artifact Publication.
Jenkins Configuration
Test your changes via pipelines on the dev Jenkins instance by creating two new pipelines in the docs/ folder. First, copy my pipeline (connor-website-build-master) and create one new pipeline to build your new release branch (called website-build-x.y.z where x.y.z is the release version). Then, copy restricted-website-publish-master and modify it to integrate the output of your first new pipeline with the output of connor-website-build-master (the master build). This second pipeline should decompress the artifact generated by connor-website-build-master, then decompress the artifact generated by your new pipeline (the copy of connor-website-build-master) into a directory x.y.z/ (where x.y.z is the release version) within the versions/ directory of the decompressed master build.
If running these pipelines in series (release branch in parallel with master, then publisher to combine the two artifacts) results in a single artifact, the build has passed. Test the build on a local web server. If everything appears to be working, you are ready to integrate your changes with the production website.
Integrating with Production
Create similar pipelines on the prod Jenkins instance, but this time, instead of copying connor-website-build-master, copy restricted-website-build-master. Also, instead of copying restricted-website-publish-master you should modify that same pipeline to integrate the new release artifact in the same manner as in the dev pipeline. At this point, your changes (to both the master branch and your new release branch) should be fully merged into the main repository (apache/incubator-mxnet), and you should be ready to build the new master website with your changes.
Run the pipelines in the same order/configuration as on the dev instance, and you should be able to view your changes on the production website. Now, you can configure these pipelines to run on a regular interval so that any changes made to the release branch automatically propagate to the production website.
Update Website Default Version
When a user visits MXNet website from other domains, for example google search, typing url directly in browser, bookmark etc.. he/she will be redirected to the stable version of website. This redirect rule is imported in this PR which is to prevent frequent changes of contents in master branch from confusing our customers, see this Github issue.
When adding a new website release, update this line in .htaccess file under /docs/static_site/src/, link to target line in .htaccess file. Change the 1.x in RewriteRule ^(.*)$ /versions/1.6/$1 [r=307,L] to the next stable version.
# Set default website version to current stable (v1.6)RewriteCond %{REQUEST_URI} !^/versions/RewriteCond %{HTTP_REFERER} !mxnet.apache.orgRewriteCond %{HTTP_REFERER} !mxnet.incubator.apache.org# for future release for example 2.0# update this line to: RewriteRule ^(.*)$ /versions/2.0/$1 [r=307,L]RewriteRule ^(.*)$ /versions/1.6/$1 [r=307,L]