From b37b1643ce2c05aab5d784d7c709bd6d9c840b3b Mon Sep 17 00:00:00 2001 From: Fokko Driesprong Date: Tue, 6 Aug 2024 11:29:08 +0200 Subject: [PATCH] GH-80: Update `contributing.md` (#76) --- .../Contribution Guidelines/contributing.md | 96 ++++++------------- 1 file changed, 29 insertions(+), 67 deletions(-) diff --git a/content/en/docs/Contribution Guidelines/contributing.md b/content/en/docs/Contribution Guidelines/contributing.md index b9655567..6516de0f 100644 --- a/content/en/docs/Contribution Guidelines/contributing.md +++ b/content/en/docs/Contribution Guidelines/contributing.md @@ -1,97 +1,59 @@ --- -title: "Contributing to Parquet" -linkTitle: "Contributing to Parquet" +title: "Contributing to Parquet-Java" +linkTitle: "Contributing to Parquet-Java" weight: 3 description: > - How to contribute to Parquet + How to contribute to Parquet-Java --- Pull Requests ------------- -We prefer to receive contributions in the form of GitHub pull requests. Please send pull requests against the [github.com/apache/parquet-mr](https://github.com/apache/parquet-mr) repository. If you’ve previously forked Parquet from its old location, you will need to add a remote or update your origin remote to [https://github.com/apache/parquet-mr.git](https://github.com/apache/parquet-mr.git) Here are a few tips to get your contribution in: +We prefer to receive contributions in the form of GitHub pull requests. Please send pull requests against the [github.com/apache/parquet-java](https://github.com/apache/parquet-java) repository. If you’ve previously forked Parquet from its old location, you will need to add a remote or update your origin remote to [https://github.com/apache/parquet-java.git](https://github.com/apache/parquet-java.git). Here are a few tips to get your contribution in: 1. 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. -2. Create a JIRA for your patch on the [Parquet Project JIRA](https://issues.apache.org/jira/browse/PARQUET). -3. 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: [https://github.com/apache/parquet-mr/pull/5](https://github.com/apache/parquet-mr/pull/5)). +2. Create an Issue on the [Parquet-Java issues](https://github.com/apache/parquet-java/issues). +3. 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 Issue `GH-2935`: (ex: [https://github.com/apache/parquet-java/pull/2951](https://github.com/apache/parquet-java/pull/2951)). 4. Make sure that your code passes the unit tests. You can run the tests with `mvn test` in the root directory. 5. Add new unit tests for your code. -6. All Pull Requests are tested automatically on [GitHub Actions](https://github.com/apache/parquet-mr/actions). [TravisCI](https://travis-ci.org/github/apache/parquet-mr) is also used to run the tests on ARM64 CPU architecture +6. All Pull Requests are tested automatically on [GitHub Actions](https://github.com/apache/parquet-java/actions). -If you’d like to report a bug but don’t have time to fix it, you can still post it to our [issue tracker](https://issues.apache.org/jira/browse/PARQUET), or email the mailing list ([dev@parquet.apache.org](mailto:dev@parquet.apache.org)). +If you’d like to report a bug but don’t have time to fix it, you can still [raise an issue](https://github.com/apache/parquet-java/issues), or email the mailing list ([dev@parquet.apache.org](mailto:dev@parquet.apache.org)). Committers ---------- -Merging a pull request requires being a committer on the project. +### Merging a Pull Request -How to merge a Pull request (have an apache and github-apache remote setup): +Merging a pull request requires being a committer on the project and approval of the PR by a committer who is not the author. - 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 +A pull request can be merged through the GitHub UI. By default, only [squash and merge](https://github.com/apache/parquet-java/blob/824b7d009eb41539cb0e2f73110efc0ac5694251/.asf.yaml#L29) is enabled on the project. +When the PR solves an existing issue, ensure that it references the issue in the Pull-Request template `Closes #1234`. This way the issue is linked to the PR, and GitHub will automatically close the relevant issue when the PR is being merged. -run the following command +### Tracking issues using Milestones - dev/merge_parquet_pr.py +When a PR is raised that fixes a bug, or a feature that you want to target a certain version, make sure to attach a [milestone](https://github.com/apache/parquet-java/milestones). This way other committers can track certain versions, and see what is still pending. For information on the actual release, please check [the release page](releasing.md). +### Maintenance branches -example output: +Once a PR has been merged to master, it can be that the commit needs to be backported to maintenance [branches](https://github.com/apache/parquet-java/branches), (ex: [1.14.x](https://github.com/apache/parquet-java/tree/parquet-1.14.x)). The easiest way is to do this locally: - Which pull request would you like to merge? (e.g. 34): +Make sure that the remote is set up correctly: +```sh +git remote add github-apache git@github.com:apache/parquet-java.git +``` -Type the pull request number (from [https://github.com/apache/parquet-mr/pulls](https://github.com/apache/parquet-mr/pulls)) and hit enter. +Now you can cherry-pick a PR to a previous branch: - === 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): - - -If this looks good, type `y` and hit enter. - - From gitbox.apache.org:/repos/asf/parquet-mr.git - * [new branch] master -> 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): - - -A local branch with the merge has been created. Type `y` and hit enter to push it to apache master - - 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 -> 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): - - -For now just say `n` as we have 1 branch +```sh +get fetch --all +git checkout parquet-1.14.x +git reset --hard github-apache/parquet-1.14.x +git cherry-pick +git push github-apache/parquet-1.14.x +``` Website ------- @@ -99,7 +61,7 @@ Website To create documentation for a new release of `parquet-format` create a new .md file under `content/en/blog/parquet-format`. Please see existing files in that directory as an example. -To create documentation for a new release of `parquet-mr` create a new .md file under `content/en/blog/parquet-mr`. Please see existing files in that directory as an example. +To create documentation for a new release of `parquet-java` create a new .md file under `content/en/blog/parquet-java`. Please see existing files in that directory as an example. ### Website development and deployment