From 16618cea31d8c83ecb9610ab5a2a609d54c38799 Mon Sep 17 00:00:00 2001 From: Joey French Date: Sat, 3 Jan 2026 00:15:40 -0600 Subject: [PATCH] Update issue creation documentation and templates for clarity and consistency - Revised the create-issue command documentation to generalize repository references and improve clarity in instructions. - Updated YAML templates for feature, RFC, and spec issues to provide clearer descriptions and guidance on usage. - Enhanced the sanitization steps for public visibility to include specific customer data and business metrics. These changes aim to streamline the issue creation process and ensure better understanding for users. --- .claude/commands/create-issue.md | 73 ++++---- .github/CONTRIBUTING.md | 286 +++++++++++++++++++++++++++++ .github/ISSUE_TEMPLATE/feature.yml | 2 +- .github/ISSUE_TEMPLATE/rfc.yml | 4 +- .github/ISSUE_TEMPLATE/spec.yml | 4 +- 5 files changed, 331 insertions(+), 38 deletions(-) create mode 100644 .github/CONTRIBUTING.md diff --git a/.claude/commands/create-issue.md b/.claude/commands/create-issue.md index 99f918a..30502c3 100644 --- a/.claude/commands/create-issue.md +++ b/.claude/commands/create-issue.md @@ -1,29 +1,32 @@ -Create a GitHub issue for the robosystems-python-client repository based on the user's input. +Create a GitHub issue for the current repository based on the user's input. ## Instructions 1. **Determine Issue Type** - Based on the user's description, determine which type to use: - **Bug**: Defects or unexpected behavior - **Task**: Specific, bounded work items that can be completed in one PR - - **Feature**: User-facing feature suggestions - - **Spec**: Features requiring technical design, multiple phases, or architectural changes - - **RFC**: Significant design proposals needing team discussion before implementation + - **Feature**: Request a new capability (no design required) + - **RFC**: Propose a design for discussion before implementation (if available) + - **Spec**: Approved implementation plan ready for execution (if available) + + Note: Not all repos have RFC/Spec templates. Check `.github/ISSUE_TEMPLATE/` first. 2. **Gather Context** - If the user provides a file path or references existing code: - Read the relevant files to understand the current implementation - - Check client methods in `/robosystems_client/` - - Review tests in `/tests/` + - Check related configuration files + - Review any referenced documentation 3. **Draft the Issue** - Use the YAML templates in `.github/ISSUE_TEMPLATE/`: - - `bug.yml` - Include reproduction steps, version info + - `bug.yml` - Include reproduction steps, impact, environment - `task.yml` - Be specific about scope and acceptance criteria - - `feature.yml` - Simple "I wish I could..." format - - `spec.yml` - Fill in all sections with technical detail - - `rfc.yml` - Comprehensive design with alternatives considered + - `feature.yml` - Capture the need and why it matters + - `spec.yml` - Fill in all sections with technical detail (if available) + - `rfc.yml` - Comprehensive design with alternatives considered (if available) 4. **Sanitize for Public Visibility** - Before creating: - - Remove any internal API details or secrets - - Generalize any sensitive information + - Remove any internal pricing, margins, or cost details + - Remove specific customer names or data + - Generalize any sensitive business metrics - Keep technical implementation details (these are fine to share) 5. **Create the Issue** - Use `gh issue create` with: @@ -33,34 +36,24 @@ Create a GitHub issue for the robosystems-python-client repository based on the 6. **Set Issue Type** - After creation, set the issue type via GraphQL: ```bash + # Get repo info from current directory + REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner) + OWNER=$(echo $REPO | cut -d'/' -f1) + NAME=$(echo $REPO | cut -d'/' -f2) + # Get issue ID - gh api graphql -f query='{ repository(owner: "RoboFinSystems", name: "robosystems-python-client") { issue(number: NUMBER) { id } } }' + gh api graphql -f query="{ repository(owner: \"$OWNER\", name: \"$NAME\") { issue(number: NUMBER) { id } } }" + + # Get available issue types for this repo + gh api graphql -f query="{ repository(owner: \"$OWNER\", name: \"$NAME\") { issueTypes(first: 10) { nodes { id name } } } }" - # Set type (use correct type ID) + # Set type (use correct type ID from above) gh api graphql -f query='mutation { updateIssue(input: { id: "ISSUE_ID", issueTypeId: "TYPE_ID" }) { issue { number } } }' ``` - Issue Type IDs (org-level, shared across repos): - - Task: `IT_kwDODL_jkM4BnUUo` - - Bug: `IT_kwDODL_jkM4BnUUp` - - Feature: `IT_kwDODL_jkM4BnUUq` - - Spec: `IT_kwDODL_jkM4B0XrY` - - RFC: `IT_kwDODL_jkM4B0XrZ` - ## Labels -Issue types handle primary categorization. Use labels for metadata. - -**Area** (which part of the client): -- `area:client` - Core client functionality -- `area:api` - API method implementations -- `area:types` - Pydantic models and type definitions -- `area:auth` - Authentication handling -- `area:errors` - Error handling -- `area:testing` - Test coverage -- `area:docs` - Documentation -- `area:packaging` - pyproject.toml, releases -- `area:ci-cd` - Workflows, releases +Issue types handle primary categorization. Use labels for metadata (varies by repo): **Priority** (when to do it): - `priority:critical` - Drop everything @@ -76,6 +69,20 @@ Issue types handle primary categorization. Use labels for metadata. - `blocked` - Waiting on something - `needs-review` - Ready for review +Check `gh label list` for available labels in the current repo. + +## Example Usage + +User: "We need to add export functionality" + +Response: I'll create a feature issue for export functionality. Let me first understand the current state... + +[Read relevant files to understand current implementation] +[Draft issue matching the template structure] +[Create issue with gh issue create] +[Set issue type via GraphQL] +[Add appropriate labels] + ## Output Format After creating the issue, provide: diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..2b8d173 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,286 @@ +# Contributing to RoboSystems Python Client + +Thank you for your interest in contributing to the RoboSystems Python Client! This is the official Python SDK for interacting with the RoboSystems API. + +## Community + +- **[Discussions](https://github.com/orgs/RoboFinSystems/discussions)** - Questions, ideas, and general conversation +- **[Project Board](https://github.com/orgs/RoboFinSystems/projects/3)** - Track work across all RoboSystems repositories +- **[Wiki](https://github.com/RoboFinSystems/robosystems/wiki)** - Architecture docs and guides + +## Table of Contents + +- [Getting Started](#getting-started) +- [Development Process](#development-process) +- [How to Contribute](#how-to-contribute) +- [Development Setup](#development-setup) +- [Coding Standards](#coding-standards) +- [Testing](#testing) +- [Pull Request Process](#pull-request-process) +- [Publishing](#publishing) +- [Security](#security) + +## Getting Started + +1. **Fork the repository** on GitHub +2. **Clone your fork** locally: + ```bash + git clone https://github.com/YOUR-USERNAME/robosystems-python-client.git + cd robosystems-python-client + ``` +3. **Add the upstream remote**: + ```bash + git remote add upstream https://github.com/RoboFinSystems/robosystems-python-client.git + ``` +4. **Set up your development environment** (see [Development Setup](#development-setup)) + +## Development Process + +We use GitHub flow for our development process: + +1. Create a feature branch from `main` +2. Make your changes in small, atomic commits +3. Write or update tests for your changes +4. Update documentation as needed +5. Create a PR to the `main` branch + +### Branch Naming + +Use descriptive branch names: + +- `feature/add-new-method` - New features +- `bugfix/fix-auth-error` - Bug fixes +- `chore/update-deps` - Maintenance tasks + +**Note:** All PRs must target the `main` branch only. + +## How to Contribute + +### Issue Types + +We use issue templates to organize work: + +| Type | When to Use | +|------|-------------| +| **Bug** | Defects or unexpected behavior | +| **Task** | Specific, bounded work that fits in one PR | +| **Feature** | Request a new capability (no design required) | +| **RFC** | Propose a design for discussion before implementation | +| **Spec** | Approved implementation plan ready for execution | + +### Reporting Bugs + +Before creating a bug report, check existing issues to avoid duplicates. Include: + +- Steps to reproduce the issue +- Expected vs actual behavior +- SDK version (`pip show robosystems-client`) +- Python version +- Relevant error messages and tracebacks + +### First-Time Contributors + +Look for issues labeled `good first issue` or `help wanted`. These are great starting points for new contributors. + +## Development Setup + +### Prerequisites + +- Python 3.11+ (check `.python-version`) +- `uv` for package management +- Git configured with your GitHub account + +### Local Development Environment + +1. **Install uv** (if not already installed): + + ```bash + curl -LsSf https://astral.sh/uv/install.sh | sh + # Or on macOS: brew install uv + ``` + +2. **Install dependencies**: + + ```bash + uv sync + ``` + +3. **Run tests**: + + ```bash + uv run pytest + ``` + +### Environment Configuration + +For integration tests, create a `.env` file: + +```env +ROBOSYSTEMS_API_KEY=your-api-key +ROBOSYSTEMS_API_URL=https://api.robosystems.ai # or http://localhost:8000 for local +``` + +## Coding Standards + +### Python Code Style + +- **Formatter**: Ruff (88 character line length) +- **Linter**: Ruff +- **Type checking**: Pyright/Basedpyright +- **Docstrings**: Google style + +Run code quality checks: + +```bash +uv run ruff check . # Run linting +uv run ruff check --fix # Auto-fix linting issues +uv run ruff format . # Format code +uv run pyright # Type checking +``` + +### Commit Messages + +Follow the Conventional Commits specification: + +``` +type(scope): subject +``` + +Types: + +- `feat`: New feature (new method, type, etc.) +- `fix`: Bug fix +- `docs`: Documentation changes +- `refactor`: Code refactoring +- `test`: Test changes +- `chore`: Maintenance tasks + +Examples: + +``` +feat(graphs): add create_graph method +fix(auth): resolve token refresh issue +docs(readme): update usage examples +``` + +### SDK Design Guidelines + +When adding new methods: + +- Follow existing naming conventions (snake_case) +- Use Pydantic models for request/response types +- Include comprehensive docstrings with examples +- Add type hints to all functions +- Handle errors with appropriate exception types + +## Testing + +### Test Requirements + +- All new methods must include tests +- Bug fixes should include regression tests +- Tests must pass locally before submitting PR + +### Running Tests + +```bash +# Run all tests +uv run pytest + +# Run with coverage +uv run pytest --cov + +# Run specific test file +uv run pytest tests/test_graphs.py + +# Run with verbose output +uv run pytest -v +``` + +## Pull Request Process + +### Before Creating a PR + +1. **Commit all changes**: + + ```bash + git add . + git commit -m "feat: your descriptive commit message" + ``` + +2. **Update from upstream**: + + ```bash + git fetch origin + git rebase origin/main + ``` + +3. **Run all checks locally**: + + ```bash + uv run ruff check . + uv run ruff format --check . + uv run pytest + ``` + +4. **Push your branch**: + ```bash + git push origin your-branch-name + ``` + +### PR Requirements + +- All tests must pass +- Code must pass linting and formatting checks +- Must include appropriate documentation updates +- Must be reviewed by at least one maintainer + +### Manual PR Creation + +```bash +gh pr create --base main --title "Your PR title" --body "Your PR description" +``` + +## Publishing + +This package is published to PyPI as `robosystems-client`. Releases are managed by maintainers: + +```bash +# Build the package +uv build + +# Publish to PyPI +uv publish +``` + +**Note:** Only maintainers can publish new versions. + +## Security + +### Security Vulnerabilities + +**DO NOT** create public issues for security vulnerabilities. Instead: + +1. Email security@robosystems.ai with details +2. Include steps to reproduce if possible +3. Allow time for the issue to be addressed before public disclosure + +### Security Best Practices + +- Never commit API keys or secrets +- Never log sensitive data +- Validate inputs before sending to API +- Keep dependencies up to date + +## Questions and Support + +- **[GitHub Discussions](https://github.com/orgs/RoboFinSystems/discussions)** - Best place for questions and community conversation +- **[GitHub Issues](https://github.com/RoboFinSystems/robosystems-python-client/issues)** - Bug reports and feature requests for this repo +- **[API Reference](https://api.robosystems.ai/docs)** - Backend API documentation +- **Email**: security@robosystems.ai for security issues only + +## Recognition + +Contributors will be recognized in our [Contributors](https://github.com/RoboFinSystems/robosystems-python-client/graphs/contributors) page. + +Thank you for contributing to RoboSystems Python Client! diff --git a/.github/ISSUE_TEMPLATE/feature.yml b/.github/ISSUE_TEMPLATE/feature.yml index 62b284b..2af5972 100644 --- a/.github/ISSUE_TEMPLATE/feature.yml +++ b/.github/ISSUE_TEMPLATE/feature.yml @@ -1,5 +1,5 @@ name: Feature -description: I wish I could... +description: Request a new capability (no design required) type: Feature body: - type: textarea diff --git a/.github/ISSUE_TEMPLATE/rfc.yml b/.github/ISSUE_TEMPLATE/rfc.yml index 12111dc..4c22578 100644 --- a/.github/ISSUE_TEMPLATE/rfc.yml +++ b/.github/ISSUE_TEMPLATE/rfc.yml @@ -1,5 +1,5 @@ -name: RFC (Design Document) -description: Propose a significant design change for team feedback +name: RFC +description: Propose a design for discussion before implementation type: RFC body: - type: textarea diff --git a/.github/ISSUE_TEMPLATE/spec.yml b/.github/ISSUE_TEMPLATE/spec.yml index c346294..bafa754 100644 --- a/.github/ISSUE_TEMPLATE/spec.yml +++ b/.github/ISSUE_TEMPLATE/spec.yml @@ -1,5 +1,5 @@ -name: Technical Specification -description: Detailed design for a feature or system change +name: Spec +description: Approved implementation plan ready for execution type: Spec body: - type: textarea