Contributing to the Kong docs
Hello, and welcome! Thanks for thinking about contributing to the Kong documentation.
This section of the docs is here to help you help us, so read on to learn how to ask questions and help effectively.
We respect your time, and the more you follow our guidelines the easier it is for us (docs maintainers) to respond
promptly and help you get your pull requests merged.
What we’re looking for
We welcome fixes to unclear prose, fixes to typos in docs for recent versions, docs for new features you’ve contributed to
the code, and more.
If you’ve written a Kong plugin and need to contribute documentation for it, see the docs about plugin docs.
There are special guidelines for these docs.
We ask that you explore the existing documentation before you start a big docs contribution. Some types of docs
don’t belong on the site: end-to-end guides, tutorials, anything better suited to a blog post. If you’re interested in
this kind of content, though, join the community on Kong’s forum, on
Gitter, or on IRC at #kong.
The community is the place to ask support questions, too. We can’t help you with the product in this repository.
For bugs against Kong Gateway functionality, see the code repository.
How to contribute
We adhere to our own code of conduct and we expect the same of our contributors.
If you find a problem in the docs, you can file an issue against the docs
or you can submit a pull request with a fix. If you submit a PR without an issue, make sure to fill out the PR template to explain why
you’re making the change. We require the information we ask for in the template, and it’s especially important if we don’t have
an issue to refer to.
The Kong docs team assigns someone to review PRs every day, so you can expect acknowledgment of your contribution and at least preliminary
feedback within about a day of your initial PR. We ask that you respond to feedback within a week if we ask for changes; otherwise, we’ll close
your issue or PR, although you can always reopen it to finish your work.
If you fix a typo (and we welcome typo fixes!), be sure to check for it everywhere, not just in the one instance you might
have found. Currently docs for each version live in separate directories, not branches, and much content doesn’t change from
version to version. Chances are good that a typo on a page in one version appears on the same page in other versions too.
Before you change anything except fixes for typos or well-known grammar rules, explore these resources:
- Our style guide. Provides a minimal set of style guidelines we ask you to adhere to.
- Our set of markdown rules for making your content work with our Jekyll implementation. Specifies how you must
work with certain kinds of content – includes, variables, new pages.
- Our list of Kong-specific terms. Includes product names and other terms the Kong docs use in specific ways.
Updates to the Kong docs
main branch are automatically published with our Netlify integration. We also work with Netlify preview deploys, so when you create a pull request on GitHub, Netlify automatically provides a preview build that includes your changes.
If you are making substantial changes, we ask that you build locally before you create your PR. This lets you run tests locally, and helps you fix any build errors before working with Netlify.
See the README for instructions to set up and build locally.
Make sure to fork the repository and create an appropriately named branch before you start working on any substantial changes.
If you’re new to Git and GitHub, we suggest you take some time with some of the great resources for learning these tools. Their basic purpose
is version control, but they were made to support open source projects, so their design and implemenation might be different from what
you’re used to. Resources we’ve found helpful, with thanks to the Write the Docs newsletter:
Or consider a GUI client instead of the command line, such as GitHub Desktop, TortoiseGit (Windows), Tower, Sourcetree, or GitKraken.
If you’re making small spelling or grammar changes, you’re welcome to skip the whole learn-Git-fork-branch-work-locally flow and make your changes directly in the GitHub web UI. The UI takes care of forking/branching automatically, so you don’t need to worry about it. Because we work with deploy previews in Netlify, this approach means you also don’t need to worry about building locally before you submit your PR.
If your contribution to this repository was accepted and fixes a bug, adds
functionality, or makes it significantly easier to use or understand Kong,
congratulations! You are eligible to receive the very special Contributor
T-shirt! Fill out the Contributors Submissions form and we’ll
get it to you!
Thank you for contributing!