Contributing to codex¶

Last Updated: 2026-07-08
Audience: Contributors, Maintainers
Related: Code Style Guide, Testing Guide, Documentation Style Guide

Overview¶

Welcome! This guide helps you contribute to codex successfully.

Note

This repository is designed for and managed by AI Assistants and Agents. All processes are automated and autonomous. Guidelines below support this workflow.

Quick Start for Contributors¶

1. Set Up Your Environment¶

# Clone the repository
git clone https://github.com/Aries-Serpent/_codex_.git
cd _codex_

# Install dependencies
pip install -r requirements-dev.txt
pre-commit install --install-hooks

2. Configure Git Hooks¶

# Install pre-commit hooks
pre-commit migrate-config
pre-commit autoupdate
pre-commit install --hook-type pre-commit --hook-type pre-push --hook-type commit-msg

3. Make Your Changes¶

Create a new branch: git checkout -b feature/your-feature-name
Make your changes
Test locally: pytest tests/
Commit: git commit -m "feat: description"

4. Push and Create PR¶

# Normalize line endings
git add --renormalize .
git commit -m "chore: normalize line endings via .gitattributes"

# Push your branch
git push origin feature/your-feature-name

Making Changes¶

Code Standards¶

Follow the Code Style Guide for: - Code formatting and naming conventions - Comment guidelines - Import organization - Test requirements

Documentation Standards¶

All documentation must follow the Documentation Style Guide: - Single H1 title per file - Clear, active voice - Working code examples - Proper heading hierarchy - Relative internal links

Commit Message Format¶

Use conventional commits:

<type>(<scope>): <subject>

<body>

<footer>

Types: feat, fix, docs, style, refactor, perf, test, chore

Examples:

feat(api): add authentication endpoint
fix(cli): resolve import error on Windows
docs(readme): update installation instructions

Managing Line Endings¶

After .gitattributes updates, normalize once:

git add --renormalize .
git commit -m "chore: normalize line endings via .gitattributes"

Fast Path vs. Full Checks¶

Commit-Time Hooks (Fast)¶

Run locally before pushing:

pre-commit run

Full Checks (Before Merge)¶

Run when committing:

SKIP=semgrep git commit -m "feat: description"

Note

Semgrep runs automatically on pre-push and in CI. Use pre-commit run --all-files for manual full scans.

Using Operational Templates¶

Operational templates in docs/templates/ follow a role-gated execution model.

Task	Template	Purpose
Move Python files	Python File Relocation	Preserve backward compatibility
CLI changes	CLI Hardening	Target ≥85% coverage
Plan work	Intent Validation	Document assumptions & risks

Using a Template¶

Copy the template file
Replace all [PLACEHOLDER: ...] entries
Attach supporting assets (tests, notebooks)
Document execution in "Execution Notes"
Validate placeholders are resolved
Ensure references are accessible

Example:

[PLACEHOLDER: MIGRATION_INTENT_SUMMARY] 
→ "Relocate tokenizer helpers to `codex.text`"

[PLACEHOLDER: COMMAND_LIST]
→ "`codex-cli sync`, `codex-cli diff`"

[PLACEHOLDER: APPROVAL_DEADLINE]
→ "2025-11-07"

Troubleshooting¶

Missing Pre-Commit Hooks¶

Reinstall hooks:

pre-commit install --install-hooks \
  --hook-type pre-commit \
  --hook-type pre-push \
  --hook-type commit-msg

Hook Configuration¶

Check .pre-commit-config.yaml for available stages. Values match hook names (pre-commit, pre-push, etc).

Common Issues¶

Issue	Solution
Hooks won't install	Run: `pre-commit autoupdate`
Hook too slow	Use `SKIP=toolname git commit`
Line ending issues	Run: `git add --renormalize .`
Semgrep blocking	Run on pre-push only, not pre-commit

Code Review Expectations¶

What Reviewers Check¶

✅ Code follows style guide
✅ Tests cover new code
✅ Documentation is updated
✅ Examples are working
✅ No breaking changes (unless major version)
✅ Commit messages are clear
✅ Related issues are linked

How to Prepare¶

Test locally: pytest
Run linting: pre-commit run --all-files
Update docs if needed
Reference related issues/PRs
Keep commits logical (not squashed)

Asking for Help¶

How-to questions: GitHub Discussions
Bug reports: Issue Tracker
Design feedback: Open a draft PR for early feedback

Code of Conduct¶

Please review our Code of Conduct before contributing. We're committed to fostering an inclusive and respectful environment.

Thank you for contributing to codex! 🚀