How To Contribute

The Cloud Native Glossary content is stored in this GitHub repo where you’ll find a list of issues, PRs, and discussions about the glossary.

There are four ways you can contribute:

1. Work on an existing issue
2. Propose new terms
3. Update existing ones
4. Help translate the glossary

Who can contribute?

The goal of this Glossary is to make the cloud native space — which is notorious for its complexity — simpler for people by making it easier to understand. To do that, we must focus on simplicity.

Explaining complex concepts in simple words is really hard. And while the digestible, user-friendly outcome may seem easy, achieving the desired simplicity is the result of hard work and collaboration between cloud native experts. In short, to contribute new terms, you need a deep understanding of the topic.

The localization effort is a bit different. With solid existing definitions in English, less experienced contributors can still provide good localized terms. This side of the project is better suited for beginners.

Join the Glossary community!

Consider joining our monthly Glossary Working Group meetings if you want to contribute regularly. You can find meeting details in the CNCF calendar. You can also connect with the maintainers and fellow contributors in our #glossary channel on the CNCF Slack — we’d love to meet you!

Work on an existing issue

Go to the Glossary GitHub repo issues. There you’ll see a list of all issues. You can filter by label (e.g. English language, help needed, good first issue). Note that you’ll need a GitHub account to do any of this.

Make sure the term you are interested in is not already assigned to someone. Here you can see that the first three terms are available while the next term has already been assigned.

Once you found a term you want to work on, say so in the issue. Click on it and add a comment.

Additionally, please also join the #glossary channel on the CNCF Slack and let the maintainers know that you’ve raised an issue for a new term (ideally, tag @Catherine Paganini, @jmo, @Seokho Son, @Jihoon Seo, and/or @iamnoah to be sure they don’t miss it). Note that you can only claim one term at a time. If you want to work on multiple terms, please finish one before claiming the next one.

Once they assign it to you, you can start working on it. For the next steps, please refer to the Submitting a new term (creating a PR) section.

Propose new terms

You can propose a new term for others to work on or create a new definition yourself. Either way, you’ll start by creating an issue. Please note that terms must meet the CNCF’s cloud native definition. The only exceptions are foundational terms needed to understand cloud native concepts.

Below is a step-by-step guide for those not yet familiar with GitHub. If you are a GitHub Pro, please do have a quick look to make sure you use our issue templates, appropriate naming conventions, claim a PR on Slack (otherwise we may miss it), and where to find the file template. And please make sure to read the Style Guide before getting started — thank you!

Creating an issue

Go to the Glossary GitHub repo issues and click on “New issue”.

You’ll see a variety of templates. To propose a new term in English, select “Request to add a new term (English)”.

Add the word you’re suggesting, answer the two questions below, check the checkboxes, and hit “Submit new issue”. If you’re just proposing a new term, you’re done! To work on it, follow the next steps.

Triaging your issue

Next, the maintainers will triage the issue. That means they will assess if the term should be part of the Glossary (note, not every term will be admitted. Terms should be established and widely-used cloud native terms).

Please let the maintainers know that you’ve submitted a term on Slack as they may otherwise miss it. Ideally, tag @Catherine Paganini, @jmo, @Seokho Son, @Jihoon Seo, and/or @iamnoah. If the term is approved and you want to work on it, they’ll assign it to you.

Note that you can only claim one term at a time. If you want to work on multiple terms, please finish one before claiming the next.

Submitting a new term (creating a PR)

Before getting started, please read the Style Guide — it will help minimize backs and forth. As stated in the style guide, we highly recommend starting with a Google or Word doc.

Once the term is ready to submit, go to content (under code)…

…then “en” (or the language you are submitting for)…

…and select _TEMPLATE.md

Copy the content…

…and go back to the “en” folder. Hit “Add file” and select “Create new file”.

Add the term name in the URL (no capitalization, no spaces, no parentheses, and use hyphens to separate words) and .md at the end (note: if your preview doesn’t work, you probably forgot to add .md at the end). Now paste the template content below. Copy and paste your definition into the file. To make reviews easier, please use semantic line breaks (e.g. one line per sentence). Note that GitHub uses markdown to format the text (e.g., hyperlink, bold, italic). Please refer to this markdown cheat sheet. To verify you’ve used markdown as intended, go to “Preview”.

Scroll down and name the new commit file when you are ready to submit. You are now about to commit the term to your own branch. Submitting a PR requires one more step. Hit “Commit new file” and…

…now you’re creating an PR:

You should now see your PR under “Pull requests”.

Update an existing term

To update an existing term, you can either suggest a change via an issue or go ahead and update the term directly by submitting a pull request (PR).

Request a change via an issue

If you want to flag a problem with a term but don’t know how or want to fix it yourself, click on “Report issue”.

This will directly open an issue. Please elaborate on which change is needed and why. Hit submit, and that’s it.

Update a term directly

To change a term directly, go to “Edit this page”.

This will open the term’s GitHub page. Make your changes and submit a PR. Please refer to “Submitting a new term” above for a detailed description (jump to the section that speaks about markdown).

Help translate the glossary

To help translate the glossary into your native language, please join the #glossary-localizations channel on the CNCF Slack and let us know. You can either join an existing team or create a new one (to see what it takes, check out or Localization Guide). Please also join our monthly Glossary Working Group meetings. You can find meeting details in the CNCF calendar. We look forward to meeting you there!