You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@vxquery.apache.org by pr...@apache.org on 2015/07/16 18:58:16 UTC
vxquery git commit: Developer contribution documentation for the site.
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 <pr...@apache.org>
Authored: Thu Jul 16 09:57:43 2015 -0700
Committer: Preston Carman <pr...@apache.org>
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