| <rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom"><channel><title>Apache Parquet – Developer Guide</title><link>/docs/contribution-guidelines/</link><description>Recent content in Developer Guide on Apache Parquet</description><generator>Hugo -- gohugo.io</generator><atom:link href="/docs/contribution-guidelines/index.xml" rel="self" type="application/rss+xml"/><item><title>Docs: Modules</title><link>/docs/contribution-guidelines/modules/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>/docs/contribution-guidelines/modules/</guid><description> |
| <p>The <a href="https://github.com/apache/parquet-format">parquet-format</a> project contains format specifications and Thrift definitions of metadata required to properly read Parquet files.</p> |
| <p>The <a href="https://github.com/apache/parquet-mr">parquet-mr</a> project contains multiple sub-modules, which implement the core components of reading and writing a nested, column-oriented data stream, map this core onto the parquet format, and provide Hadoop Input/Output Formats, Pig loaders, and other Java-based utilities for interacting with Parquet.</p> |
| <p>The <a href="https://github.com/apache/parquet-cpp">parquet-cpp</a> project is a C++ library to read-write Parquet files.</p> |
| <p>The <a href="https://github.com/apache/arrow-rs/tree/master/parquet">parquet-rs</a> project is a Rust library to read-write Parquet files.</p> |
| <p>The <a href="https://github.com/Parquet/parquet-compatibility">parquet-compatibility</a> project (deprecated) contains compatibility tests that can be used to verify that implementations in different languages can read and write each other’s files. As of January 2022 compatibility tests only exist up to version 1.2.0.</p></description></item><item><title>Docs: Building Parquet</title><link>/docs/contribution-guidelines/building/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>/docs/contribution-guidelines/building/</guid><description> |
| <p>Building |
| Java resources can be build using <code>mvn package</code>. The current stable version should always be available from Maven Central.</p> |
| <p>C++ thrift resources can be generated via make.</p> |
| <p>Thrift can be also code-genned into any other thrift-supported language.</p></description></item><item><title>Docs: Contributing to Parquet</title><link>/docs/contribution-guidelines/contributing/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>/docs/contribution-guidelines/contributing/</guid><description> |
| <h2 id="pull-requests">Pull Requests</h2> |
| <p>We prefer to receive contributions in the form of GitHub pull requests. Please send pull requests against the <a href="https://github.com/apache/parquet-mr">github.com/apache/parquet-mr</a> repository. If you’ve previously forked Parquet from its old location, you will need to add a remote or update your origin remote to <a href="https://github.com/apache/parquet-mr.git">https://github.com/apache/parquet-mr.git</a> Here are a few tips to get your contribution in:</p> |
| <ol> |
| <li>Break your work into small, single-purpose patches if possible. It’s much harder to merge in a large change with a lot of disjoint features.</li> |
| <li>Create a JIRA for your patch on the <a href="https://issues.apache.org/jira/browse/PARQUET">Parquet Project JIRA</a>.</li> |
| <li>Submit the patch as a GitHub pull request against the master branch. For a tutorial, see the GitHub guides on forking a repo and sending a pull request. Prefix your pull request name with the JIRA name (ex: <a href="https://github.com/apache/parquet-mr/pull/5">https://github.com/apache/parquet-mr/pull/5</a>).</li> |
| <li>Make sure that your code passes the unit tests. You can run the tests with <code>mvn test</code> in the root directory.</li> |
| <li>Add new unit tests for your code.</li> |
| <li>All Pull Requests are tested automatically on <a href="https://github.com/apache/parquet-mr/actions">GitHub Actions</a>. <a href="https://travis-ci.org/github/apache/parquet-mr">TravisCI</a> is also used to run the tests on ARM64 CPU architecture</li> |
| </ol> |
| <p>If you’d like to report a bug but don’t have time to fix it, you can still post it to our <a href="https://issues.apache.org/jira/browse/PARQUET">issue tracker</a>, or email the mailing list (<a href="mailto:dev@parquet.apache.org">dev@parquet.apache.org</a>).</p> |
| <h2 id="committers">Committers</h2> |
| <p>Merging a pull request requires being a comitter on the project.</p> |
| <p>How to merge a Pull request (have an apache and github-apache remote setup):</p> |
| <pre><code>git remote add github-apache git@github.com:apache/parquet-mr.git |
| git remote add apache https://gitbox.apache.org/repos/asf?p=parquet-mr.git |
| </code></pre> |
| <p>run the following command</p> |
| <pre><code>dev/merge_parquet_pr.py |
| </code></pre> |
| <p>example output:</p> |
| <pre><code>Which pull request would you like to merge? (e.g. 34): |
| </code></pre> |
| <p>Type the pull request number (from <a href="https://github.com/apache/parquet-mr/pulls">https://github.com/apache/parquet-mr/pulls</a>) and hit enter.</p> |
| <pre><code>=== Pull Request #X === |
| title Blah Blah Blah |
| source repo/branch |
| target master |
| url https://api.github.com/repos/apache/parquet-mr/pulls/X |
| Proceed with merging pull request #3? (y/n): |
| </code></pre> |
| <p>If this looks good, type <code>y</code> and hit enter.</p> |
| <pre><code>From gitbox.apache.org:/repos/asf/parquet-mr.git |
| * [new branch] master -&gt; PR_TOOL_MERGE_PR_3_MASTER |
| Switched to branch 'PR_TOOL_MERGE_PR_3_MASTER' |
| Merge complete (local ref PR_TOOL_MERGE_PR_3_MASTER). Push to apache? (y/n): |
| </code></pre> |
| <p>A local branch with the merge has been created. Type <code>y</code> and hit enter to push it to apache master</p> |
| <pre><code>Counting objects: 67, done. |
| Delta compression using up to 4 threads. |
| Compressing objects: 100% (26/26), done. |
| Writing objects: 100% (36/36), 5.32 KiB, done. |
| Total 36 (delta 17), reused 0 (delta 0) |
| To gitbox.apache.org:/repos/asf/parquet-mr.git |
| b767ac4..485658a PR_TOOL_MERGE_PR_X_MASTER -&gt; master |
| Restoring head pointer to b767ac4e |
| Note: checking out 'b767ac4e'. |
| You are in 'detached HEAD' state. You can look around, make experimental |
| changes and commit them, and you can discard any commits you make in this |
| state without impacting any branches by performing another checkout. |
| If you want to create a new branch to retain commits you create, you may |
| do so (now or later) by using -b with the checkout command again. Example: |
| git checkout -b new_branch_name |
| HEAD is now at b767ac4... Update README.md |
| Deleting local branch PR_TOOL_MERGE_PR_X |
| Deleting local branch PR_TOOL_MERGE_PR_X_MASTER |
| Pull request #X merged! |
| Merge hash: 485658a5 |
| Would you like to pick 485658a5 into another branch? (y/n): |
| </code></pre> |
| <p>For now just say <code>n</code> as we have 1 branch</p> |
| <h2 id="website">Website</h2> |
| <h3 id="release-documentation">Release Documentation</h3> |
| <p>To create documentation for a new release of <code>parquet-format</code> create a new <releaseNumber>.md file under <code>content/en/blog/parquet-format</code>. Please see existing files in that directory as an example.</p> |
| <p>To create documentation for a new release of <code>parquet-mr</code> create a new <releaseNumber>.md file under <code>content/en/blog/parquet-mr</code>. Please see existing files in that directory as an example.</p> |
| <h3 id="website-development-and-deployment">Website development and deployment</h3> |
| <h4 id="staging">Staging</h4> |
| <p>To make a change to the <code>staging</code> version of the website:</p> |
| <ol> |
| <li>Make a PR against the <code>staging</code> branch in the repository</li> |
| <li>Once the PR is merged, the <code>Build and Deploy Parquet Site</code> |
| job in the <a href="https://github.com/apache/parquet-site/blob/staging/.github/workflows/deploy.yml">deployment workflow</a> will be run, populating the <code>asf-staging</code> branch on this repo with the necessary files.</li> |
| </ol> |
| <p><strong>Do not directly edit the <code>asf-staging</code> branch of this repo</strong></p> |
| <h4 id="production">Production</h4> |
| <p>To make a change to the <code>production</code> version of the website:</p> |
| <ol> |
| <li>Make a PR against the <code>production</code> branch in the repository</li> |
| <li>Once the PR is merged, the <code>Build and Deploy Parquet Site</code> |
| job in the <a href="https://github.com/apache/parquet-site/blob/production/.github/workflows/deploy.yml">deployment workflow</a> will be run, populating the <code>asf-site</code> branch on this repo with the necessary files.</li> |
| </ol> |
| <p><strong>Do not directly edit the <code>asf-site</code> branch of this repo</strong></p></description></item><item><title>Docs: Releasing Parquet</title><link>/docs/contribution-guidelines/releasing/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>/docs/contribution-guidelines/releasing/</guid><description> |
| <h3 id="setup">Setup</h3> |
| <p>You will need: * PGP code signing keys, published in <a href="https://downloads.apache.org/parquet/KEYS">KEYS</a> * Permission to stage artifacts in Nexus</p> |
| <p>Make sure you have permission to deploy Parquet artifacts to Nexus by pushing a snapshot:</p> |
| <pre><code>mvn deploy |
| </code></pre> |
| <p>If you have problems, read the <a href="https://www.apache.org/dev/publishing-maven-artifacts.html">publishing Maven artifacts documentation</a></p> |
| <h3 id="release-process">Release process</h3> |
| <p>Parquet uses the maven-release-plugin to tag a release and push binary artifacts to staging in Nexus. Once maven completes the release, the offical source tarball is built from the tag.</p> |
| <p>Before you start the release process:</p> |
| <ol> |
| <li>Verify that the release is finished (no planned JIRAs are pending)</li> |
| <li>Build and test the project</li> |
| <li>Update the change log |
| <ul> |
| <li>Go to the release notes for the release in JIRA</li> |
| <li>Copy the HTML and convert it to markdown with an <a href="https://domchristie.github.io/turndown/">online converter</a></li> |
| <li>Add the content to CHANGES.md and update formatting</li> |
| <li>Commit the update to CHANGES.md</li> |
| </ul> |
| </li> |
| </ol> |
| <h4 id="1-run-the-prepare-script">1. Run the prepare script</h4> |
| <pre><code>dev/prepare-release.sh &lt;version&gt; &lt;rc-number&gt; |
| </code></pre> |
| <p>This runs maven’s release prepare with a consistent tag name. After this step, the release tag will exist in the git repository.</p> |
| <p>If this step fails, you can roll back the changes by running these commands.</p> |
| <pre><code>find ./ -type f -name '*.releaseBackup' -exec rm {} \; |
| find ./ -type f -name 'pom.xml' -exec git checkout {} \; |
| </code></pre> |
| <h4 id="2-run-releaseperform-to-stage-binaries">2. Run release:perform to stage binaries</h4> |
| <pre><code>mvn release:perform |
| </code></pre> |
| <p>This uploads binary artifacts for the release tag to <a href="https://repository.apache.org/">Nexus</a>.</p> |
| <h4 id="3-in-nexus-close-the-staging-repository">3. In Nexus, close the staging repository</h4> |
| <p>Closing a staging repository makes the binaries available in <a href="https://repository.apache.org/content/groups/staging/org/apache/parquet/">staging</a>, but does not publish them.</p> |
| <ol> |
| <li>Go to <a href="https://repository.apache.org/">Nexus</a>.</li> |
| <li>In the menu on the left, choose “Staging Repositories”.</li> |
| <li>Select the Parquet repository.</li> |
| <li>At the top, click “Close” and follow the instructions. For the comment use “Apache Parquet [Format] ”.</li> |
| </ol> |
| <h4 id="4-run-the-source-tarball-script">4. Run the source tarball script</h4> |
| <pre><code>dev/source-release.sh &lt;version&gt; &lt;rc-number&gt; |
| </code></pre> |
| <p>This script builds the source tarball from the release tag’s SHA1, signs it, and uploads the necessary files with SVN.</p> |
| <p>The source release is pushed to <a href="https://dist.apache.org/repos/dist/dev/parquet/">https://dist.apache.org/repos/dist/dev/parquet/</a></p> |
| <p>The last message from the script is the release commit’s SHA1 hash and URL for the VOTE e-mail.</p> |
| <h4 id="5-send-a-vote-e-mail-to-devparquetapacheorgmailtodevparquetapacheorg">5. Send a VOTE e-mail to <a href="mailto:dev@parquet.apache.org">dev@parquet.apache.org</a></h4> |
| <p>Here is a template you can use. Make sure everything applies to your release.</p> |
| <pre><code>Subject: [VOTE] Release Apache Parquet &lt;VERSION&gt; RC&lt;NUM&gt; |
| Hi everyone, |
| I propose the following RC to be released as official Apache Parquet &lt;VERSION&gt; release. |
| The commit id is &lt;SHA1&gt; |
| * This corresponds to the tag: apache-parquet-&lt;VERSION&gt;-rc&lt;NUM&gt; |
| * https://github.com/apache/parquet-mr/tree/&lt;SHA1&gt; |
| The release tarball, signature, and checksums are here: |
| * https://dist.apache.org/repos/dist/dev/parquet/&lt;PATH&gt; |
| You can find the KEYS file here: |
| * https://downloads.apache.org/parquet/KEYS |
| Binary artifacts are staged in Nexus here: |
| * https://repository.apache.org/content/groups/staging/org/apache/parquet/ |
| This release includes important changes that I should have summarized here, but I'm lazy. |
| Please download, verify, and test. |
| Please vote in the next 72 hours. |
| [ ] +1 Release this as Apache Parquet &lt;VERSION&gt; |
| [ ] +0 |
| [ ] -1 Do not release this because... |
| </code></pre> |
| <h3 id="publishing-after-the-vote-passes">Publishing after the vote passes</h3> |
| <p>After a release candidate passes a vote, the candidate needs to be published as the final release.</p> |
| <h4 id="1-tag-final-release-and-set-development-version">1. Tag final release and set development version</h4> |
| <pre><code>dev/finalize-release &lt;release-version&gt; &lt;rc-num&gt; &lt;new-development-version-without-SNAPSHOT-suffix&gt; |
| </code></pre> |
| <p>This will add the final release tag to the RC tag and sets the new development version in the pom files. If everything is fine push the changes and the new tag to github: <code>git push --follow-tags</code></p> |
| <h4 id="2-release-the-binary-repository-in-nexus">2. Release the binary repository in Nexus</h4> |
| <h4 id="3-copy-the-release-artifacts-in-svn-into-releases">3. Copy the release artifacts in SVN into releases</h4> |
| <p>First, check out the candidates and releases locations in SVN:</p> |
| <pre><code>mkdir parquet |
| cd parquet |
| svn co https://dist.apache.org/repos/dist/dev/parquet candidates |
| svn co https://dist.apache.org/repos/dist/release/parquet releases |
| </code></pre> |
| <p>Next, copy the directory for the release candidate the passed from candidates to releases and rename it; remove the “-rcN” part of the directory name.</p> |
| <pre><code>cp -r candidates/apache-parquet-&lt;VERSION&gt;-rcN/ releases/apache-parquet-&lt;VERSION&gt; |
| </code></pre> |
| <p>Then add and commit the release artifacts:</p> |
| <pre><code>cd releases |
| svn add apache-parquet-&lt;version&gt; |
| svn ci -m &quot;Parquet: Add release &lt;VERSION&gt;&quot; |
| </code></pre> |
| <h4 id="4-update-parquetapacheorg">4. Update parquet.apache.org</h4> |
| <p>Update the downloads page on parquet.apache.org. Instructions for updating the site are on the <a href="http://parquet.apache.org/docs/contribution-guidelines/contributing/">contribution page</a>.</p> |
| <h4 id="5-send-an-announce-e-mail-to-announceapacheorgmailtoannounceapacheorg-and-the-dev-list">5. Send an ANNOUNCE e-mail to <a href="mailto:announce@apache.org">announce@apache.org</a> and the dev list</h4> |
| <pre><code>[ANNOUNCE] Apache Parquet release &lt;VERSION&gt; |
| I'm please to announce the release of Parquet &lt;VERSION&gt;! |
| Parquet is a general-purpose columnar file format for nested data. It uses |
| space-efficient encodings and a compressed and splittable structure for |
| processing frameworks like Hadoop. |
| Changes are listed at: https://github.com/apache/parquet-mr/blob/apache-parquet-&lt;VERSION&gt;/CHANGES.md |
| This release can be downloaded from: https://parquet.apache.org/downloads/ |
| Java artifacts are available from Maven Central. |
| Thanks to everyone for contributing! |
| </code></pre></description></item></channel></rss> |
