From c2934abc45a8dc041a34ebdec66a31df9a7146ac Mon Sep 17 00:00:00 2001 From: Adam Weeks Date: Wed, 25 Feb 2026 10:35:44 -0500 Subject: [PATCH] feat: add contributing guidelines and agent documentation --- .github/ISSUE_TEMPLATE/bug_report.md | 36 +++++++++++ .github/ISSUE_TEMPLATE/config.yml | 5 ++ .github/ISSUE_TEMPLATE/feature_request.md | 27 ++++++++ .github/pull_request_template.md | 14 +++++ .github/workflows/prettier.yml | 2 + AGENTS.md | 54 ++++++++++++++++ CONTRIBUTING.md | 75 +++++++++++++++++++++++ 7 files changed, 213 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/pull_request_template.md create mode 100644 AGENTS.md create mode 100644 CONTRIBUTING.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..ba2d905 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,36 @@ +--- +name: Bug Report +about: Report a bug or unexpected behavior +title: '[Bug] ' +labels: bug +assignees: '' +--- + +## Description + +A clear and concise description of what the bug is. + +## Steps to Reproduce + +1. Go to '...' +2. Run '...' +3. See error + +## Expected Behavior + +What you expected to happen. + +## Actual Behavior + +What actually happened. + +## Environment + +- OS: [e.g., macOS 14, Windows 11] +- Node.js version: [e.g., 20.x] +- Python version (if applicable): [e.g., 3.11] +- Other relevant details: + +## Additional Context + +Add any other context, screenshots, or error messages about the problem here. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..e26fe17 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: true +contact_links: + - name: Webex Developer Documentation + url: https://developer.webex.com/ + about: Webex API and developer resources diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..2b1d12c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,27 @@ +--- +name: Feature Request +about: Suggest an idea or improvement for the template +title: '[Feature] ' +labels: enhancement +assignees: '' +--- + +## Description + +A clear and concise description of the feature or improvement you're proposing. + +## Use Case + +Describe the problem or use case this would address. Why would this be useful for contributors or projects using this template? + +## Proposed Solution + +Describe your proposed solution. What would be added or changed? + +## Alternatives Considered + +Describe any alternative solutions or workarounds you've considered. + +## Additional Context + +Add any other context, examples, or screenshots about the feature request here. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..7428263 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,14 @@ +## Description + +Brief description of the changes in this pull request. + +## Related Issue + +Fixes # (link to issue if applicable) + +## Checklist + +- [ ] Code compiles successfully +- [ ] Lint and format checks pass (`npx prettier . --check` and `ruff check .`) +- [ ] README updated if needed +- [ ] Changes tested locally diff --git a/.github/workflows/prettier.yml b/.github/workflows/prettier.yml index 7f54ebd..b79852d 100644 --- a/.github/workflows/prettier.yml +++ b/.github/workflows/prettier.yml @@ -17,6 +17,8 @@ jobs: - name: Install dependencies run: npm ci + env: + HUSKY: 0 - name: Check formatting run: npx prettier --check . diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..e43f1f2 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,54 @@ +# AGENTS.md + +Project context for AI coding agents (Cursor, GitHub Copilot, etc.) working on the Webex Samples Template. + +## Project Overview + +This is the **Webex Samples Template** repository—a standardized framework for creating code contributions to the Webex Samples organization. Projects created from this template are intended to be **open sourced and used by customers and partners**. The template provides a consistent structure, linting tools, and GitHub Actions for all new sample repositories. + +## Tech Stack + +- **Node.js**: Prettier, ESLint, Husky, lint-staged +- **Python**: Ruff (linter) + +## Format and Lint Commands + +### Prettier (JavaScript, JSON, Markdown, YAML) + +```bash +npx prettier . --check # Check formatting +npx prettier . --write # Apply formatting +npm run format # Same as --write +``` + +### Ruff (Python) + +```bash +ruff check . # Check for issues +ruff check --fix . # Auto-fix issues +``` + +## Pre-Commit Hooks + +Husky and lint-staged run automatically before each commit when enabled. To enable, uncomment the lines in [.husky/pre-commit](.husky/pre-commit): + +```bash +npx lint-staged +ruff check --fix . +``` + +## Dev Environment Tips + +- Use `npm run format` for Prettier formatting +- Use a Python virtual environment when running Ruff +- Run `npm ci` to install dependencies (use `npm ci` in CI, not `npm install`) + +## Quality Rules + +**Code must compile and pass all linters before committing.** Run Prettier and Ruff (or enable pre-commit hooks) to ensure checks pass locally before pushing. All GitHub Actions workflows must pass before a pull request can be merged. + +## Pull Request Instructions + +- All workflows (Prettier, Ruff) must pass before merging +- Contact Adam Weeks (adweeks) or Ashton Jordan (ashjorda) to have a new repo added to the Webex Samples organization +- New repos are private by default; contact Adam or Ashton for review to make the repo public diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..21ea6c9 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,75 @@ +# Contributing to Webex Samples Template + +Thank you for your interest in contributing to the Webex Samples Template! We appreciate your help in maintaining and improving this framework for the Webex Samples organization. + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [How to Contribute](#how-to-contribute) +- [Development Setup](#development-setup) +- [Pull Request Process](#pull-request-process) +- [Style Guide](#style-guide) +- [Getting Help](#getting-help) + +## Code of Conduct + +This project follows the Webex Samples organization standards. Please be respectful and constructive in all interactions. + +## How to Contribute + +We welcome several types of contributions: + +- **Bug reports**: Found something broken? Open an issue using the bug report template +- **Feature requests**: Have an idea to improve the template? Use the feature request template +- **Documentation**: Improvements to README, this guide, or other docs +- **Code**: Fixes, enhancements, or new features via pull requests + +## Development Setup + +1. **Clone the repository**: + + ```bash + git clone + cd Webex-Samples-Template + ``` + +2. **Install dependencies**: + + ```bash + npm install + ``` + +3. **Install Ruff** (for Python linting): + + ```bash + pip install ruff + ``` + +4. **Enable pre-commit hooks** (optional but recommended): Uncomment the lines in [.husky/pre-commit](.husky/pre-commit) to run Prettier and Ruff automatically before each commit. + +## Pull Request Process + +1. **Create a branch** from `main` for your changes +2. **Ensure code compiles and passes all linters** before committing. Run: + - `npx prettier . --check` and `npx prettier . --write` if needed + - `ruff check .` and `ruff check --fix .` for Python files +3. **Commit your changes** with clear, descriptive messages +4. **Open a pull request** using the PR template +5. **Address review feedback** promptly +6. **Wait for CI**—all GitHub Actions (Prettier, Ruff) must pass before merging + +**Important**: Code must compile and pass all linters before committing. Do not push code that fails the Prettier or Ruff checks. + +## Style Guide + +- **JavaScript, JSON, Markdown, YAML**: Use [Prettier](https://prettier.io) for formatting +- **Python**: Use [Ruff](https://docs.astral.sh/ruff/linter/) for linting + +See the [README](README.md) for detailed instructions on running Prettier and Ruff locally. + +## Getting Help + +- **Adam Weeks** (adweeks) +- **Ashton Jordan** (ashjorda) + +Reach out to Adam or Ashton for questions about the template, adding repos to the organization, or making repos public.