From 4626f33c8f2269efdc11811d2c5f04534e762301 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 6 Feb 2026 15:19:31 +0000 Subject: [PATCH 1/3] Initial plan From 1e6cfb7db25eea4e63426525e822db271fe77819 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 6 Feb 2026 15:22:28 +0000 Subject: [PATCH 2/3] docs: add contributing guidelines and PR title format guide Co-authored-by: groupthinking <154503486+groupthinking@users.noreply.github.com> --- .github/PR_TITLE_GUIDE.md | 57 +++++++++++++++++++++++++ .github/pull_request_template.md | 39 +++++++++++++++++ CONTRIBUTING.md | 73 ++++++++++++++++++++++++++++++++ README.md | 10 +++++ 4 files changed, 179 insertions(+) create mode 100644 .github/PR_TITLE_GUIDE.md create mode 100644 .github/pull_request_template.md create mode 100644 CONTRIBUTING.md diff --git a/.github/PR_TITLE_GUIDE.md b/.github/PR_TITLE_GUIDE.md new file mode 100644 index 0000000..1399c5d --- /dev/null +++ b/.github/PR_TITLE_GUIDE.md @@ -0,0 +1,57 @@ +# PR Title Recommendations + +## For PR #4: "updates to the `README.md`" + +### Current Issue +The PR title "updates to the `README.md`" does not follow the conventional commits format required by our PR validation workflow. + +### Recommended Title +Based on the changes in PR #4, the title should be: + +``` +docs: update README.md and simplify xAI instructions +``` + +### Why This Format? + +1. **Type**: `docs` - This PR primarily contains documentation changes +2. **Description**: Clear, concise explanation of what was changed +3. **Follows Convention**: Matches the pattern `^(feat|fix|docs|style|refactor|test|chore|perf|ci|build|revert)(\(.+\))?:` + +### Alternative Titles (if applicable) + +If the PR includes multiple types of changes, consider: +- `docs: revise README and update setup instructions` +- `docs(readme): simplify xAI setup guide and update examples` + +### How to Update PR Title + +1. Go to the PR page on GitHub +2. Click the "Edit" button next to the PR title +3. Update the title to follow the format above +4. Save changes + +The PR validation workflow will then pass with no warnings. + +## For Future PRs + +Please refer to [CONTRIBUTING.md](../CONTRIBUTING.md) for comprehensive guidelines on: +- PR title format (conventional commits) +- PR description requirements +- Code style guidelines +- Testing requirements + +### Quick Reference + +| Type | When to Use | Example | +|------|-------------|---------| +| `feat` | New feature | `feat(agent): add autonomous reply functionality` | +| `fix` | Bug fix | `fix(xapi): correct mention polling interval` | +| `docs` | Documentation only | `docs: update README.md and simplify xAI instructions` | +| `refactor` | Code restructuring | `refactor(grok): simplify AI decision logic` | +| `chore` | Maintenance | `chore: update dependencies to latest versions` | +| `ci` | CI/CD changes | `ci: add PR validation workflow` | + +--- + +**Note**: The PR validation workflow treats conventional commits format as a **warning** (not an error), so PRs will not be blocked. However, following this format improves project maintainability and changelog generation. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..9218122 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,39 @@ +## Description + + + +## Motivation + + + +## Changes + + +- +- +- + +## Related Issues + + +Closes # + +## Testing + + +- [ ] Builds successfully (`npm run build`) +- [ ] Tested in simulation mode +- [ ] Tested with real API calls (if applicable) + +## Checklist + +- [ ] PR title follows [conventional commits format](../CONTRIBUTING.md#pr-title-format) (e.g., `feat:`, `fix:`, `docs:`) +- [ ] PR description is clear and complete +- [ ] Code follows project style guidelines +- [ ] Changes are focused and reasonably sized +- [ ] Documentation updated (if needed) +- [ ] No sensitive information (API keys, tokens) committed + +## Screenshots / Logs (if applicable) + + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..4d389e2 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,73 @@ +# Contributing to MyXstack + +Thank you for contributing to MyXstack! This guide will help you understand our contribution process and conventions. + +## Pull Request Guidelines + +### PR Title Format + +We follow the [Conventional Commits](https://www.conventionalcommits.org/) format for PR titles. This helps us automatically generate changelogs and understand the nature of changes at a glance. + +**Format**: `(): ` + +**Types**: +- `feat`: A new feature +- `fix`: A bug fix +- `docs`: Documentation changes only +- `style`: Code style changes (formatting, semicolons, etc.) that don't affect functionality +- `refactor`: Code changes that neither fix bugs nor add features +- `perf`: Performance improvements +- `test`: Adding or updating tests +- `chore`: Maintenance tasks, dependency updates +- `ci`: Changes to CI/CD configuration +- `build`: Changes to build system or dependencies +- `revert`: Reverting a previous commit + +**Scope** (optional): The area of the codebase affected (e.g., `agent`, `xapi`, `grok`, `mcp`) + +**Examples**: +- `docs: update README.md and simplify xAI instructions` +- `feat(agent): add autonomous reply functionality` +- `fix(xapi): correct mention polling interval` +- `chore: update dependencies to latest versions` +- `ci: add PR validation workflow` + +### PR Description + +- Provide a clear description of what the PR does (minimum 20 characters) +- Reference related issues using `#issue-number` +- Explain the motivation for the change +- List any breaking changes +- Include testing steps if applicable + +### PR Size + +- Try to keep PRs focused and under 500 lines of changes +- Large PRs (>500 lines) will trigger a warning +- Consider breaking large changes into smaller, reviewable chunks +- If a large PR is unavoidable, provide extra context in the description + +## Code Style + +Follow the guidelines in `.github/copilot-instructions.md`: +- Use TypeScript strict mode +- Prefer async/await over raw promises +- Always wrap API calls in try-catch blocks +- Use explicit types; avoid `any` +- Follow naming conventions: + - Classes: PascalCase (e.g., `XAPIClient`) + - Functions: camelCase (e.g., `fetchMentions`) + - Constants: UPPER_SNAKE_CASE (e.g., `DEFAULT_POLLING_INTERVAL`) + +## Testing + +- Run `npm run build` to verify TypeScript compilation +- Test changes in simulation mode when possible +- Ensure existing tests pass before submitting + +## Questions? + +If you have questions, feel free to: +- Open an issue for discussion +- Ask in your PR comments +- Check the existing documentation in `ARCHITECTURE.md` or `USAGE.md` diff --git a/README.md b/README.md index 0dd0e21..9bcb346 100644 --- a/README.md +++ b/README.md @@ -115,3 +115,13 @@ Then tag your bot from another account to see it respond. Replace the placeholde ## Current status Start with Phases 1–4 today. If you hit a snag, share the exact output/error and we can debug together. + +## Contributing + +We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on: +- PR title format (conventional commits) +- Code style and conventions +- Testing requirements +- How to submit pull requests + +For quick reference on PR titles, see [.github/PR_TITLE_GUIDE.md](.github/PR_TITLE_GUIDE.md). From 4504b9eb969ec68e512824106a4bb71fe2a4c337 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 6 Feb 2026 15:23:39 +0000 Subject: [PATCH 3/3] docs: refactor PR title guide to be more general Co-authored-by: groupthinking <154503486+groupthinking@users.noreply.github.com> --- .github/PR_TITLE_GUIDE.md | 69 +++++++++++++++----------------- .github/pull_request_template.md | 2 +- 2 files changed, 34 insertions(+), 37 deletions(-) diff --git a/.github/PR_TITLE_GUIDE.md b/.github/PR_TITLE_GUIDE.md index 1399c5d..e486d4b 100644 --- a/.github/PR_TITLE_GUIDE.md +++ b/.github/PR_TITLE_GUIDE.md @@ -1,56 +1,53 @@ -# PR Title Recommendations +# PR Title Quick Reference -## For PR #4: "updates to the `README.md`" +## Conventional Commits Format -### Current Issue -The PR title "updates to the `README.md`" does not follow the conventional commits format required by our PR validation workflow. +All PR titles should follow the [Conventional Commits](https://www.conventionalcommits.org/) format: -### Recommended Title -Based on the changes in PR #4, the title should be: +**Format**: `(): ` -``` -docs: update README.md and simplify xAI instructions -``` +### Types and Examples -### Why This Format? - -1. **Type**: `docs` - This PR primarily contains documentation changes -2. **Description**: Clear, concise explanation of what was changed -3. **Follows Convention**: Matches the pattern `^(feat|fix|docs|style|refactor|test|chore|perf|ci|build|revert)(\(.+\))?:` - -### Alternative Titles (if applicable) - -If the PR includes multiple types of changes, consider: -- `docs: revise README and update setup instructions` -- `docs(readme): simplify xAI setup guide and update examples` +| Type | When to Use | Example | +|------|-------------|---------| +| `feat` | New feature | `feat(agent): add autonomous reply functionality` | +| `fix` | Bug fix | `fix(xapi): correct mention polling interval` | +| `docs` | Documentation only | `docs: update README.md and simplify xAI instructions` | +| `refactor` | Code restructuring | `refactor(grok): simplify AI decision logic` | +| `chore` | Maintenance | `chore: update dependencies to latest versions` | +| `ci` | CI/CD changes | `ci: add PR validation workflow` | +| `style` | Formatting changes | `style: fix indentation in config files` | +| `test` | Test updates | `test: add unit tests for agent service` | +| `perf` | Performance improvements | `perf(xapi): optimize mention polling` | ### How to Update PR Title -1. Go to the PR page on GitHub +1. Go to your PR page on GitHub 2. Click the "Edit" button next to the PR title 3. Update the title to follow the format above 4. Save changes The PR validation workflow will then pass with no warnings. -## For Future PRs +## Common Scenarios -Please refer to [CONTRIBUTING.md](../CONTRIBUTING.md) for comprehensive guidelines on: -- PR title format (conventional commits) -- PR description requirements -- Code style guidelines -- Testing requirements +### Documentation Updates +**Problem**: PR title like "updates to the `README.md`" +**Solution**: `docs: update README.md and simplify xAI instructions` -### Quick Reference +### Multiple File Changes +**Problem**: PR title like "various fixes" +**Solution**: Choose the primary change type: +- `fix: resolve polling and authentication issues` +- `refactor: restructure API client and services` -| Type | When to Use | Example | -|------|-------------|---------| -| `feat` | New feature | `feat(agent): add autonomous reply functionality` | -| `fix` | Bug fix | `fix(xapi): correct mention polling interval` | -| `docs` | Documentation only | `docs: update README.md and simplify xAI instructions` | -| `refactor` | Code restructuring | `refactor(grok): simplify AI decision logic` | -| `chore` | Maintenance | `chore: update dependencies to latest versions` | -| `ci` | CI/CD changes | `ci: add PR validation workflow` | +### Feature Additions +**Problem**: PR title like "new stuff" +**Solution**: `feat(agent): implement autonomous decision-making` + +## Full Guidelines + +For comprehensive contribution guidelines, see [CONTRIBUTING.md](/CONTRIBUTING.md). --- diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 9218122..c8aa8d1 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -27,7 +27,7 @@ Closes # ## Checklist -- [ ] PR title follows [conventional commits format](../CONTRIBUTING.md#pr-title-format) (e.g., `feat:`, `fix:`, `docs:`) +- [ ] PR title follows [conventional commits format](/CONTRIBUTING.md#pr-title-format) (e.g., `feat:`, `fix:`, `docs:`) - [ ] PR description is clear and complete - [ ] Code follows project style guidelines - [ ] Changes are focused and reasonably sized