Local git conventions#

If you are tracking the Arrow source repository locally, here is achecklist for usinggit:

• Work off of yourpersonal fork ofapache/arrow and submit pull requests“upstream”.

• Keep your fork’smain branch synced withupstream/main.

• Develop on branches, rather than your own “main” branch.

• It does not matter what you call your branch. Some people like to use the GitHubissue number as branch name, others use descriptive names.

• Sync your branch withupstream/mainregularly, as many commits aremerged to main every day.

• It is recommended to usegitrebase rather thangitmerge.

• In case there are conflicts, and your local commit history has multiple commits,you may simplify the conflict resolution process bysquashing your local commitsinto a single commit. Preserving the commit history isn’t as important becausewhen your feature branch is merged upstream, a squash happens automatically.

  How to squash local commits?

  Abort the rebase with:

  $gitrebase--abort

  Following which, the local commits can be squashed interactively by running:

  $gitrebase--interactiveORIG_HEAD~n

  Wheren is the number of commits you have in your local branch. After the squash,you can try the merge again, and this time conflict resolution should be relativelystraightforward.

  Once you have an updated local copy, you can push to your remote repo. Note, since yourremote repo still holds the old history, you would need to do a force push. Most pushesshould use--force-with-lease:

  $gitpush--force-with-leaseoriginbranch

  The option--force-with-lease will fail if the remote has commits that are not availablelocally, for example if additional commits have been made by a colleague. By using--force-with-lease instead of--force, you ensure those commits are not overwrittenand can fetch those changes if desired.

  Setting rebase to be default

  If you set the following in your repo’s.git/config, the--rebase option can beomitted from thegitpull command, as it is implied by default.

  [pull]      rebase = true

Pull request and review#

When contributing a patch, use this list as a checklist of Apache Arrow workflow:

• Submit the patch as aGitHub pull request against themain branch.

• So that your pull request syncs with the GitHub issue,prefix your pull requesttitle with the GitHub issue id (ex:GH-14866: [C++] Remove internal GroupBy implementation).

• Give the pull request aclear, brief description: when the pull request ismerged, this will be retained in the extended commit message.

• Make sure that your codepasses the unit tests. You can find instructions howto run the unit tests for each Arrow component in its respective README file.

Core developers and others with a stake in the part of the project your changeaffects will review, request changes, and hopefully indicate their approvalin the end. To make the review process smooth for everyone, try to

• 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,and particularly if you’re new to the project, smaller changes are much easierfor maintainers to accept.

• Add new unit tests for your code.

• Follow the style guides for the part(s) of the project you’re modifying.

  Some languages (C++ and Python, for example) run a lint check incontinuous integration. For all languages, see their respective developerdocumentation and READMEs for style guidance.

• Try to make it look as if the codebase has a single author,and emulate any conventions you see, whether or not they are officiallydocumented or checked.

When tests are passing and the pull request has been approved by the interestedparties, acommitterwill merge the pull request. This is done with acommand-line utility that does a squash merge.

Experimental repositories#

Apache Arrow has an explicit policy over developing experimental repositoriesin the context ofrules for revolutionaries.

The main motivation for this policy is to offer a lightweight mechanism toconduct experimental work, with the necessary creative freedom, within the ASFand the Apache Arrow governance model. This policy allows committers to work onnew repositories, as they offer many important tools to manage it (e.g. githubissues, “watch”, “github stars” to measure overall interest).

Guidance for specific features#

From time to time the community has discussions on specific types of featuresand improvements that they expect to support. This section outlines decisionsthat have been made in this regard.