src/site/apt/development_contribution.apt

~~ 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 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.>>

    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.
      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
      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.

    * 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 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.

      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.

    * 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 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)

  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.

    * 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>> (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.