Contributing to Jina¶
Thanks for your interest in contributing to Jina. We’re grateful for your initiative! ❤️
I’m Alex C-G, Open Source Evangelist for Jina. I’m all about getting our new contributors up-to-speed, and that’s what we’ll do below.
Join Us on Slack!¶
The best way to know more about contributing and how to get started is to join us on Slack and ask questions in our public channels.
In this guide we’re going to go through the steps for each kind of contribution, and good and bad examples of what to do. We look forward to your contributions!
🏁 Before you Start¶
Not a coder but still want to contribute?¶
We’re happy for any contributions, code or not. If you’d like to write a blog post, record a podcast, organize a meetup, or anything else to contribute to Jina, we’d love to hear from you!
🐞 Bugs and Issues¶
We love to get issue reports. But we love it even more if they’re in the right format. For any bugs you encounter, we need you to:
Describe your problem: What exactly is the bug. Be as clear and concise as possible
Why do you think it’s happening? If you have any insight, here’s where to share it
There are also a couple of nice to haves:
Environment: You can find this with
Screenshots: If they’re relevant
🥇 Making Your First Submission¶
Associate your local git config with your github account. If this is your first time using git you can follow the steps.
Create a new branch, for example
Work on this branch to do the fix/improvement.
Commit the changes with the correct commit style.
Make a pull request.
Submit your pull request and wait for all checks to pass.
Request reviews from one of the code owners.
Get a LGTM 👍 and PR gets merged.
Note: If you’re just fixing a typo or grammatical issue, you can go straight to a pull request.
Associate with github account¶
Confirm username and email on your profile page.
Set git config on your computer.
git config user.name "YOUR GITHUB NAME" git config user.email "YOUR GITHUB EMAIL"
(Optional) Reset the commit author if you made commits before you set the git config.
git checkout YOUR-WORKED-BRANCH git commit --amend --author="YOUR-GITHUB-NAME <YOUR-GITHUB-EMAIL>" --no-edit git log # to confirm the change is effective git push --force
What happens after the merge? Understand the development stage and release cycles here.
git clone won’t clone anything under
jina/hub as it is a Git submodule maintained at
jina-ai/jina-hub. If you want to contribute to
jina-hub, please move to
jina-ai/jina-hub repo and make your contribution.
Most cases when you work on
jina-ai/jina, you don’t need
jina-hub. But just in case for some reason you wish to work with files under
jina/hub (e.g. some integration test), you can use:
git clone https://github.com/jina-ai/jina.git git submodule update --init --remote
At any time, if you want to sync your local files
master@jina-ai/jina-hub, you can always use:
git submodule update --remote
If you are unfamiliar with git submodule, this blog post from Github nicely explains it.
☑️ Naming Conventions¶
For branches, commits, and PRs we follow some basic naming conventions:
Use all lower-case
Include one of our specified types
Short (under 70 characters is best)
In general, follow the Conventional Commit guidelines
Note: If you don’t follow naming conventions, your commit will be automatically flagged to be fixed.
Specify the correct types¶
Type is an important prefix in PR, commit message. For each branch, commit, or PR, we need you to specify the type to help us keep things organized. For example,
feat: add hat wobble ^--^ ^------------^ | | | +-> Summary in present tense. | +-------> Type: chore, docs, feat, fix, refactor, style, or test.
build: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
ci: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
docs: Documentation only changes
feat: A new feature
fix: A bug fix
perf: A code change that improves performance
refactor: A code change that neither fixes a bug nor adds a feature
style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
test: Adding missing tests or correcting existing tests
chore: updating grunt tasks etc; no production code change
Naming your Branch¶
Your branch name should follow the format
typeis one of the types above
scopeis optional, and represents the module your branch is working on.
issue_idis the GitHub issue number. Having the correct issue number will automatically link the Pull Request on this branch to that issue.
fix-executor-loader-113 chore-update-version docs-add-cloud-section-33
||Not descriptive enough, all caps, doesn't follow spec|
||Should be lower case, not descriptive|
||No type, not descriptive|
Writing your Commit Message¶
A good commit message helps us track Jina’s development. A Pull Request with a bad commit message will be rejected automatically in the CI pipeline.
Commit messages should stick to our naming conventions outlined above, and use the format
typeis one of the types above.
scopeis optional, and represents the module your commit is working on.
subjectexplains the commit, without an ending period
For example, a commit that fixes a bug in the executor module should be phrased as:
fix(executor): fix the bad naming in init function
fix(indexer): fix wrong sharding number in indexer feat: add remote api
||All letters should be in lowercase|
||Missing space after
Naming your Pull Request¶
We don’t enforce naming of PRs and branches, but we recommend you follow the same style. It can simply be one of your commit messages, just copy/paste it, e.g.
fix(readme): improve the readability and move sections.
💥 Testing Jina Locally and on CI¶
Locally you can do unittest via:
pip install ".[match-py-ver]" python -m unittest -v
When you add an executor or a driver, you may introduce new dependencies to Jina. You can verify the dependencies via:
, and via Docker container:
docker run jinaai/jina:my-local-version check
It prints a list of components the current version of Jina supports, and then exits. Make sure yours are not in red.
Once you submit the PR, your code will be tested in the environment of Python 3.7 and 3.8 with full exta dependencies (
pip install .[all]) installed.
📖 Contributing Documentation¶
Good docs make developers happy, and we love happy developers! We’ve got a few different types of docs:
Docstrings in Python functions in RST format - generated by Sphinx
These are typically written in Markdown, though some may be in RestructuredText.
If you’re just correcting a typo, feel free to make a pull request. For bigger ones, check out our getting support section to get in touch and discuss more.
Tutorials and Examples¶
This is anything under the Jina Examples repo.
If you’re submitting a new example, be sure to get a good grounding in Jina, go through our previous examples, and test your code.
If you’re making small tweaks to an existing example, make a pull request. For bigger ones, check out our getting support section to get in touch and discuss more.
Docstrings are how we document Jina’s functions. This is suitable for more experienced documentation writers who understand Python functions, docstring formatting, and RestructuredText format.
💬 Getting Support¶
We’re always happy to lend a hand, answer questions, or listen to feedback. You find us here:
We’re also looking at starting online developer hangouts, so you can catch up with us over chat and video, and get to meet your fellow Jina contributors.
🙏 Thank You¶
Once again, thanks so much for your interest in contributing to Jina. We’re excited to see your contributions!