• Contributing to SREGym
  • Table of Contents
  • Rules and Guidelines on AI Usage
  • Getting Started
  • Development Setup
    • Prerequisites
    • Installation
  • How to Contribute
    • Reporting Bugs
    • Suggesting Features
    • Code Contributions
  • Development Guidelines
    • Code Style
      • Python Code Style
      • Running Code Formatters
      • Code Quality Best Practices
    • Commit Messages
  • Adding New Components
    • Adding New Applications
    • Adding New Problems
    • Adding New Oracles
  • Pull Request Process
    • PR Checklist
  • Community
    • Getting Help
    • Staying Updated
  • License

LLMs and coding agents are significant productivity boost if used correctly, but a big headache if not. In SREGym, we welcome contributors who leverage LLMs and coding agents in building new features, but blatant abuse of LLMs and coding agents in generating code and communicating on GitHub is not welcomed.

More specifically, it is ok to use AI to:

• generate code for features or bug fixes, but any AI generated code MUST be checked and tested by a human

It is NOT ok to use AI to:

• generate complete responses to other humans, e.g., in PRs, comments, etc, with no human intervention
• "one-shot" an open issue by using coding agents to generate commits, PR description, and PR comments, with no human intervention
• Other use cases where blatant abuse is obvious.

For PRs and communications that violate the rules above, if its owner (i.e., the GitHub user that opens them) is a first-time violator, they receive a warning on the behavior. If they violate the rules again, they are unfortunately banned from contributing to SREGym.

Before contributing, please:

1. Read the README.md to understand the project
2. Review the Problem List
3. Join our Slack community
4. Check existing issues to avoid duplicates

• Python >= 3.12
• Helm
• brew
• kubectl
• uv (recommended for dependency management)

1. Fork the repository on GitHub

2. Clone your fork with submodules:

   git clone --recurse-submodules https://github.com/YOUR_USERNAME/SREGym
   cd SREGym

3. Install dependencies:

   uv sync

4. Install git hooks via prek:

   uv run prek install

5. Set up your cluster (see README.md for options)

When reporting bugs, please include:

• Clear description of the issue
• Steps to reproduce the problem
• Expected behavior vs actual behavior
• Environment details (OS, Python version, cluster type)
• Relevant logs or error messages
• Problem ID if the issue is specific to a particular problem

Use the GitHub issue tracker with the "bug" label.

We welcome feature suggestions! Please:

• Check if the feature has already been requested
• Describe the use case and expected behavior
• Explain why this feature would be valuable
• Consider whether it aligns with the project's goals

Use the GitHub issue tracker with the "enhancement" label.

We welcome contributions including:

• Bug fixes
• New applications
• New problems
• New oracles or evaluation metrics
• MCP server enhancements
• Documentation improvements
• Test coverage improvements
• Performance optimizations

SREGym follows code style guidelines enforced by prek (git hooks):

• Formatter: Black with 120 character line length
• Import sorting: isort with Black profile
• Target Python version: 3.12

Configuration is in pyproject.toml:

[tool.black]
line-length = 120
target-version = ["py312"]

[tool.isort]
profile = "black"
line_length = 120

Prek hooks will automatically run on commit. To manually format:

# Format all Python files
uv run black .

# Sort imports
uv run isort .

# Run all hooks manually
uv run prek run --all-files

• Write clear, self-documenting code
• Add docstrings to classes and functions
• Keep functions focused and modular
• Follow existing patterns in the codebase
• Handle errors gracefully with appropriate logging
• Avoid hardcoded values; use configuration where appropriate

Write clear, descriptive commit messages:

• First line should be 50 characters or less
• Provide additional context in the body if needed
• Reference issue numbers when applicable

Example:

Add support for custom fault injection parameters

- Extend VirtualizationFaultInjector to accept custom config
- Add validation for parameter types
- Update documentation with examples

Fixes #123

To add a new application to SREGym:

1. Create application metadata in SREGym/service/metadata/<app-name>.json:

   {
     "name": "My Application",
     "description": "Description of the application",
     "namespace": "my-app",
     "Helm Config": {
       "release_name": "my-app-release",
       "chart_path": "path/to/helm/chart",
       "namespace": "my-app"
     }
   }

2. Create application class in sregym/service/apps/<app-name>.py:

   from sregym.service.apps.base import Application
   
   class MyApp(Application):
       def __init__(self):
           super().__init__("sregym/service/metadata/<app-name>.json")

3. Update documentation if needed

To add a new problem:

1. Create problem file in sregym/conductor/problems/<problem-name>.py:

   from sregym.service.apps.myapp import MyApp
   from sregym.conductor.oracles.detection import DetectionOracle
   from sregym.conductor.oracles.diagnosis import DiagnosisOracle
   from sregym.conductor.oracles.mitigation import MitigationOracle
   from sregym.conductor.problems.base import Problem
   from sregym.utils.decorators import mark_fault_injected
   
   class MyProblem(Problem):
       def __init__(self):
           self.app = MyApp()
           self.faulty_service = ["service-name"]
   
           # Attach evaluation oracles
           self.diagnosis_oracle = DiagnosisOracle(
               problem=self,
               expected=self.faulty_service
           )
           self.mitigation_oracle = MitigationOracle(problem=self)
   
       @mark_fault_injected
       def inject_fault(self):
           # Fault injection logic
           pass
   
       @mark_fault_injected
       def recover_fault(self):
           # Fault recovery logic
           pass

2. Register your problem in sregym/conductor/problems/registry.py

3. (Optional) Configure tasks in sregym/conductor/tasklist.yml:

   my-problem-id:
     - detection
     - diagnosis
     - mitigation

4. Document the problem with clear description and expected behavior

5. Validate the problem in your PR. Add a line to your pull request description in this form (anywhere in the body):

   /validate-problem <problem_id>
   

   where <problem_id> is your problem's registry key. This opts the PR into the Problem Validation workflow, which deploys the app, injects the fault, and verifies that the mitigation oracle fails while the fault is live and passes again after recovery. The check must be green before merge. You can add the line after opening the PR, or post it as a PR comment — handy when a reviewer wants to run validation that the contributor forgot. Comment triggers require write access to the repo.

   Any PR that changes files under sregym/conductor/problems/ must include a /validate-problem line; a gate check fails the PR otherwise. If validation genuinely does not apply — a refactor, a registry.py/base.py change, or a problem that cannot run on the CI kind cluster — opt out explicitly with:

   /validate-problem skip
   

   To run the validation locally:

   uv run python tests/integration/validate_problem.py --problem <problem_id>

   Automated validation does not replace human review.

6. Screen validated problems for difficulty (core team). Run Problem Difficulty Evaluation from the Actions tab, or have an owner, member, or collaborator post this PR comment:

   /evaluate-problem <problem_id> [3|5] [glm-5.3-flash]
   

   The optional values default to five attempts and glm-5.3-flash. The workflow runs the Codex harness against the Z.ai Coding Plan and publishes diagnosis, mitigation, and overall pass rates in the run summary and PR conversation. A problem is marked saturated only when every requested attempt completes and passes.

Custom oracles allow for specialized evaluation:

1. Create your oracle in SREGym/conductor/oracles/<oracle-name>.py
2. Inherit from appropriate base oracle class
3. Implement evaluation logic
4. Document the oracle's purpose and usage

1. Create a feature branch from main:

   git checkout -b feature/your-feature-name

2. Make your changes following the development guidelines

3. Commit your changes with clear commit messages

4. Push to your fork:

   git push origin feature/your-feature-name

5. Create a Pull Request on GitHub:

   • Provide a clear title and description
   • Reference any related issues
   • Explain what changes you made and why
   • Describe how you tested the changes
   • Include screenshots or examples if applicable

6. Respond to feedback:

   • Address review comments promptly
   • Update your PR as needed
   • Keep discussions constructive and professional

7. Wait for approval:

   • At least one maintainer approval is required
   • All CI checks must pass
   • No merge conflicts with main branch

Before submitting, ensure:

• Code follows the project's style guidelines
• Documentation updated if needed
• Prek hooks pass
• No unnecessary files or changes included
• Commit messages are clear and descriptive
• PR description explains the changes

• Slack: Join our Slack community for discussions
• Issues: Use GitHub issues for bug reports and feature requests
• Documentation: Check the README and existing documentation

• Watch the repository for updates
• Follow discussions on Slack
• Review the problem list for new additions

By contributing to SREGym, you agree that your contributions will be licensed under the MIT License.