cognitive-archaelogy-tribunal

Contributing to Cognitive Archaeology Tribunal

Thank you for your interest in contributing! This document provides guidelines for contributing code, documentation, datasets, and ideas.

Table of Contents

Code of Conduct

This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.

How Can I Contribute?

1. Code Contributions

2. Dataset Contributions

3. Documentation Contributions

4. Community Contributions

Development Setup

Prerequisites

# Python 3.8+
python --version

# Git
git --version

# pip
pip --version

Clone and Setup

# Fork the repository on GitHub
# Then clone your fork
git clone https://github.com/YOUR_USERNAME/cognitive-archaelogy-tribunal
cd cognitive-archaelogy-tribunal

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Install development dependencies
pip install -r requirements-dev.txt  # (if exists)

# Install pre-commit hooks (if configured)
pre-commit install

Run Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=cognitive_tribunal

# Run specific test file
pytest tests/test_ai_context_aggregator.py

Code Contributions

Workflow

  1. Create an Issue (for significant changes)
    • Describe what you want to change
    • Discuss approach with maintainers
    • Get feedback before coding
  2. Fork & Branch 
    # Create a feature branch
git checkout -b feature/your-feature-name

# Or a bugfix branch
git checkout -b fix/issue-123-description
  3. Write Code
    • Follow style guides (see below)
    • Add/update tests
    • Update documentation
    • Add docstrings
  4. Test 
    # Run tests
pytest

# Check code style
black cognitive_tribunal/
flake8 cognitive_tribunal/

# Type checking (if using mypy)
mypy cognitive_tribunal/
  5. Commit 
    # Write clear commit messages
git add .
git commit -m "Add feature: brief description

Longer explanation if needed.
Fixes #123"
  6. Push & PR 
    # Push to your fork
git push origin feature/your-feature-name

# Create Pull Request on GitHub
# Fill out the PR template

Pull Request Requirements

Pull Request Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] CHANGELOG.md updated
- [ ] Code follows style guide

## Related Issues
Fixes #123
Related to #456

Dataset Contributions

Publishing a Dataset

  1. Prepare Data 
    # Add data to ingestion chambers
cp your-data.json ingestion/ai-exports/

# Run processing
./scripts/ingest_all.sh

# Check for sensitive info
./scripts/sanitize_for_public.sh
  2. Add Metadata
    • Create DATASET.md with description
    • Add LICENSE-DATASET
    • Create CONSENT.md
    • Include citation information
  3. Submit
    • Fork repository
    • Add your dataset
    • Create pull request
    • Maintainers will review

Dataset Requirements

Documentation Contributions

Types of Documentation

Documentation Style

Building Docs Locally

# If using Sphinx or similar
cd docs
make html

# View in browser
open _build/html/index.html

Reporting Bugs

Before Submitting

Bug Report Template

## Bug Description
Clear description of the bug

## Steps to Reproduce
1. Step one
2. Step two
3. ...

## Expected Behavior
What should happen

## Actual Behavior
What actually happens

## Environment
- OS: [e.g., macOS 14.0]
- Python: [e.g., 3.11.2]
- Tool Version: [e.g., 0.2.0]

## Additional Context
Logs, screenshots, etc.

Suggesting Enhancements

Enhancement Template

## Feature Description
Brief description

## Use Case
Why is this needed?

## Proposed Solution
How should it work?

## Alternatives Considered
Other approaches

## Additional Context
Mockups, examples, etc.

Style Guides

Python Code Style

Formatter: Black (line length 100)

black --line-length 100 cognitive_tribunal/

Linter: flake8

flake8 cognitive_tribunal/

Key Points:

Example:

def analyze_conversations(
    export_path: str,
    filters: Optional[Dict[str, Any]] = None
) -> Dict[str, Any]:
    """
    Analyze AI conversation exports.

    Args:
        export_path: Path to conversation export file
        filters: Optional filters to apply

    Returns:
        Analysis results with stats and insights

    Raises:
        FileNotFoundError: If export_path doesn't exist
        ValueError: If export format is invalid
    """
    # Implementation
    pass

Bash Script Style

Linter: shellcheck

shellcheck scripts/*.sh

Key Points:

Markdown Style

Linter: markdownlint

Key Points:

Commit Message Style

Format:

type: brief description (50 chars max)

Longer explanation if needed (72 chars max per line).
Can include multiple paragraphs.

Fixes #123
Related to #456

Types:

Examples:

feat: add browser tab analyzer module

Implements full BrowserTabAnalyzer class with tab group
analysis, temporal clustering, and domain categorization.

Fixes #42

fix: handle empty conversation files

Previously crashed on empty JSON files. Now returns
helpful error message.

Fixes #51

Review Process

What Happens After PR?

  1. Automated Checks (if CI/CD configured)
    • Tests run
    • Linting checks
    • Coverage reports
  2. Maintainer Review
    • Code quality
    • Test coverage
    • Documentation
    • Design decisions
  3. Feedback
    • Requested changes
    • Questions
    • Suggestions
  4. Approval & Merge
    • Once approved, will be merged
    • May be squashed into single commit

Review Timeline

Getting Help

Recognition

Contributors will be:

License

By contributing, you agree that your contributions will be licensed under the project’s existing licenses:

Thank You!

Your contributions make this project better for everyone. We appreciate your time and effort! 🙏

Document ID: CAT-CONTRIB-001 Status: Active Version: 1.0.0 Last Updated: 2025-11-19

See also: Code of Conduct Governance Roadmap
This site is open source. Improve this page.