Preparing the site for the next release. 171/head
authorPreston Carman <prestonc@apache.org>
Sun, 4 Jun 2017 19:48:53 +0000 (12:48 -0700)
committerPreston Carman <prestonc@apache.org>
Wed, 7 Jun 2017 22:00:46 +0000 (15:00 -0700)
- Updating the index page to highlight JSONiq extension to XQuery.
- Fixing issue with JavaDocs.
- Adding contribution details with git commands.

src/site/apt/development_contribution.apt
src/site/apt/index.apt
src/site/resources/images/vxquery_stack.png
vxquery-core/src/main/java/org/apache/vxquery/runtime/functions/step/ChildPathStepUnnesting.java
vxquery-core/src/main/java/org/apache/vxquery/runtime/functions/step/DescendantOrSelfPathStepUnnesting.java
vxquery-core/src/main/java/org/apache/vxquery/runtime/functions/util/FunctionHelper.java

index f767cfd..c64bad2 100644 (file)
@@ -17,7 +17,7 @@ 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.
+  to answer questions 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.>>
@@ -55,13 +55,19 @@ Contributing Code
       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.
+      The authors_username is very important when reviewing a developers code on your own machine.
 
+---
+git checkout master
+git pull
+git branch prestonc/vxquery_142
+git checkout prestonc/vxquery_142
+---
 
     * 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
@@ -82,12 +88,19 @@ Contributing Code
 
       Remove an extra debug code and verify the patch only includes code for the change.
 
+    * Commit and push code.
+
+      Commit changes to the branch and push to github.
+
 
     * 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.
+      The branch should be up-to-date with the latest Apache VXQuery master branch.
+
+      Git rebase is a nice option for keeping your code up-to-date with master without messing up the Pull Request.
+      (Merge will show changes in master as your changes on your branch.)
 
 
     * Post your Pull Request.
@@ -96,16 +109,41 @@ Contributing Code
       At least one other member of the community should review the change.
       If there is any feedback, address this and repeat the posting process.
 
+    * Update your Pull Request.
+
+      Update your change to address any comments from reviewers.
+
+    * Prepare your change for merge.
+
+      Squash your changes into a single commit with a nice commit message.
+      The commit message's first line should be less than 50 character and any additional comments
+      are included below a blank line.
+
+---
+VXQUERY-142: fn:doc support for source files
+
+The fn:doc function now supports reading files defined in the test suite XML source tag.
+---
+
+      Git rebase has a option of merging commits into a single commit that works nicely for squashing your changes.
+      ({{{http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html}git ready}} has a nice example.)
+      Although, this will not work if you happened use merge when updated to the latest master branch.
+
+
 ** Code Reviewer
 
     * Review the Pull Request.
 
-      Post inline or global comments for the developer.
+      Post in-line 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.
 
+      Each Pull Request automatically triggers a {{{https://asterix-jenkins.ics.uci.edu/job/vxquery-pr/}VXQuery Jenkins}}
+      job that runs all the tests.
+
+
 
 ** VXQuery Committer (author or sponsor of the change)
 
@@ -114,9 +152,39 @@ Contributing Code
   they are pushing on to the repository.
   Often the committer will also be the reviewer for non-committer changes.
 
+    * Add ASF as a git remote (first time committers).
+
+      Create a git remote for ASF repository. {{{https://git-wip-us.apache.org/repos/asf/vxquery.git}}}
+
     * Double check the VXQuery and XQTS tests.
 
+      A {{{https://asterix-jenkins.ics.uci.edu/job/vxquery-pr/}VXQuery Jenkins}} instance has been set up to
+      check the last ten Pull Requests.
+      The Pull Request being reviewed should pass all tests.
+      Each commit to a Pull Request will trigger a new test run.
+      Confirm the last test run passes all the tests.
+
+    * Double check the change.
+
+      Confirm the change has a single commit and includes a nice commit message.
+
     * Merge the change with ASF master.
 
-      When merging the change, do not rebase.
+      When merging the change, do not <<rebase>> (we do not want to change the Apache commit history).
       Instead do a single merge commit into Apache VXQuery master.
+      Since the Pull Request now has a single commit, an alternative would be to cherry pick that commit
+      from the given branch into master.
+
+---
+git checkout master
+git merge prestonc/vxquery_142
+git log
+---
+
+      Review the log to confirm the history is correct.
+
+
+    * Push change to ASF remote.
+
+      Confirm the log is correct on your local master.
+      Push master to the ASF remote.
index 3986f81..919bf1f 100644 (file)
@@ -16,8 +16,9 @@
 Apache VXQuery
 
   Apache VXQuery\x99 will be a standards compliant XML Query processor implemented in Java.
-  The focus is on the evaluation of queries on large amounts of XML data.
-  Specifically the goal is to evaluate queries on large collections of relatively small XML documents.
+  The XQuery processor supports the {{{http://www.jsoniq.org/}JSONiq}} extension to XQuery.
+  The focus is on the evaluation of queries on large amounts of JSON and XML data.
+  Specifically the goal is to evaluate queries on large collections of relatively small JSON or XML documents.
   To achieve this queries will be evaluated on a cluster of shared nothing machines.
 
   There are lots of large collections of relatively small documents like e.g. the {{{http://www.sec.gov/info/edgar/ednews/dissemin.htm}EDGAR dataset}} or the {{{http://wiki.openstreetmap.org/wiki/Download}OpenStreetMap dataset}}.
index 01549a5..5a0efe5 100644 (file)
Binary files a/src/site/resources/images/vxquery_stack.png and b/src/site/resources/images/vxquery_stack.png differ
index 9026de3..03b9cf3 100644 (file)
@@ -18,7 +18,6 @@ package org.apache.vxquery.runtime.functions.step;
 
 import java.io.IOException;
 
-import org.apache.hyracks.algebricks.common.exceptions.AlgebricksException;
 import org.apache.hyracks.api.context.IHyracksTaskContext;
 import org.apache.hyracks.api.exceptions.HyracksDataException;
 import org.apache.hyracks.data.std.api.IPointable;
@@ -109,7 +108,7 @@ public class ChildPathStepUnnesting extends AbstractForwardAxisPathStep {
      * @param result
      *            result
      * @return found result
-     * @throws AlgebricksException
+     * @throws HyracksDataException
      *             Could not save result.
      */
     protected boolean stepNodeTree(TaggedValuePointable tvpInput, int level, IPointable result)
index 305e26d..facbee3 100644 (file)
@@ -20,7 +20,6 @@ import java.io.IOException;
 import java.util.ArrayList;
 import java.util.List;
 
-import org.apache.hyracks.algebricks.common.exceptions.AlgebricksException;
 import org.apache.hyracks.api.context.IHyracksTaskContext;
 import org.apache.hyracks.api.exceptions.HyracksDataException;
 import org.apache.hyracks.data.std.api.IPointable;
@@ -141,7 +140,7 @@ public class DescendantOrSelfPathStepUnnesting extends AbstractForwardAxisPathSt
      * @param result
      *            result
      * @return found result
-     * @throws AlgebricksException
+     * @throws HyracksDataException
      *             Could not save result.
      */
     protected boolean stepNodeTree(TaggedValuePointable tvpInput, int level, IPointable result)
index 7c3197a..6558274 100644 (file)
@@ -1359,15 +1359,16 @@ public class FunctionHelper {
     }
 
     /**
-     * Writes a number to the DataOutput with zeros as place holders if the number is too small to fill the padding.
+     * Writes a number to the string builder with zeros as place holders if the number is too small to fill the padding.
      *
      * @param valueArg
      *            value
      * @param paddingArg
      *            padding
-     * @param dOut
-     *            data output
+     * @param sb
+     *            string builder
      * @throws IOException
+     *             Could not save result.
      */
     public static void writeNumberWithPadding(long valueArg, int paddingArg, UTF8StringBuilder sb) throws IOException {
         long value = valueArg;