You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@systemml.apache.org by de...@apache.org on 2017/04/07 18:58:51 UTC
[47/50] [abbrv] incubator-systemml git commit: [SYSTEMML-1397]
Describe process for deploying versioned docs
[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 <de...@us.ibm.com>
Authored: Mon Mar 13 15:18:22 2017 -0700
Committer: Deron Eriksson <de...@us.ibm.com>
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.
+