You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@apex.apache.org by th...@apache.org on 2016/07/28 21:57:13 UTC
[1/2] apex-site git commit: Added releasing documentation to the
release process
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 <pr...@datatorrent.com>
Authored: Sat Jul 9 12:20:02 2016 -0700
Committer: Pramod Immaneni <pr...@datatorrent.com>
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
[2/2] apex-site git commit: Merge branch 'documentation-in-release'
of https://github.com/PramodSSImmaneni/incubator-apex-site
Posted by th...@apache.org.
Merge branch 'documentation-in-release' of https://github.com/PramodSSImmaneni/incubator-apex-site
Project: http://git-wip-us.apache.org/repos/asf/apex-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/apex-site/commit/18264a78
Tree: http://git-wip-us.apache.org/repos/asf/apex-site/tree/18264a78
Diff: http://git-wip-us.apache.org/repos/asf/apex-site/diff/18264a78
Branch: refs/heads/master
Commit: 18264a780c0287cd9b1f4e2af236c7fa4ae1738d
Parents: c1498b1 563cda8
Author: Thomas Weise <th...@datatorrent.com>
Authored: Thu Jul 28 14:55:29 2016 -0700
Committer: Thomas Weise <th...@datatorrent.com>
Committed: Thu Jul 28 14:55:29 2016 -0700
----------------------------------------------------------------------
src/md/release.md | 69 ++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 69 insertions(+)
----------------------------------------------------------------------