diff --git a/.github/PR_TITLE_GUIDE.md b/.github/PR_TITLE_GUIDE.md new file mode 100644 index 0000000..e486d4b --- /dev/null +++ b/.github/PR_TITLE_GUIDE.md @@ -0,0 +1,54 @@ +# PR Title Quick Reference + +## Conventional Commits Format + +All PR titles should follow the [Conventional Commits](https://www.conventionalcommits.org/) format: + +**Format**: `(): ` + +### Types and 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 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. + +## Common Scenarios + +### Documentation Updates +**Problem**: PR title like "updates to the `README.md`" +**Solution**: `docs: update README.md and simplify xAI instructions` + +### 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` + +### 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). + +--- + +**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..c8aa8d1 --- /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).