Community#

You can check out Kagi on GitHub at: https://github.com/justinmayer/kagi

Communication channels#

How to contribute#

Thanks for your interest in contributing to Kagi!

Note

We love community feedback and are glad to review contributions of any size — from typos in the documentation to critical bug fixes — so don’t be shy!

Report bugs#

Report bugs at https://github.com/justinmayer/kagi/issues/new

If you are reporting a bug, please include:

  • Any details about your local setup that might be helpful in troubleshooting.

  • Detailed steps to reproduce the bug.

Fix bugs#

Check out the open issues - anything tagged with the good-first-issue label could be a good choice for newcomers.

Implement features#

Look through the GitHub issues for features. Anything tagged with enhancement is open to whoever wants to implement it.

Write documentation#

Kagi could always use more documentation, whether as part of the official docs, in docstrings, or even on the Web in blog posts, articles, and such.

This official documentation is maintained in GitHub. The docs folder contains the documentation sources in reStructuredText format. And you can generate the docs locally with:

invoke docs

Output is written at docs/_build/html/index.html.

We obviously accept pull requests for this documentation, just as we accept them for bug fixes and features! See open issues.

Submit feedback#

Any issue with the question label is open for feedback, so feel free to share your thoughts with us!

The best way to send feedback is to file a new issue on GitHub.

If you are proposing a feature:

  • Explain how you envision it working. Try to be as detailed as you can.

  • Try to keep the scope as narrow as possible. This will help make it easier to implement.

  • Feel free to include any code you might already have, even if it’s just a rough idea. This is a volunteer-driven project, and contributions are welcome. :)

Contributing#

We welcome your contributions to Kagi and strive to make it as easy as possible to participate.

Quick Set-up#

First, install Poetry:

curl -sSL https://install.python-poetry.org/ | python -

Go to the Kagi repository on GitHub and tap the Fork button at top-right. Then clone the source for your fork and add the upstream project as a Git remote:

git clone https://github.com/YOUR_USERNAME/kagi.git
cd kagi
git remote add upstream https://github.com/justinmayer/kagi.git

Install dependencies and set up the project:

poetry install
poetry shell
invoke setup

Your local environment should now be ready to go!

Detailed Set-up#

The first step is to install Poetry:

curl -sSL https://install.python-poetry.org/ | python -

Next, install Pre-commit. Here we will install Pipx and use it to install Pre-commit:

python3 -m pip install --user pipx
python3 -m pipx ensurepath
pipx install pre-commit

Tell Pre-commit where to store its Git hooks, such as ~/.local/share/git/templates. This only needs to be done once per workstation, so if you have already run these commands for another project, you can skip this step:

mkdir -p ~/.local/share/git/templates
git config --global init.templateDir ~/.local/share/git/templates
pre-commit init-templatedir ~/.local/share/git/templates

Go to the Kagi repository on GitHub and tap the Fork button at top-right. Then clone the source for your fork and add the upstream project as a Git remote:

git clone https://github.com/YOUR_USERNAME/kagi.git
cd kagi
git remote add upstream https://github.com/justinmayer/kagi.git

Install the Pre-commit hooks:

pre-commit install

(optional) Poetry will automatically create a virtual environment for you but will alternatively use an already-activated environment if you prefer to create and activate your virtual environments manually:

python3 -m venv ~/virtualenvs/kagi
source ~/virtualenvs/kagi/bin/activate

Install Kagi and its dependencies via Poetry:

poetry install

Your local environment should now be ready to go. Use the following command to run the test suite (you can omit poetry shell if you manually created and activated a virtual environment via the optional step above):

poetry shell
invoke tests

You can speed up test runs via the following command, replacing 4 with your workstation’s CPU core count:

PYTEST_ADDOPTS="-n 4" invoke tests