From a2f53855ff8509fc1cd6857f3ef6bc2d28ca4631 Mon Sep 17 00:00:00 2001 From: spbkgw-beep Date: Thu, 26 Feb 2026 17:34:41 -0800 Subject: [PATCH 1/2] chore: add community health docs and contribution templates --- .github/ISSUE_TEMPLATE/bug_report.yml | 76 +++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 8 ++ .github/ISSUE_TEMPLATE/feature_request.yml | 46 ++++++++ .github/pull_request_template.md | 22 ++++ CODE_OF_CONDUCT.md | 125 +++++++++++++++++++++ CONTRIBUTING.md | 65 +++++++++++ README.md | 11 ++ SECURITY.md | 33 ++++++ SUPPORT.md | 23 ++++ pyproject.toml | 3 + 10 files changed, 412 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/pull_request_template.md create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md create mode 100644 SUPPORT.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..57a9604 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,76 @@ +name: Bug report +description: Report incorrect behavior or a regression +title: "[Bug]: " +labels: ["bug"] +body: + - type: checkboxes + id: precheck + attributes: + label: Pre-flight checklist + options: + - label: I searched existing issues and did not find a duplicate. + required: true + - label: I am using the latest released version of agent-estimate. + required: true + + - type: textarea + id: summary + attributes: + label: What happened? + description: Describe the bug and impact. + placeholder: A clear and concise description of the problem. + validations: + required: true + + - type: textarea + id: steps + attributes: + label: Steps to reproduce + description: Provide a minimal reproducible example. + placeholder: | + 1. Run command... + 2. With input... + 3. Observe output... + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected behavior + placeholder: What should have happened? + validations: + required: true + + - type: textarea + id: actual + attributes: + label: Actual behavior / output + render: shell + placeholder: Paste relevant output or stack trace. + validations: + required: true + + - type: input + id: version + attributes: + label: agent-estimate version + placeholder: "0.4.0" + validations: + required: true + + - type: input + id: python + attributes: + label: Python version + placeholder: "3.12.2" + validations: + required: true + + - type: input + id: os + attributes: + label: Operating system + placeholder: "macOS 15, Ubuntu 24.04, Windows 11" + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..f810889 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Security vulnerability report + url: https://github.com/haoranc/agent-estimate/security/advisories/new + about: Report security issues privately through GitHub Security Advisories. + - name: Support and usage questions + url: https://github.com/haoranc/agent-estimate/blob/main/SUPPORT.md + about: Read support options and troubleshooting guidance. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..52e2787 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,46 @@ +name: Feature request +description: Propose an improvement or new capability +title: "[Feature]: " +labels: ["enhancement"] +body: + - type: checkboxes + id: precheck + attributes: + label: Pre-flight checklist + options: + - label: I searched existing issues and did not find a duplicate proposal. + required: true + - label: This request is for agent-estimate itself (not only a local workflow). + required: true + + - type: textarea + id: problem + attributes: + label: Problem statement + description: What user problem are you trying to solve? + placeholder: As a user, I cannot... + validations: + required: true + + - type: textarea + id: proposal + attributes: + label: Proposed solution + description: Describe what you want to happen. + placeholder: Add a new flag/subcommand/behavior... + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: What have you tried, and why is it insufficient? + placeholder: Current workaround is... + + - type: textarea + id: scope + attributes: + label: Scope and impact + description: Who benefits and what areas are touched (CLI, action, plugin, docs)? + placeholder: Impacts estimate command and docs... diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..8af717c --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,22 @@ +## Summary + +Describe the change and why it is needed. + +## Related Issues + +Use `Fixes #` or `Refs #` where applicable. + +## Validation + +List what you ran locally: + +- [ ] `ruff check .` +- [ ] `pytest -q` +- [ ] Additional targeted checks (if applicable) + +## Checklist + +- [ ] Scope is focused and does not include unrelated changes +- [ ] Docs/README/changelog updated if behavior changed +- [ ] New behavior is covered by tests where practical +- [ ] No secrets or private data added diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..e5d2b1b --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,125 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +- Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior include: + +- The use of sexualized language or imagery, and sexual attention or advances + of any kind +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or email address, + without their explicit permission +- Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official email address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at: +https://github.com/haoranc/agent-estimate/issues + +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +https://www.contributor-covenant.org/version/2/1/code_of_conduct/. + +Community Impact Guidelines were inspired by +https://github.com/mozilla/diversity. + +[homepage]: https://www.contributor-covenant.org diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..43a5a7c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,65 @@ +# Contributing to agent-estimate + +Thanks for your interest in contributing. + +## Ground Rules + +- Be respectful and collaborative. +- Follow the [Code of Conduct](./CODE_OF_CONDUCT.md). +- Keep changes focused and well-tested. + +## Development Setup + +Requirements: + +- Python 3.10+ +- Git + +Setup: + +```bash +python -m venv .venv +source .venv/bin/activate +pip install -e '.[dev]' +``` + +## Local Validation + +Run before opening a pull request: + +```bash +ruff check . +pytest -q +``` + +If your change touches CLI behavior, include at least one integration-style test update in `tests/integration/` when appropriate. + +## Pull Request Workflow + +1. Fork the repository and branch from `main`. +2. Keep PRs scoped to one problem. +3. Link related issue(s) in the PR description. +4. Include a short test plan and validation output. +5. Update docs/changelog when behavior changes. + +## Reporting Bugs + +Use the bug report issue template and include: + +- Expected behavior +- Actual behavior +- Minimal reproduction steps +- Python version, OS, and package version + +## Proposing Features + +Use the feature request template and explain: + +- Problem statement +- Proposed solution +- Alternatives considered +- Potential tradeoffs + +## Security + +For security disclosures, follow [SECURITY.md](./SECURITY.md) and use private reporting. diff --git a/README.md b/README.md index 02adc91..a6e61e9 100644 --- a/README.md +++ b/README.md @@ -229,6 +229,10 @@ agent-estimate estimate "Ship packaging flow" --config ./my_agents.yaml ## Contributing +See [CONTRIBUTING.md](./CONTRIBUTING.md) for full workflow and expectations. + +Quick start: + 1. Fork and create a branch from `main`. 2. Install dev dependencies: ```bash @@ -241,6 +245,13 @@ agent-estimate estimate "Ship packaging flow" --config ./my_agents.yaml ``` 4. Open a pull request with a clear summary and test evidence. +## Community + +- Code of Conduct: [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) +- Security Policy: [SECURITY.md](./SECURITY.md) +- Support: [SUPPORT.md](./SUPPORT.md) +- Changelog: [CHANGELOG.md](./CHANGELOG.md) + ## License Apache License 2.0 diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..367aa8b --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,33 @@ +# Security Policy + +## Supported Versions + +The project currently provides security fixes for the latest released minor line. + +| Version | Supported | +| --- | --- | +| 0.4.x | Yes | +| < 0.4.0 | No | + +## Reporting a Vulnerability + +Please report suspected vulnerabilities through a private GitHub Security Advisory: + +- [Report a vulnerability](https://github.com/haoranc/agent-estimate/security/advisories/new) + +Do not open public GitHub issues for security vulnerabilities. + +When reporting, include: + +- A clear description of the issue and impact +- Reproduction steps or proof of concept +- Affected versions and environment details +- Any known mitigations + +## Response Process + +- Initial acknowledgement target: within 3 business days +- Triage and severity assessment: as quickly as possible after acknowledgement +- Fix and coordinated disclosure: as soon as a safe patch is ready + +We will coordinate disclosure timing with the reporter and credit the reporter in release notes unless you request otherwise. diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 0000000..9b0fbc2 --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,23 @@ +# Support + +## Getting Help + +For usage questions and troubleshooting: + +1. Read the [README](./README.md) for install and command examples. +2. Search existing [GitHub issues](https://github.com/haoranc/agent-estimate/issues). +3. Open a new issue if needed. + +## Bug Reports and Feature Requests + +- Use the issue templates when opening bug reports or feature requests. +- Include clear reproduction steps and environment details. + +## Security Issues + +Do not report security vulnerabilities in public issues. +Use the private process documented in [SECURITY.md](./SECURITY.md). + +## Scope + +Support is provided on a best-effort basis by maintainers and contributors. diff --git a/pyproject.toml b/pyproject.toml index 8be8d23..22f1c17 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -38,6 +38,9 @@ dev = [ Homepage = "https://github.com/haoranc/agent-estimate" Repository = "https://github.com/haoranc/agent-estimate" Issues = "https://github.com/haoranc/agent-estimate/issues" +Changelog = "https://github.com/haoranc/agent-estimate/blob/main/CHANGELOG.md" +Security = "https://github.com/haoranc/agent-estimate/security/policy" +Support = "https://github.com/haoranc/agent-estimate/blob/main/SUPPORT.md" [project.scripts] agent-estimate = "agent_estimate.cli.app:main" From e58592b73832a078edb7c2bb857eb08512e3aaf7 Mon Sep 17 00:00:00 2001 From: spbkgw-beep Date: Thu, 26 Feb 2026 17:43:25 -0800 Subject: [PATCH 2/2] docs: address review nits for coc contact and windows setup --- CODE_OF_CONDUCT.md | 7 +++++-- CONTRIBUTING.md | 6 ++++++ 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index e5d2b1b..c657d16 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -59,8 +59,11 @@ representative at an online or offline event. ## Enforcement Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported to the community leaders responsible for enforcement at: -https://github.com/haoranc/agent-estimate/issues +reported privately to the community leaders responsible for enforcement at: +https://github.com/haoranc/agent-estimate/security/advisories/new + +For Code of Conduct reports, include `[CoC]` in the advisory title so it can be +triaged appropriately. All complaints will be reviewed and investigated promptly and fairly. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 43a5a7c..3153ac9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -23,6 +23,12 @@ source .venv/bin/activate pip install -e '.[dev]' ``` +Windows PowerShell activation: + +```powershell +.venv\\Scripts\\Activate.ps1 +``` + ## Local Validation Run before opening a pull request: