Repository: vxquery Updated Branches: refs/heads/master d9e4f29f4 -> 94dcab204
Developer contribution documentation for the site. Project: http://git-wip-us.apache.org/repos/asf/vxquery/repo Commit: http://git-wip-us.apache.org/repos/asf/vxquery/commit/94dcab20 Tree: http://git-wip-us.apache.org/repos/asf/vxquery/tree/94dcab20 Diff: http://git-wip-us.apache.org/repos/asf/vxquery/diff/94dcab20 Branch: refs/heads/master Commit: 94dcab2046c0a5c04ad18d1cae05213a83478fde Parents: d9e4f29 Author: Preston Carman <[email protected]> Authored: Thu Jul 16 09:57:43 2015 -0700 Committer: Preston Carman <[email protected]> Committed: Thu Jul 16 09:57:43 2015 -0700 ---------------------------------------------------------------------- src/site/apt/cluster_installation.apt | 149 ------------------------ src/site/apt/development_contribution.apt | 122 +++++++++++++++++++ src/site/apt/development_site_update.apt | 34 ++++++ src/site/apt/user_cluster_installation.apt | 149 ++++++++++++++++++++++++ src/site/site.xml | 8 +- 5 files changed, 312 insertions(+), 150 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/vxquery/blob/94dcab20/src/site/apt/cluster_installation.apt ---------------------------------------------------------------------- diff --git a/src/site/apt/cluster_installation.apt b/src/site/apt/cluster_installation.apt deleted file mode 100644 index 1342908..0000000 --- a/src/site/apt/cluster_installation.apt +++ /dev/null @@ -1,149 +0,0 @@ -~~ Licensed to the Apache Software Foundation (ASF) under one or more -~~ contributor license agreements. See the NOTICE file distributed with -~~ this work for additional information regarding copyright ownership. -~~ The ASF licenses this file to You under the Apache License, Version 2.0 -~~ (the "License"); you may not use this file except in compliance with -~~ the License. You may obtain a copy of the License at -~~ -~~ http://www.apache.org/licenses/LICENSE-2.0 -~~ -~~ Unless required by applicable law or agreed to in writing, software -~~ distributed under the License is distributed on an "AS IS" BASIS, -~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -~~ See the License for the specific language governing permissions and -~~ limitations under the License. - -Cluster Installation - - -* Requirements - - * Apache VXQuery\x99 source archive (apache-vxquery-X.Y-source-release.zip) - - * JDK >= 1.7 - - * Apache Maven >= 3.2 - - -* Steps - - * <<Export JAVA_HOME>> - ---- -$ export JAVA_HOME=/usr/java/latest ---- - - - * <<Unzip and build VXQuery>> - ---- -$ unzip apache-vxquery-X.Y-source-release.zip -$ cd apache-vxquery-X.Y -$ mvn package -DskipTests -$ cd .. ---- - - - * <<Create configuration file>> - - Create a configuration xml file containing the information of the vxquery cluster.Here is an example of a VXQuery configuration file for a cluster with 1 master and 3 slaves. - ---- - <cluster xmlns="cluster"> - <name>local</name> - <username>joe</username> - <master_node> - <id>master</id> - <client_ip>128.195.52.177</client_ip> - <cluster_ip>192.168.100.0</cluster_ip> - </master_node> - <node> - <id>nodeA</id> - <cluster_ip>192.168.100.1</cluster_ip> - </node> - <node> - <id>nodeB</id> - <cluster_ip>192.168.100.2</cluster_ip> - </node> - <node> - <id>nodeC</id> - <cluster_ip>192.168.100.3</cluster_ip> - </node> - </cluster> ---- - - * Fields that are required: - - * name : name of the cluster - - * username : user that will execute commands in all the machines of the cluster. Preferably a user that has passwordless ssh access to the machines. - - * id : hostname of the node - - * cluster_ip : ip of the host in the cluster - - * client_ip : ip of the master - - * Some optional fields: - - * CCPORT : port for the Cluster Controller - - * J_OPTS : define the java options you want, for Cluster Controller and Node Controller - - - * <<Deploy cluster>> - - To deploy the cluster you need to execute this command in the vxquery installation directory - ---- -$python cluster_cli.py -c ../conf/cluster.xml -a deploy -d /apache-vxquery/vxquery-server ---- - - * Arguments: - - * -c : path to the configuration file you created - - * -a : action you want to perform - - * -d : directory in the system to deploy the cluster - - - * <<Start cluster>> - - The command to start the cluster is - ---- -$python cluster_cli.py -c ../conf/cluster.xml -a start ---- - - - * <<Stop cluster>> - - The command to stop the cluster is - ---- -$python cluster_cli.py -c ../conf/cluster.xml -a stop ---- - - - * <<Check process status for Cluster Controller>> - - You can try these commands to check on the status of the processes - ---- -$ps -ef|grep ${USER}|grep java|grep 'Dapp.name=vxquerycc' ---- - - - * <<Check process status for Node Controller>> - ---- -$ps -ef|grep ${USER}|grep java|grep 'Dapp.name=vxquerync' ---- - - - * <<Check process status for hyracks process>> - ---- -$ps -ef|grep ${USER}|grep java|grep 'hyracks' ---- \ No newline at end of file http://git-wip-us.apache.org/repos/asf/vxquery/blob/94dcab20/src/site/apt/development_contribution.apt ---------------------------------------------------------------------- diff --git a/src/site/apt/development_contribution.apt b/src/site/apt/development_contribution.apt new file mode 100644 index 0000000..f767cfd --- /dev/null +++ b/src/site/apt/development_contribution.apt @@ -0,0 +1,122 @@ +~~ Licensed to the Apache Software Foundation (ASF) under one or more +~~ contributor license agreements. See the NOTICE file distributed with +~~ this work for additional information regarding copyright ownership. +~~ The ASF licenses this file to You under the Apache License, Version 2.0 +~~ (the "License"); you may not use this file except in compliance with +~~ the License. You may obtain a copy of the License at +~~ +~~ http://www.apache.org/licenses/LICENSE-2.0 +~~ +~~ Unless required by applicable law or agreed to in writing, software +~~ distributed under the License is distributed on an "AS IS" BASIS, +~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +~~ See the License for the specific language governing permissions and +~~ limitations under the License. + +Contributing Code + + The following steps outline how to submit code to the VXQuery community for inclusion. + Please read the Developer {{{http://vxquery.apache.org/developer_get_started.html}Get Started}} Guide + to answer question about getting start as a developer. + VXQuery community supports two methods for contributing code to the project. + + [[1]] <<Submit a patch file to an open VXQuery issue.>> + + This method works well for small bug fixes. + + [[1]] <<Create a pull request in github.>> + + The pull request will allow the community to give the developer (you) feedback + and support in creating a quality submission. + The following steps outline the github pull request process for the VXQuery community. + +* Github Pull Request Process + +** Developer + + * Pre-contribution steps to follow. + + * {{{http://vxquery.apache.org/user_get_started.html}Community steps}}. + + * {{{http://vxquery.apache.org/developer_get_started.html}Developer steps}}. + + * Create a {{{https://github.com/}github}} account. + + + * Create a github fork of {{{https://github.com/apache/vxquery}Apache VXQuery}} project. + + Go to {{{https://github.com/apache/vxquery}Apache VXQuery}} github mirror. + Create a fork by clicking on the fork button. + Then clone the fork to your local machine for development. + + + * Create a branch for your changes. + + VXQuery uses the following convention when creating a branch: authors_username/topic_or_issue + (examples: prestonc/vxquery_142 or tillw/group_by_clause). + The following branch name helps keep branches separated and keeps it easy to determine the author and topic. + + + * Make the change. + + :-) + + + * Add new tests. (optional) + + If the change is not covered in the XQTS, please create a new test in the VXQuery test suite + to cover the code changes made to VXQuery. + + + * Test your changes. + + Once the change is ready, test the branch against known passing Apache VXQuery tests. + The patch must not break any of the existing test suites, either the VXQuery or currently passing XQTS. + + * {{{http://vxquery.apache.org/user_running_tests.html} Run the Test Suites}} + + * {{{http://vxquery.apache.org/development_update_xqts_results.html}Update Passing Tests}} + + + * Clean up your code. + + Remove an extra debug code and verify the patch only includes code for the change. + + + * Create a github Pull Request. + + Once the work has been tested, a pull request can be created for the change branch. + Please use the Apache VXQuery master as branch to compare the change branch. + The branch should be up-to-date with the lastest Apache VXQuery master branch. + + + * Post your Pull Request. + + Post the Pull Request to the mailing list or issue to allow the VXQuery community to give feedback on the change. + At least one other member of the community should review the change. + If there is any feedback, address this and repeat the posting process. + +** Code Reviewer + + * Review the Pull Request. + + Post inline or global comments for the developer. + Be polite in your suggestions. + Guide the developer to bring the code up to VXQuery's code standards. + + * Double check the VXQuery and XQTS tests. + + +** VXQuery Committer (author or sponsor of the change) + + The VXQuery committer will be responsible for the change made to the ASF git repository. + While they do not need to be the author, the committer should have some understanding of the change + they are pushing on to the repository. + Often the committer will also be the reviewer for non-committer changes. + + * Double check the VXQuery and XQTS tests. + + * Merge the change with ASF master. + + When merging the change, do not rebase. + Instead do a single merge commit into Apache VXQuery master. http://git-wip-us.apache.org/repos/asf/vxquery/blob/94dcab20/src/site/apt/development_site_update.apt ---------------------------------------------------------------------- diff --git a/src/site/apt/development_site_update.apt b/src/site/apt/development_site_update.apt new file mode 100644 index 0000000..240de25 --- /dev/null +++ b/src/site/apt/development_site_update.apt @@ -0,0 +1,34 @@ +~~ Licensed to the Apache Software Foundation (ASF) under one or more +~~ contributor license agreements. See the NOTICE file distributed with +~~ this work for additional information regarding copyright ownership. +~~ The ASF licenses this file to You under the Apache License, Version 2.0 +~~ (the "License"); you may not use this file except in compliance with +~~ the License. You may obtain a copy of the License at +~~ +~~ http://www.apache.org/licenses/LICENSE-2.0 +~~ +~~ Unless required by applicable law or agreed to in writing, software +~~ distributed under the License is distributed on an "AS IS" BASIS, +~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +~~ See the License for the specific language governing permissions and +~~ limitations under the License. + +Updating the Apache VXQuery\x99 site + + * update the <<<site>>> branch in git + + * build a new site and deploy it to <<<../site>>> + +--- +$ mvn site site:deploy +--- + + * submit the site to svn + +--- +$ cd ../site +$ svn st | awk '/\?/ { print $2 }' | xargs svn add # add all new files +$ svn ci -m"updated site" +$ cd - +--- + http://git-wip-us.apache.org/repos/asf/vxquery/blob/94dcab20/src/site/apt/user_cluster_installation.apt ---------------------------------------------------------------------- diff --git a/src/site/apt/user_cluster_installation.apt b/src/site/apt/user_cluster_installation.apt new file mode 100644 index 0000000..1342908 --- /dev/null +++ b/src/site/apt/user_cluster_installation.apt @@ -0,0 +1,149 @@ +~~ Licensed to the Apache Software Foundation (ASF) under one or more +~~ contributor license agreements. See the NOTICE file distributed with +~~ this work for additional information regarding copyright ownership. +~~ The ASF licenses this file to You under the Apache License, Version 2.0 +~~ (the "License"); you may not use this file except in compliance with +~~ the License. You may obtain a copy of the License at +~~ +~~ http://www.apache.org/licenses/LICENSE-2.0 +~~ +~~ Unless required by applicable law or agreed to in writing, software +~~ distributed under the License is distributed on an "AS IS" BASIS, +~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +~~ See the License for the specific language governing permissions and +~~ limitations under the License. + +Cluster Installation + + +* Requirements + + * Apache VXQuery\x99 source archive (apache-vxquery-X.Y-source-release.zip) + + * JDK >= 1.7 + + * Apache Maven >= 3.2 + + +* Steps + + * <<Export JAVA_HOME>> + +--- +$ export JAVA_HOME=/usr/java/latest +--- + + + * <<Unzip and build VXQuery>> + +--- +$ unzip apache-vxquery-X.Y-source-release.zip +$ cd apache-vxquery-X.Y +$ mvn package -DskipTests +$ cd .. +--- + + + * <<Create configuration file>> + + Create a configuration xml file containing the information of the vxquery cluster.Here is an example of a VXQuery configuration file for a cluster with 1 master and 3 slaves. + +--- + <cluster xmlns="cluster"> + <name>local</name> + <username>joe</username> + <master_node> + <id>master</id> + <client_ip>128.195.52.177</client_ip> + <cluster_ip>192.168.100.0</cluster_ip> + </master_node> + <node> + <id>nodeA</id> + <cluster_ip>192.168.100.1</cluster_ip> + </node> + <node> + <id>nodeB</id> + <cluster_ip>192.168.100.2</cluster_ip> + </node> + <node> + <id>nodeC</id> + <cluster_ip>192.168.100.3</cluster_ip> + </node> + </cluster> +--- + + * Fields that are required: + + * name : name of the cluster + + * username : user that will execute commands in all the machines of the cluster. Preferably a user that has passwordless ssh access to the machines. + + * id : hostname of the node + + * cluster_ip : ip of the host in the cluster + + * client_ip : ip of the master + + * Some optional fields: + + * CCPORT : port for the Cluster Controller + + * J_OPTS : define the java options you want, for Cluster Controller and Node Controller + + + * <<Deploy cluster>> + + To deploy the cluster you need to execute this command in the vxquery installation directory + +--- +$python cluster_cli.py -c ../conf/cluster.xml -a deploy -d /apache-vxquery/vxquery-server +--- + + * Arguments: + + * -c : path to the configuration file you created + + * -a : action you want to perform + + * -d : directory in the system to deploy the cluster + + + * <<Start cluster>> + + The command to start the cluster is + +--- +$python cluster_cli.py -c ../conf/cluster.xml -a start +--- + + + * <<Stop cluster>> + + The command to stop the cluster is + +--- +$python cluster_cli.py -c ../conf/cluster.xml -a stop +--- + + + * <<Check process status for Cluster Controller>> + + You can try these commands to check on the status of the processes + +--- +$ps -ef|grep ${USER}|grep java|grep 'Dapp.name=vxquerycc' +--- + + + * <<Check process status for Node Controller>> + +--- +$ps -ef|grep ${USER}|grep java|grep 'Dapp.name=vxquerync' +--- + + + * <<Check process status for hyracks process>> + +--- +$ps -ef|grep ${USER}|grep java|grep 'hyracks' +--- \ No newline at end of file http://git-wip-us.apache.org/repos/asf/vxquery/blob/94dcab20/src/site/site.xml ---------------------------------------------------------------------- diff --git a/src/site/site.xml b/src/site/site.xml index 2828d50..6758899 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -64,7 +64,7 @@ limitations under the License. href="user_installation.html" /> <item name="Cluster Installation" - href="cluster_installation.html" /> + href="user_cluster_installation.html" /> <item name="Executing a Query" href="user_query.html" /> @@ -78,6 +78,9 @@ limitations under the License. name="Get Started" href="developer_get_started.html" /> <item + name="Contributing Code" + href="development_contribution.html" /> + <item name="Data Handling" href="development_data_handling.html" /> <item @@ -93,6 +96,9 @@ limitations under the License. name="Release Steps" href="development_release.html" /> <item + name="Site Update Steps" + href="development_site_update.html" /> + <item name="Update Local Git XQTS Results" href="development_update_xqts_results.html" /> <!-- <item
