How To Contribute

Welcome

Welcome to the Cloud Native Glossary contributing guide, and thank you for your interest. There are a number of ways you can contribute to this project, which we’ll cover in detail here:

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

CNCF glossary overview

The goal of this glossary is to simplify the cloud native space — which is notorious for its complexity — and thus make it more accessible to people.

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

Who can contribute?

How you can participate in this project depends on your level of cloud native expertise. Simplifying complex concepts requires a deep knowledge of the topic. Therefore, to contribute new terms, you must be proficient in them. Contributors are typically engineers who have worked with these technologies for some time or academics focused on cloud native.

That know-how is required because explaining complex concepts in simple words is really hard. And while the digestible, user-friendly outcome may seem easy, achieving the desired simplicity results from hard work and collaboration between cloud native experts.

If you are not a cloud native expert yet but still want to contribute, we recommend teaming up with someone who is. Once the expert is confident that the term accurately describes the concept, you are ready for your first Glossary contribution.

The localization effort is where beginners proficient in another language can make valuable contributions to the Glossary. With solid existing definitions in English, less experienced contributors can localize terms to a target language. You can join an existing localization team or create a new one. Read this guide’s Help Localize the glossary section to learn how to get started.

Before you start

Before beginning your Glossary contributor journey, be sure to complete the following steps:

1. Create a GitHub account, if you don’t have one already.
2. Sign the Contributor License Agreement (CLA).
3. Verify your commit signature
4. Enable vigilant mode in your GitHub account to display the “Verified” status on your commits.

Best practices

To facilitate the reviewing process, please use semantic line breaks (e.g., one line per sentence). We recommend checking out this markdown cheat sheet to correctly format Markdown text in GitHub (e.g., hyperlink, bold, italic). And when naming .md files, please use lowercase letters and hyphens instead of spaces to separate words and avoid parenthesis.

Style guide

Read our Style Guide to understand our guidelines for formatting and writing documents and make the contribution process more efficient.

Join the Glossary community!

If you want to contribute regularly, consider joining our monthly Glossary Working Group meetings. You can find the 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 to find a list of available issues. You can use labels (e.g., English language, help needed, good first issue) to filter out issues.

Be sure the term you select hasn’t already been assigned to anybody. For example, here you can see that the first three terms are available while the fourth one has already been assigned.

Once you select a term to work on, comment on the issue.

Additionally, notify the maintainers on the #glossary channel of the CNCF Slack workspace and tag @iamnoah, @nate-double-u, @Seokho Son, @Jihoon Seo, and/or @castrojo to be sure they don’t miss it.

For the next steps, please refer to the Submitting a new term (creating a PR) section.

Note: you can start working on an issue after the maintainers assigned it to you. You can only claim one term at a time. Workig on multiple terms is sequential, you must complete a term before claiming the next one.

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. To be added to the glossary, every new term 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 people unfamiliar with GitHub. If you are a GitHub Pro, please do scan this guide to gather enough information about the following topics:

1. Locating templates for issues and new terms.
2. Claiming issues.
3. Solving spell check failures.

Creating an issue

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

Select “Request to add a new term (English)” from the list of templates.

Add the word you’re suggesting, answer the questions, check the boxes, and hit “Submit new issue”. If you’re just proposing a new term, you’re done! If you want to work on the definition, keep reading.

Triaging your issue

Next, the maintainers will triage the issue. That means they will assess if the term should be part of the Glossary. Not every term will be admitted. To be included in the Glossary, they should be established and widely-used cloud native concepts.

Please let the maintainers know that you’ve proposed a new term on Slack and tag @iamnoah, @nate-double-u, @Seokho Son, @Jihoon Seo, and/or @castrojo so that they don’t miss it. If you want to work on the definition, let the maintainers know and they’ll assign it to you.

Submitting a new term (creating a PR)

As stated in our 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” (for English) or the first two letters of the language you are contributing to…

…and select _TEMPLATE.md

Copy the content…

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

Add the name of the term in the URL as described in the Best practices section. Add the .md extension at the end of the name (without this extension you won’t be able to preview your file). Now paste the template content in the section below. Copy and paste the text of your definition into the file. To verify you’ve used Markdown as described in the Best practices section, click on “Preview”.

Scroll down and name the new commit file. Hit “Commit new file” when you are ready to submit and…

… you’re now ready to create a new PR:

Once you hit the “Create pull request” button your PR should be visible in the “Pull requests” tab.

Update an existing term

To update an existing term, you can either request changes by creating an issue or work on the changes yourself and submit a PR.

Request a change via an issue

If you want to flag a problem with a term, you can use the “Report issue” option of the CNCF Glossary webpage. Locate yourself in the CNCF page of the concept you’d like to flag and click on “Report issue”. This will automatically open an issue for you

Please describe your suggestions and why they are needed. Hit submit, and that’s it.

Update a term directly

To modify a term and submit your suggestions, click “Edit this page.”

This will open the term’s GitHub page. Make your changes and create a PR. Please refer to the Best practices section above and read our Style Guide to make sure you follow our guidelines.

Help localize the glossary

To help localize the glossary into a target language, please join the #glossary-localizations channel on the CNCF Slack workspace and send us a message. You can either join an existing team or create a new one (to see what it takes, read our Localization Guide). Please read the How to contribute guide of the target language to gather the specifics of that team’s contribution process.

Spell check

There are two main reasons why the spell check can fail:

• The PR contains misspellings.
• The PR contains words that are not registered in the word list.

To add new words to the list, follow these steps:

1. In your PR, locate the file “wordlist.txt”.
2. Click “Edit this file” and add the missing words in alphabetic order.
3. Add a commit message and select “Sign off and propose changes”.

Note: the spell check is case-insensitive.

We updated this guide based on templates from The Good Docs Project.