Contributing

We welcome all kinds of contributions to Kepler from the community!

For an in-depth guide on how to get started, checkout the Contributing Guide here.

Kepler Adopters

You and your organization are using Kepler? That's awesome. We would love to hear from you! 💚

The yaml file in here contains a list of all Kepler adopters. If you want to add your organization to Kepler's list, just add an entry there and once merged you will be found under Kepler Adopters.

Rendering Adopters

As part of adding an organization to the Kepler Adopters page, when data/adopters.yaml is updated, gomplate must be installed. The Kepler website uses it to render the Kepler Adopters page properly.

Note

These steps are only needed if data/adopters.yaml is updated as part of adding an organization to the Kepler Adopters page.

Install pkgx
```
curl -Ssf https://pkgx.sh | sh
```
Install gomplate
```
pkgx +gomplate.ca^v3.11.7
```
Enter the output from the previous command to update PATH. Example:
```
PATH="$HOME/.pkgx/gomplate.ca/v3.11.7/bin${PATH:+:$PATH}"
```

Update adopters page using data from data/adopters.yaml

gomplate -d adopters=./data/adopters.yaml -f templates/adopters.md -o docs/project/adopters.md

Adding Your Organization

To do so follow these steps:

Fork the kepler-doc repository.
Clone it locally with git clone https://github.com/<YOUR-GH-USERNAME>/kepler-doc.git.
(Optional) Add the logo of your organization to docs/fig/logos. Good practice is for the logo to be called e.g. MY-ORG.png (=> docs/fig/logos/default.svg is the Kepler logo, it is used when no organization logo is provided.)
Add an entry to the YAML file with the name of your organization, url that links to its website, and the path to the logo. Example:
```
    - name: Kepler
      url: https://sustainable-computing.io/
      logo: logos/kepler.svg
```
Verify the Kepler Adopters page updated properly by running the following commands (see Install MkDocs for more details on how to preview the documentation from a build):
```
mkdocs build
mkdocs server
```
When happy with the changes, add the changed files using git add -A and then commit using git commit -s -m "Add MY-ORG to adopters" (commit sign-off is required, see DCO of the kepler project).
Push the commit with git push origin main.
Open a Pull Request to kepler-doc

Documentation Translation

Kepler welcomes contributions to translate our documentation into different languages to make it accessible to a global community of developers and operators!

Translation Process Overview

Our documentation follows internationalization (i18n) conventions using language suffixes:

English (Original): docs/path/to/file.md
Chinese: docs/path/to/file.zh.md
Other languages: docs/path/to/file.[LANG_CODE].md

Getting Started with Translations

1. Use the AI Translation Agent

For efficient and accurate technical translations, we recommend using our specialized AI translation prompt. This ensures:

✅ Technical accuracy - Preserves API names, commands, and code blocks
✅ Consistent terminology - Maintains technical terms across documents
✅ Proper formatting - Keeps markdown structure and syntax highlighting
✅ Quality validation - Generates quality check reports

📋 Translation Agent Prompt: TRANSLATOR.md

2. Quality Assurance Process

Every translation should include a quality check report to validate accuracy:

Generated Files for Each Translation:

docs/path/to/file.md          # Original English
docs/path/to/file.zh.md       # Chinese translation
docs/path/to/file.zh-qc.md    # Quality check report

The quality check report (.zh-qc.md) contains:

Comparison between original and reverse-translated content
Technical accuracy assessment
Formatting and structure validation
Recommendation for approval/revision

3. Translation Guidelines

✅ DO:

Preserve all technical identifiers (API names, commands, URLs)
Maintain markdown formatting and code block syntax
Keep consistent terminology within and across documents
Include the statutory warning about AI translation
Generate quality check reports for validation

❌ DON'T:

Translate technical commands, API endpoints, or code snippets
Modify file paths, repository URLs, or external links
Change the document structure or heading hierarchy
Skip quality validation steps

4. Statutory Warning Requirement

All translated documents must include this warning at the beginning:

!!! warning "机器翻译声明"
    本文档由 AI 语言模型 (Claude) 从英文自动翻译而成。如发现翻译错误或不准确之处，请在 [Kepler 文档项目](https://github.com/sustainable-computing-io/kepler-doc/issues) 中提交 issue 报告问题。

Contributing Your Translation

Step-by-Step Process:

Fork and Clone

git clone https://github.com/<YOUR-USERNAME>/kepler-doc.git
cd kepler-doc

Create Translation Branch

git checkout -b translate-[language]-[document-name]

Generate Translation
Use the AI translation agent
Follow the quality assurance process
Ensure all files are generated (.zh.md + .zh-qc.md)
Review and Test

mkdocs build
mkdocs serve

Preview your translations at http://localhost:8000

Commit Changes

git add docs/path/to/file.zh.md docs/path/to/file.zh-qc.md
git commit -s -m "Add Chinese translation for [document-name]

- Translate docs/path/to/file.md to Chinese
- Include quality check report for validation
- Follow i18n conventions with .zh.md suffix"

Open Pull Request
Include both translation and quality check files
Reference the quality check report findings in PR description
Mention any technical terms that required special handling

Translation Priority

High Priority Documents:

Installation guides (docs/kepler/installation/)
Usage documentation (docs/kepler/usage/)
Configuration guides (docs/kepler-operator/)

Medium Priority:

Developer documentation (docs/kepler/developer/)
Architecture and design docs (docs/archive/design/)

Language Support

Currently supported languages:

中文 (Chinese): .zh.md suffix

Want to add a new language?

Check mkdocs.yml i18n configuration
Open an issue to discuss language code and navigation structure
Follow the same process with appropriate language suffix

Translation Maintenance

Translations should be updated when:

Original English documents are significantly changed
Technical APIs or commands are modified
New features are added that affect documented procedures

Pro tip: Watch the repository for changes to English files that have translations to stay up-to-date!

Getting Help

Questions about translation process: GitHub Discussions
Report translation errors: GitHub Issues
Technical content clarification: Main Kepler Repository

Thank you for helping make Kepler documentation accessible worldwide! 🌍