Repository: apex-site Updated Branches: refs/heads/master c1498b1fe -> 18264a780
Added releasing documentation to the release process Project: http://git-wip-us.apache.org/repos/asf/apex-site/repo Commit: http://git-wip-us.apache.org/repos/asf/apex-site/commit/563cda84 Tree: http://git-wip-us.apache.org/repos/asf/apex-site/tree/563cda84 Diff: http://git-wip-us.apache.org/repos/asf/apex-site/diff/563cda84 Branch: refs/heads/master Commit: 563cda84bff625bd1fea8d005a722e6be05ea0a7 Parents: 80bb445 Author: Pramod Immaneni <[email protected]> Authored: Sat Jul 9 12:20:02 2016 -0700 Committer: Pramod Immaneni <[email protected]> Committed: Thu Jul 28 06:01:08 2016 -0700 ---------------------------------------------------------------------- src/md/release.md | 69 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/apex-site/blob/563cda84/src/md/release.md ---------------------------------------------------------------------- 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 @@ mkdir svn-dist && cp *-source-* svn-dist/ 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 @@ git push apache ``` 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
