-
Notifications
You must be signed in to change notification settings - Fork 1.6k
Guide for Contributors
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.
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.
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.
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}
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
.
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
.
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
thengit rebase --continue
You might have to do multiple git rebase -i origin/master
operations to get it right.
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.
- Home
- FAQ
- jq Language Description
- Cookbook
- Modules
- Parsing Expression Grammars
- Docs for Oniguruma Regular Expressions (RE.txt)
- Advanced Topics
- Guide for Contributors
- How To
- C API
- jq Internals
- Tips
- Development