Merge branch 'documentation-in-release' of https://github.com/PramodSSImmaneni/incubator-apex-site
diff --git a/src/md/release.md b/src/md/release.md
index 6701603..a5ad9b0 100644
--- a/src/md/release.md
+++ b/src/md/release.md
@@ -150,6 +150,57 @@
svn import svn-dist https://dist.apache.org/repos/dist/dev/apex/${RNAME}-RC1 -m "Apache Apex v${rv}-RC1"
```
+## Build and Deploy Documentation
+
+The documentation will be generated as static HTML files and copied into the `apex-site` repository. It will be available at an alternate URL path until the release is promoted, at which time it will also be promoted to the main website location.
+
+Do the following setup steps before building and deploying the documentation.
+
+1. Clone the apex-site repository into a folder called ```apex-site``` at the same level as the current repository.
+
+2. Set the following environment variables.
+
+ For -core releases:
+
+ ```
+ REPO_NAME=apex-core
+ DOC_NAME=apex
+ ```
+
+ For -malhar releases:
+
+ ```
+ REPO_NAME=apex-malhar
+ DOC_NAME=malhar
+ ```
+
+ The `REPO_NAME` variable above should match the folder name of the cloned apex module being built.
+
+To build and deploy the documentation, execute the following commands in the apex module folder specified in `REPO_NAME` above. **Note**: Until [mkdocs #859](https://github.com/mkdocs/mkdocs/issues/859) is resolved and available for download, use mkdocs built against [master](https://github.com/mkdocs/mkdocs).
+
+```bash
+# build docs, they would be generated in a site sub-folder
+mkdocs build --clean
+
+# Calculate the major.minor version
+docv=`echo ${rv} | sed 's/\([0-9]*\)\.\([0-9]*\)\.\([0-9]*\)/\1\.\2/'`
+
+# copy docs from site folder into target folder on apex-site
+cd ../apex-site
+git checkout asf-site
+rm -rf docs/${DOC_NAME}-${docv}
+cp -r ../${REPO_NAME}/site docs/${DOC_NAME}-${docv}
+git add -A
+git commit -m "Adding ${DOC_NAME}-${rv} documentation"
+git push
+```
+
+The documentation is now accessible at the URL location below. For patch releases, however, the documentation changes will already reflect on the website.
+
+```
+https://apex.apache.org/docs/${DOC_NAME}-${docv}/
+```
+
## Voting
Vote call sample:
@@ -201,6 +252,24 @@
```
Merge `@since` tag and change log changes to `master`.
+### Documentation
+
+There two steps in promotion. The documentation built during the build step above is made available on the website and then any changes to the rest of the website are deployed.
+
+1. If this is a new minor or a major release, under the `apex-site` folder, run the following commands to point the website to the release documentation folder, otherwise it is a patch release and this step can be skipped as the documentation is already reflected in the website.
+
+```bash
+# docv major.minor version calculated in the build step
+cd docs
+# Set the release version to be the latest available version
+ln -nsf ${DOC_NAME}-${docv} ${DOC_NAME}
+git add -A
+git commit -m "Promoting ${DOC_NAME}-${docv} documentation"
+git push
+```
+
+2. Refer to the documentation in [apex-site repository](https://github.com/apache/apex-site#contributing) to add any new links to the [docs.md](https://github.com/apache/apex-site/blob/master/src/md/docs.md) page, follow the committer steps to commit and push these changes, and deploy the site.
+
## Announce Release
For minor or major release, publish the documentation to the web site prior to updating download page (which will automatically link the documentation). See https://github.com/apache/apex-core/tree/master/docs#deployment
