Guide for Contributors

How to Contribute to jq

First you'll need a GitHub account.

Then you'll need to visit https://github.com/jqlang/jq and click on the fork button.

The you'll need a development environment, which could be a Linux system or virtual machine, or a FreeBSD one, or a Windows one, and so on. You'll need a shell where you can run git, and you'll need a C development environment (i.e., install C compilers and various other tools). The complete set of things to install is actually documented in jq's GitHub Actions workflows for every OS for which jq has workflows defined. For example, for Linux you'll need to run sudo apt-get install -y build-essential automake autoconf bison flex gdb python3 valgrind clang-tools.

Then you'll need to git clone https://github.com/jqlang/jq and add your fork as a remote, doing something like this in a shell:

$ git clone https://github.com/jqlang/jq
$ cd jq
$ git remote add ${your_github_username_here} [email protected]:${your_github_username_here}/jq
$ git fetch ${your_github_username_here}

Next you'll need to familiarize yourself with jq's source code. See the rest of this wiki for details on jq's internals.

When you're ready you should make a branch for your work:

$ git checkout -b ${your_branch_name}

then edit source files and Makefiles as needed, get jq to build and pass tests.

To build jq you'll need to run something like:

$ autoreconf -fi
$ ./configure --enable-maintainer-mode --with-oniguruma=builtin
$ make -j4 check

Don't forget to update the manual (docs/content/manual/manual.yml) and also to update the jq.1.prebuilt and tests/man.test files if you updated the docs.

You'll then need to make one or more Git commits for your work, such as by running git commit -a. Some familiarity with Git is assumed here.

Making a Pull Request

When you're ready you should do something like this:

$ git push ${your_github_username_here} ${your_branch_name}

then visit your fork on the GitHub site, click on "Create Pull Request" and follow the instructions there.

Responding to Pull Request Reviews

You may get feedback on your PR. You should get email from GitHub, or just visit your PR's page and scroll.

You will most likely have to make changes in response to the review commentary that you receive on your PR. When you make changes, please please please do NOT use a "merge workflow".

Make changes as needed, add new commits or "fixup" commits as needed, then push or even force-push your branch to your fork.

Below you'll see instructions on how to create commits that the jq maintainers like.

Git is Difficult -- jq maintainers might help you

It's possible that you'll have trouble understanding these instructions, and sometimes jq maintainers may help you by re-writing your branch's commits to their liking and then force-pushing to your PR. This is normal. If this happens, do not push your work to your PR. Instead you should make a backup of your branch then adopt the changes that were pushed by the maintainers to your PR, like this:

$ git branch ${your_branch_name}-save ${your_branch_name}
$ git fetch ${your_github_username_here}
$ git checkout -f ${your_github_username_here}/${your_branch_name}
$ git branch -ft ${your_branch_name} ${your_github_username_here}/${your_branch_name}

Using Git Like a Pro: Git Rebase Workflows

Many users run for the hills when they hear "git rebase". Please don't be scared. It's easy.

Let's say you've created a PR, and now a bunch of unrelated things have been pushed to the upstream (most likely named origin/master from your perspective)... and you want or need to have your changes "catch up" with the upstream. In a "merge workflow" you might run git pull --merge to do so, but please do not do this! Instead we highly recommend git pull --rebase.

Rebase vs. Merge Mechanics

With a "rebase" you'll see that git will "replay" your branch's commits on top of the new upstream head commit, and each of those can have conflicts, and each time there are conflicts you'll have to resolve them and then git add and then git rebase --continue. With a "merge" you'll only have one round of conflict resolution. That's it -- that's the difference from your perspective.

So don't be afraid of git rebase.

Rebasing for Fun and Profit

Sometimes -not often, hopefully- you'll need to combine ("squash") two commits, split a commit, or re-order your commits. This is how you'll do that:

$ git rebase -i origin/master

which will start your $EDITOR with a file buffer whose contents has a) a list of commits that will be "rebased", b) instructions. Read those instructions!

Reordering commits will be as simple as moving pick lines around in that file buffer.

Squashing commits will be as simple as changing a pick line to say squash or fixup.

Rewording a commit's commit message will be as simple as changing a pick to reword.

Splitting commits is harder, and out of scope for this small wiki page for now.

When you're done with your edits to this file buffer, save and quit, and Git will execute your instructions.

If there are conflicts you can:

• attempt to resolve them
• if you conclude that you needed to use a different rebase plan (for example, maybe a particular re-ordering of commits ends up making no sense as you moved one ahead of another that it depended on) you might git rebase --abort and try again
• if you resolve the conflicts successfully you'll git add then git rebase --continue

You might have to do multiple git rebase -i origin/master operations to get it right.

Getting Help with Git

If you don't know your way around Git, don't be afraid to say so on your PR and ask for help. The maintainers are a friendly bunch and will help you as time permits them.

As you learn to use Git, you may find this Guide to Git Noobies and would-be Power-Users useful.