Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
269 lines (193 loc) · 10.4 KB

CONTRIBUTING.md

File metadata and controls

269 lines (193 loc) · 10.4 KB

Contributing to the Agentic Chatbot Accelerator

Thank you for your interest in contributing to the Agentic Chatbot Accelerator! This document provides guidelines and instructions for contributing to this project.

Table of Contents

Code of Conduct

This project has adopted the Amazon Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opensource-codeofconduct@amazon.com with any additional questions or comments.

Reporting Bugs/Feature Requests

We welcome you to use the GitHub issue tracker to report bugs or suggest features.

When filing an issue, please check existing open, or recently closed, issues to make sure somebody else hasn't already reported the issue. Please try to include as much information as you can. Details like these are incredibly useful:

  • A reproducible test case or series of steps
  • The version of our code being used
  • Any modifications you've made relevant to the bug
  • Anything unusual about your environment or deployment

Contributing via Pull Requests

Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:

  1. You are working against the latest source on the main branch.
  2. You check existing open, and recently merged, pull requests to make sure someone else hasn't addressed the problem already.
  3. You open an issue to discuss any significant work - we would hate for your time to be wasted.

To send us a pull request, please:

  1. Fork the repository.
  2. Modify the source; please focus on the specific change you are contributing. If you also reformat all the code, it will be hard for us to focus on your change.
  3. Ensure local tests pass.
  4. Commit to your fork using clear commit messages.
  5. Send us a pull request, answering any default questions in the pull request interface.
  6. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.

GitHub provides additional document on forking a repository and creating a pull request.

Finding contributions to work on

Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any 'help wanted' issues is a great place to start.

Use of AI Coding Assistants

Use of AI coding assistants (Kiro, Cline, GitHub Copilot, etc.) is encouraged when contributing to this project. However, contributors must be able to explain every line of code that AI generated, without the assistance of AI. Take time to understand what the AI produces before accepting suggestions.

This guideline ensures:

  • Code quality and maintainability
  • Contributors can effectively review and debug their contributions
  • Knowledge transfer during code reviews

Project Principles

Contributions should align with the following principles:

  1. AWS-Native Architecture: The accelerator is built on AWS services (Bedrock AgentCore, AWS Strands, CDK). Contributions should leverage AWS services appropriately and follow AWS best practices.

  2. Modular & Optional Features: The architecture supports flexible deployments. For example, the Knowledge Base feature is optional and can be disabled. New features should consider whether they belong in the core or as optional modules.

  3. Documentation-Driven: This project emphasizes comprehensive documentation. Code contributions should be accompanied by appropriate documentation updates.

  4. Infrastructure as Code: All infrastructure is defined using AWS CDK with TypeScript. Configuration is managed through YAML files with sensible defaults.

  5. Security First: Security is paramount. All contributions must pass security scans and follow AWS security best practices.

Getting Started

For complete development environment setup, project structure, IDE configuration, and local development instructions, see the Development Guide.

In summary, you will need:

  • Node.js (version 20 recommended)
  • Docker or Finch (for container builds)
  • AWS CLI (configured with appropriate credentials)
  • Python 3.11+ (for Lambda development and linting)
  • Git

Key Documentation Files:

Development Workflow

Branching Strategy

  1. Create a branch from main for your work:

    git checkout -b <type>/<description>

    Use prefixes to indicate the type of change:

    • feature/ - New features
    • fix/ - Bug fixes
    • docs/ - Documentation updates
    • refactor/ - Code refactoring
    • test/ - Test additions or modifications

  2. Keep your branch up to date with main:

    git fetch origin
git rebase origin/main

Making Changes

  1. Keep changes focused on a single issue or feature
  2. Write/update tests as necessary
  3. Update documentation for any user-facing changes
  4. Follow existing patterns in the codebase

Code Quality and Testing

Pre-commit hooks automatically enforce code formatting and linting. Before opening a pull request, ensure all checks pass and run a security scan:

# Run all pre-commit hooks
make precommit-run

# Run security scan (required before opening a PR)
make run-ash

For detailed information on code quality tools, frontend testing, CDK synthesis, and local development, see the Development Guide — Code Quality section.

Contribution Types

Code Contributions

  • Infrastructure (CDK): Modifications to iac-cdk/lib/ directory constructs
  • Lambda Functions: Python handlers in src/*/functions/
  • Frontend (React): Components in lib/user-interface/react-app/src/
  • Agent Runtime: Docker container and Python code in src/agent-core/docker/

Documentation Contributions

  • Add or update documentation in docs/src/
  • Include code snippets where helpful
  • Keep documentation in sync with code changes

Tool Extensions

Follow the Expanding AI Tools guide to add:

  • Custom function-based tools
  • Object-based tools with configuration
  • MCP server integrations

Bug Fixes

  • Reference the related issue in your PR
  • Include steps to reproduce (if not in the issue)
  • Add regression tests where applicable

Coding Standards

Python

  • Follow PEP 8 style guidelines
  • Use type hints for function signatures
  • Format with Black (line length: 120)
  • Lint with Ruff
  • Use AWS Lambda Powertools for logging and tracing

TypeScript/JavaScript

  • Follow the ESLint configuration in the project
  • Format with Prettier
  • Use TypeScript for new code where possible
  • Follow CDK best practices for infrastructure code

React

  • Use functional components with hooks
  • Follow Cloudscape Design System patterns
  • Keep components focused and reusable

General

  • Commit Messages: Write clear, descriptive messages
    • Use imperative mood ("Add feature" not "Added feature")
    • Reference issues where applicable
  • Naming: Use descriptive names for variables, functions, and files
  • Comments: Explain "why" not "what" in comments

Documentation

  • Update README.md when adding significant features
  • Add detailed documentation to docs/src/ for:
    • New features or capabilities
    • Architecture changes
    • Configuration options
  • Include diagrams for complex architectures (store in docs/diagrams/)

Reporting Bugs and Feature Requests

We welcome bug reports and feature requests through GitHub Issues.

When reporting a bug, please include:

  • Description of the issue
  • Steps to reproduce
  • Expected vs actual behavior
  • Environment details (OS, Node.js version, etc.)
  • Relevant logs or screenshots

When requesting a feature, please include:

  • Use case description
  • Proposed solution (if any)
  • Alternatives considered

Security

Security is critical for this project. Before submitting a pull request:

  1. Run ASH (Automated Security Helper):

    make run-ash

  2. Review Security-Sensitive Areas:

    • IAM policies and permissions: follow the principle of least privilege by granting only the minimum permissions required
    • Cognito configuration
    • GraphQL resolvers and authorization
    • Lambda function permissions
    • S3 bucket policies

  3. Report Security Vulnerabilities:

Thank you for contributing to the Agentic Chatbot Accelerator!