[SYSTEMML-1397] Describe process for deploying versioned docs
Project: http://git-wip-us.apache.org/repos/asf/incubator-systemml/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-systemml/commit/7407b700 Tree: http://git-wip-us.apache.org/repos/asf/incubator-systemml/tree/7407b700 Diff: http://git-wip-us.apache.org/repos/asf/incubator-systemml/diff/7407b700 Branch: refs/heads/gh-pages Commit: 7407b7001ef1835cdb6a5f70ebcce5fa901fa12a Parents: bd23224 Author: Deron Eriksson <[email protected]> Authored: Mon Mar 13 15:18:22 2017 -0700 Committer: Deron Eriksson <[email protected]> Committed: Mon Mar 13 15:18:22 2017 -0700 ---------------------------------------------------------------------- release-process.md | 99 +++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 80 insertions(+), 19 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-systemml/blob/7407b700/release-process.md ---------------------------------------------------------------------- diff --git a/release-process.md b/release-process.md index a75a281..d64d417 100644 --- a/release-process.md +++ b/release-process.md @@ -33,23 +33,6 @@ To be written. (Describe how the release candidate is built, including checksums the release candidate is deployed to servers for review.) -## Release Documentation - -The `SYSTEMML_VERSION` value in docs/_config.yml should be updated to the correct release version. The documentation -site should be built. -The SystemML documentation site should be deployed to a docs version folder within the main website project (using -svn). As an example, the documentation site for SystemML version 0.11.0 should be available -at http://systemml.apache.org/docs/0.11.0. - -The Javadocs should be generated for the project and should be deployed to a docs version folder, such as -http://systemml.apache.org/docs/0.11.0/api/java. Any other docs, such as Scaladocs if they are available, should -be deployed to corresponding locations. Note that the version number specified in the Javadocs is determined by the project -version number in the project pom.xml file. - -Additionally, the Javadocs should be deployed to http://systemml.apache.org/docs/latest/api/java -if the Javadocs have not already been deployed to this location. - - # Release Candidate Checklist ## All Artifacts and Checksums Present @@ -291,5 +274,83 @@ has been approved. ## Release Deployment -To be written. (What steps need to be done? How is the release deployed to the central maven repo? What updates need to -happen to the main website, such as updating the Downloads page? Where do the release notes for the release go?) +To be written. (What steps need to be done? How is the release deployed to Apache dist and the central maven repo? +Where do the release notes for the release go?) + + +## Documentation Deployment + +This section describes how to deploy versioned project documentation to the main website. +Note that versioned project documentation is committed directly to the `svn` project's `docs` folder. +The versioned project documentation is not committed to the website's `git` project. + +Checkout branch in main project (`incubator-systemml`). + + $ git checkout branch-0.13.0 + +In `incubator-systemml/docs/_config.yml`, set: + +* `SYSTEMML_VERSION` to project version (0.13.0) +* `FEEDBACK_LINKS` to `false` (only have feedback links on `LATEST` docs) +* `API_DOCS_MENU` to `true` (adds `API Docs` menu to get to project javadocs) + +Generate `docs/_site` by running `bundle exec jekyll serve` in `incubator-systemml/docs`. + + $ bundle exec jekyll serve + +Verify documentation site looks correct. + +In website `svn` project, create `incubator-systemml-website-site/docs/0.13.0` folder. + +Copy contents of `incubator-systemml/docs/_site` to `incubator-systemml-website-site/docs/0.13.0`. + +Delete any unnecessary files (`Gemfile`, `Gemfile.lock`). + +Create `incubator-systemml-website-site/docs/0.13.0/api/java` folder for javadocs. + +Update `incubator-systemml/pom.xml` project version to what should be displayed in javadocs (such as `0.13.0`). + +Build project (which generates javadocs). + + $ mvn clean package -P distribution + +Copy contents of `incubator-systemml/target/apidocs` to `incubator-systemml-website-site/docs/0.13.0/api/java`. + +Open up `file:///.../incubator-systemml-website-site/docs/0.13.0/index.html` and verify `API Docs` → `Javadoc` link works and that the correct Javadoc version is displayed. Verify feedback links under `Issues` menu are not present. + +Clean up any unnecessary files (such as deleting `.DS_Store` files on OS X). + + $ find . -name '.DS_Store' -type f -delete + +Commit the versioned project documentation to `svn`: + + $ svn status + $ svn add docs/0.13.0 + $ svn commit -m "Add 0.13.0 docs to website" + +Update `incubator-systemml-website/_src/documentation.html` to include 0.13.0 link. + +Start main website site by running `gulp` in `incubator-systemml-website`: + + $ gulp + +Commit and push the update to `git` project. + + $ git add -u + $ git commit -m "Add 0.13.0 link to documentation page" + $ git push + $ git push apache master + +Copy contents of `incubator-systemml-website/_site` (generated by `gulp`) to `incubator-systemml-website-site`. +After doing so, we should see that `incubator-systemml-website-site/documentation.html` has been updated. + + $ svn status + $ svn diff + +Commit the update to `documentation.html` to publish the website update. + + $ svn commit -m "Add 0.13.0 link to documentation page" + +The versioned project documentation is now deployed to the main website, and the +[Documentation Page](http://systemml.apache.org/documentation) contains a link to the versioned documentation. +
