[GitHub] apex-site pull request #42: Added updating documentation to release process

[asfgit]

Github user asfgit closed the pull request at:

https://github.com/apache/apex-site/pull/42


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] apex-site pull request #42: Added updating documentation to release process

[PramodSSImmaneni]

Github user PramodSSImmaneni commented on a diff in the pull request:

https://github.com/apache/apex-site/pull/42#discussion_r72343142
  
--- Diff: src/md/release.md ---
@@ -201,6 +252,27 @@ git push apache
 ```
 Merge `@since` tag and change log changes to `master`.
 
+### Documentation
+
+The documentation promotion is done in two steps. First the release 
documentation component is made available on the website and then the remaining 
website documentation is deployed.
+
+1. If this is a new minor or a major release, in the `apex-site` folder 
from the build, 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.
+
--- End diff --

There is also the committing to github. The snippet says to run the 
commands under the apex-site folder. There are a couple of other things in 
there which shouldn't be there. I had missed saving the file before checkin and 
they got it, I removed them.


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] apex-site pull request #42: Added updating documentation to release process

[tweise]

Github user tweise commented on a diff in the pull request:

https://github.com/apache/apex-site/pull/42#discussion_r72341103
  
--- Diff: src/md/release.md ---
@@ -201,6 +252,27 @@ git push apache
 ```
 Merge `@since` tag and change log changes to `master`.
 
+### Documentation
+
+The documentation promotion is done in two steps. First the release 
documentation component is made available on the website and then the remaining 
website documentation is deployed.
+
+1. If this is a new minor or a major release, in the `apex-site` folder 
from the build, 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.
+
--- End diff --

Why "apex-site" folder from the build? The documentation was already 
created an published (e.g. http://apex.apache.org/docs/apex-3.4/) and now all 
that remains to do is to create a symlink to make it available under 
http://apex.apache.org/docs/apex/ ?


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] apex-site pull request #42: Added updating documentation to release process

[PramodSSImmaneni]

Github user PramodSSImmaneni commented on a diff in the pull request:

https://github.com/apache/apex-site/pull/42#discussion_r72340598
  
--- Diff: 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}-${docv} documentation"
+git push
+```
+
+The documentation is now accessible at the URL location below. For patch 
releases, however, the documentation would already be reflected in the regular 
website.
--- End diff --

I will reword it.


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] apex-site pull request #42: Added updating documentation to release process

[PramodSSImmaneni]

Github user PramodSSImmaneni commented on a diff in the pull request:

https://github.com/apache/apex-site/pull/42#discussion_r72340572
  
--- Diff: src/md/release.md ---
@@ -201,6 +252,27 @@ git push apache
 ```
 Merge `@since` tag and change log changes to `master`.
 
+### Documentation
+
+The documentation promotion is done in two steps. First the release 
documentation component is made available on the website and then the remaining 
website documentation is deployed.
--- End diff --

I will reword it. The intent is to say that the module documentation is 
first deployed then the rest of the website is deployed.


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] apex-site pull request #42: Added updating documentation to release process

[PramodSSImmaneni]

Github user PramodSSImmaneni commented on a diff in the pull request:

https://github.com/apache/apex-site/pull/42#discussion_r71972984
  
--- Diff: src/md/release.md ---
@@ -150,6 +150,47 @@ 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 
location until the release is promoted, at which time it will also be promoted 
to the main website location.
+
+Do the following setup setups before building and deploying the 
documentation. Clone the apex-site repository into a folder called 
```apex-site``` at the same level as the current repository. 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
+```
+
+Execute the following commands to build and deploy the documentation. 
**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 the site folder
+mkdocs build --clean
+
+# copy docs from site into target folder on apex-site
+cd ../apex-site
+git checkout asf-site
+rm -rf docs/${DOC_NAME}-${rv}
--- End diff --

ok, I have made the changes, albeit begrudgingly. Please take a look.


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] apex-site pull request #42: Added updating documentation to release process

[PramodSSImmaneni]

Github user PramodSSImmaneni commented on a diff in the pull request:

https://github.com/apache/apex-site/pull/42#discussion_r71929670
  
--- Diff: src/md/release.md ---
@@ -150,6 +150,47 @@ 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 
location until the release is promoted, at which time it will also be promoted 
to the main website location.
+
+Do the following setup setups before building and deploying the 
documentation. Clone the apex-site repository into a folder called 
```apex-site``` at the same level as the current repository. 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
+```
+
+Execute the following commands to build and deploy the documentation. 
**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 the site folder
+mkdocs build --clean
+
+# copy docs from site into target folder on apex-site
+cd ../apex-site
+git checkout asf-site
+rm -rf docs/${DOC_NAME}-${rv}
--- End diff --

If I understood you correctly, let's say we are releasing patch 3.4.2

Docs are updated in a folder 3.4.2 during the RC process
During promotion this folder replaces the existing 3.4 folder so the docs 
are reflected on the website. 




---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] apex-site pull request #42: Added updating documentation to release process

[tweise]

Github user tweise commented on a diff in the pull request:

https://github.com/apache/apex-site/pull/42#discussion_r71928404
  
--- Diff: src/md/release.md ---
@@ -150,6 +150,47 @@ 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 
location until the release is promoted, at which time it will also be promoted 
to the main website location.
+
+Do the following setup setups before building and deploying the 
documentation. Clone the apex-site repository into a folder called 
```apex-site``` at the same level as the current repository. 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
+```
+
+Execute the following commands to build and deploy the documentation. 
**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 the site folder
+mkdocs build --clean
+
+# copy docs from site into target folder on apex-site
+cd ../apex-site
+git checkout asf-site
+rm -rf docs/${DOC_NAME}-${rv}
--- End diff --

OK, that's good. Then for a patch release the docs will be updated along 
with the RC. And only a minor or major release will need the latest symlink 
update when promoting the release.


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] apex-site pull request #42: Added updating documentation to release process

[PramodSSImmaneni]

Github user PramodSSImmaneni commented on a diff in the pull request:

https://github.com/apache/apex-site/pull/42#discussion_r71923101
  
--- Diff: src/md/release.md ---
@@ -150,6 +150,47 @@ 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 
location until the release is promoted, at which time it will also be promoted 
to the main website location.
+
+Do the following setup setups before building and deploying the 
documentation. Clone the apex-site repository into a folder called 
```apex-site``` at the same level as the current repository. 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
+```
+
+Execute the following commands to build and deploy the documentation. 
**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 the site folder
+mkdocs build --clean
+
+# copy docs from site into target folder on apex-site
+cd ../apex-site
+git checkout asf-site
+rm -rf docs/${DOC_NAME}-${rv}
--- End diff --

@tweise It's a symlink today from latest to 3.4 folder, so if we update the 
folder the website will be changed. We could also do what @sashadt is saying to 
include the patch number in the folder name.


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] apex-site pull request #42: Added updating documentation to release process

[sashadt]

Github user sashadt commented on a diff in the pull request:

https://github.com/apache/apex-site/pull/42#discussion_r71809517
  
--- Diff: src/md/release.md ---
@@ -150,6 +150,47 @@ 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 
location until the release is promoted, at which time it will also be promoted 
to the main website location.
+
+Do the following setup setups before building and deploying the 
documentation. Clone the apex-site repository into a folder called 
```apex-site``` at the same level as the current repository. 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
+```
+
+Execute the following commands to build and deploy the documentation. 
**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 the site folder
+mkdocs build --clean
+
+# copy docs from site into target folder on apex-site
+cd ../apex-site
+git checkout asf-site
+rm -rf docs/${DOC_NAME}-${rv}
--- End diff --

I like the idea of not adding -RC, and just using the version directly.  
However, I can see the argument can be made that 3.4.0 and 3.4.1 can have 
security or other feature breaking changes, and we potentially should support 
independent docs for both.  In light of this, I suggest we use `X.Y.Z` for docs 
versioning.  I know this means extra space used by patch versions, and extra 
changes to docs when a patch is released, but gives us flexibility to support 
any documentation change scenario.  So we will have:

```
docs/apex/3.3.0
docs/apex/3.4.0
docs/apex/3.4.1
docs/apex -> docs/apex/3.4.1
```


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] apex-site pull request #42: Added updating documentation to release process

[PramodSSImmaneni]

Github user PramodSSImmaneni commented on a diff in the pull request:

https://github.com/apache/apex-site/pull/42#discussion_r71800574
  
--- Diff: src/md/release.md ---
@@ -150,6 +150,47 @@ 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 
location until the release is promoted, at which time it will also be promoted 
to the main website location.
+
+Do the following setup setups before building and deploying the 
documentation. Clone the apex-site repository into a folder called 
```apex-site``` at the same level as the current repository. 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
+```
+
+Execute the following commands to build and deploy the documentation. 
**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 the site folder
+mkdocs build --clean
+
+# copy docs from site into target folder on apex-site
+cd ../apex-site
+git checkout asf-site
+rm -rf docs/${DOC_NAME}-${rv}
--- End diff --

Ah ok, I can live with that ;). The only downside is if we are addressing a 
documentation issue in an RC for a patch version greater than 0 we would affect 
the latest docs before we want to.


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] apex-site pull request #42: Added updating documentation to release process

[tweise]

Github user tweise commented on a diff in the pull request:

https://github.com/apache/apex-site/pull/42#discussion_r71776420
  
--- Diff: src/md/release.md ---
@@ -150,6 +150,47 @@ 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 
location until the release is promoted, at which time it will also be promoted 
to the main website location.
+
+Do the following setup setups before building and deploying the 
documentation. Clone the apex-site repository into a folder called 
```apex-site``` at the same level as the current repository. 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
+```
+
+Execute the following commands to build and deploy the documentation. 
**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 the site folder
+mkdocs build --clean
+
+# copy docs from site into target folder on apex-site
+cd ../apex-site
+git checkout asf-site
+rm -rf docs/${DOC_NAME}-${rv}
--- End diff --

It's none of these options ;-) 

My suggestion is to push the docs under the X.Y release location when the 
RC is created, for example:  https://apex.apache.org/docs/malhar/3.4

The latest link ((http://apex.apache.org/docs/malhar/) can be updated when 
the release is promoted, if it is a minor or major release. 

There is no -RC involved in this scenario.


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] apex-site pull request #42: Added updating documentation to release process

[PramodSSImmaneni]

Github user PramodSSImmaneni commented on a diff in the pull request:

https://github.com/apache/apex-site/pull/42#discussion_r71714416
  
--- Diff: src/md/release.md ---
@@ -150,6 +150,47 @@ 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 
location until the release is promoted, at which time it will also be promoted 
to the main website location.
+
+Do the following setup setups before building and deploying the 
documentation. Clone the apex-site repository into a folder called 
```apex-site``` at the same level as the current repository. 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
+```
+
+Execute the following commands to build and deploy the documentation. 
**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 the site folder
+mkdocs build --clean
+
+# copy docs from site into target folder on apex-site
+cd ../apex-site
+git checkout asf-site
+rm -rf docs/${DOC_NAME}-${rv}
--- End diff --

@tweise Just so I understand you correctly you are suggesting option 1. 
below correct? If it is so, I don't mind make this change but it is technically 
not correct as folks who would go to the website to refer the docs will see RC 
docs and there could not only be mistakes in there but it could refer to 
features that are not yet available in the release. 

My preference is for option 3 which is what I have implemented here. I also 
see the additional work during promotion being minimal on what is already being 
done. Let me know if you still want to go with option 1. and I will make the 
changes as I think we have had enough discussion on this already :).

1. Publish the RC docs to the website rightaway (for example under  
https://apex.apache.org/docs/apex) even though the RC hasn't been voted to be 
the final release and there can be other RCs after this.

2. Don't make RC docs available under any path such as 
https://apex.apache.org/docs/apex/3.5.0-RC1 when the RC is in review and 
publish them to https://apex.apache.org/docs/apex once the RC is voted to be 
the release.

3. What I am proposing to make RC docs available under a path such as 
https://apex.apache.org/docs/apex/3.5.0-RC1 while the RC is in review so that 
folks can review the docs as well and make it available under 
https://apex.apache.org/docs/apex when the release is ready.


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] apex-site pull request #42: Added updating documentation to release process

[tweise]

Github user tweise commented on a diff in the pull request:

https://github.com/apache/apex-site/pull/42#discussion_r71692850
  
--- Diff: src/md/release.md ---
@@ -150,6 +150,47 @@ 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 
location until the release is promoted, at which time it will also be promoted 
to the main website location.
+
+Do the following setup setups before building and deploying the 
documentation. Clone the apex-site repository into a folder called 
```apex-site``` at the same level as the current repository. 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
+```
+
+Execute the following commands to build and deploy the documentation. 
**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 the site folder
+mkdocs build --clean
+
+# copy docs from site into target folder on apex-site
+cd ../apex-site
+git checkout asf-site
+rm -rf docs/${DOC_NAME}-${rv}
--- End diff --

@PramodSSImmaneni I see no need for staging documentation. The 
documentation can be published under the final name right away. Nobody is going 
to look at it before the release is out, as that's what establishes the link to 
the docs.

For the case of updating latest (different from your example), that can be 
done anytime, and maybe it should not be pointed to a X.Y version before it was 
released. But it could theoretically also be pointed to latest master version, 
I don't think we had a need for that so far, as long as we release frequently. 
And it is possible to look at individual pages in github anyways.


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] apex-site pull request #42: Added updating documentation to release process

[PramodSSImmaneni]

Github user PramodSSImmaneni commented on a diff in the pull request:

https://github.com/apache/apex-site/pull/42#discussion_r71652914
  
--- Diff: src/md/release.md ---
@@ -150,6 +150,47 @@ 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 
location until the release is promoted, at which time it will also be promoted 
to the main website location.
+
+Do the following setup setups before building and deploying the 
documentation. Clone the apex-site repository into a folder called 
```apex-site``` at the same level as the current repository. 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
+```
+
+Execute the following commands to build and deploy the documentation. 
**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 the site folder
+mkdocs build --clean
+
+# copy docs from site into target folder on apex-site
+cd ../apex-site
+git checkout asf-site
+rm -rf docs/${DOC_NAME}-${rv}
--- End diff --

@sashadt @tweise  Please let me know if anything else is needed here. As I 
summarized promotion is nothing more than pointing the website links to the new 
docs after voting is finished and the RC is voted to be the release. Till then 
the website links point to the previous release (so folks are looking at stable 
docs) and the RC docs are accessible on a different path. I think this is 
reasonable.


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] apex-site pull request #42: Added updating documentation to release process

[PramodSSImmaneni]

Github user PramodSSImmaneni commented on a diff in the pull request:

https://github.com/apache/apex-site/pull/42#discussion_r71226364
  
--- Diff: src/md/release.md ---
@@ -150,6 +150,47 @@ 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 
location until the release is promoted, at which time it will also be promoted 
to the main website location.
+
+Do the following setup setups before building and deploying the 
documentation. Clone the apex-site repository into a folder called 
```apex-site``` at the same level as the current repository. 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
+```
+
+Execute the following commands to build and deploy the documentation. 
**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 the site folder
+mkdocs build --clean
+
+# copy docs from site into target folder on apex-site
+cd ../apex-site
+git checkout asf-site
+rm -rf docs/${DOC_NAME}-${rv}
--- End diff --

Just want to add that in example above when release is ready the location 
below
https://apex.apache.org/docs/malhar/3.4.0-RC1
will be converted to
https://apex.apache.org/docs/malhar/3.4
This is the same location we store the docs today.


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] apex-site pull request #42: Added updating documentation to release process

[sashadt]

Github user sashadt commented on a diff in the pull request:

https://github.com/apache/apex-site/pull/42#discussion_r70522203
  
--- Diff: src/md/release.md ---
@@ -150,6 +150,47 @@ 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 
location until the release is promoted, at which time it will also be promoted 
to the main website location.
--- End diff --

Every major release is always available at docs/apex-MAJOR.MINOR.  Every 
time new MAJOR.MINOR release is produced, it is also linked to docs/apex.


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] apex-site pull request #42: Added updating documentation to release process

[PramodSSImmaneni]

Github user PramodSSImmaneni commented on a diff in the pull request:

https://github.com/apache/apex-site/pull/42#discussion_r70510870
  
--- Diff: src/md/release.md ---
@@ -150,6 +150,47 @@ 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 
location until the release is promoted, at which time it will also be promoted 
to the main website location.
+
+Do the following setup setups before building and deploying the 
documentation. Clone the apex-site repository into a folder called 
```apex-site``` at the same level as the current repository. 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
+```
+
+Execute the following commands to build and deploy the documentation. 
**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 the site folder
+mkdocs build --clean
+
+# copy docs from site into target folder on apex-site
+cd ../apex-site
+git checkout asf-site
+rm -rf docs/${DOC_NAME}-${rv}
--- End diff --

Agreed will fix


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] apex-site pull request #42: Added updating documentation to release process

[PramodSSImmaneni]

Github user PramodSSImmaneni commented on a diff in the pull request:

https://github.com/apache/apex-site/pull/42#discussion_r70510813
  
--- Diff: src/md/release.md ---
@@ -150,6 +150,47 @@ 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 
location until the release is promoted, at which time it will also be promoted 
to the main website location.
--- End diff --

I mentioned it below, https://apex.apache.org/docs/${DOC_NAME}-${rv}/
It is the same server with a different path. This is already in place so 
nothing new is being added. For e.g., try https://apex.apache.org/docs/apex-3.2


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] apex-site pull request #42: Added updating documentation to release process

[tweise]

Github user tweise commented on a diff in the pull request:

https://github.com/apache/apex-site/pull/42#discussion_r70504749
  
--- Diff: src/md/release.md ---
@@ -150,6 +150,47 @@ 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 
location until the release is promoted, at which time it will also be promoted 
to the main website location.
--- End diff --

I don't think we need an alternate location and the steps below don't seem 
to indicate it either.


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] apex-site pull request #42: Added updating documentation to release process

[tweise]

Github user tweise commented on a diff in the pull request:

https://github.com/apache/apex-site/pull/42#discussion_r70504409
  
--- Diff: src/md/release.md ---
@@ -150,6 +150,47 @@ 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 
location until the release is promoted, at which time it will also be promoted 
to the main website location.
+
+Do the following setup setups before building and deploying the 
documentation. Clone the apex-site repository into a folder called 
```apex-site``` at the same level as the current repository. 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
+```
+
+Execute the following commands to build and deploy the documentation. 
**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 the site folder
+mkdocs build --clean
+
+# copy docs from site into target folder on apex-site
+cd ../apex-site
+git checkout asf-site
+rm -rf docs/${DOC_NAME}-${rv}
--- End diff --

Documentation is always MAJOR.MINOR, so ${rv} is not correct here.


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] apex-site pull request #42: Added updating documentation to release process

[tweise]

Github user tweise commented on a diff in the pull request:

https://github.com/apache/apex-site/pull/42#discussion_r70504287
  
--- Diff: src/md/release.md ---
@@ -150,6 +150,47 @@ 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 
location until the release is promoted, at which time it will also be promoted 
to the main website location.
+
+Do the following setup setups before building and deploying the 
documentation. Clone the apex-site repository into a folder called 
```apex-site``` at the same level as the current repository. Set the following 
environment variables
--- End diff --

setup setups?


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] apex-site pull request #42: Added updating documentation to release process

[PramodSSImmaneni]

GitHub user PramodSSImmaneni opened a pull request:

https://github.com/apache/apex-site/pull/42

Added updating documentation to release process

I had some updates to docs and had noticed that we don't include building 
and staging documentation as part of the release process even though all the 
steps for it is already present in other places. Had a chat with @sashadt about 
the same.

Including steps to build and stage documentation as part of the release 
process just like we do for source code. These have been taken from existing 
documentation in other places and adapted accordingly. @sashadt and @tweise 
please review.

You can merge this pull request into a Git repository by running:

$ git pull https://github.com/PramodSSImmaneni/incubator-apex-site 
documentation-in-release

Alternatively you can review and apply these changes as the patch at:

https://github.com/apache/apex-site/pull/42.patch

To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:

This closes #42


commit a1070050b957ad406d5be2057c6480775c205cc0
Author: Pramod Immaneni 
Date:   2016-07-09T19:20:02Z

Added updating documentation to release process




---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---