From 1c40c74b1913aa3d605f4abb8dbbe77e02ce273b Mon Sep 17 00:00:00 2001 From: "codegen-sh[bot]" <131295404+codegen-sh[bot]@users.noreply.github.com> Date: Sun, 27 Apr 2025 22:41:08 +0000 Subject: [PATCH] Enhance documentation with expanded guides and examples --- docs/gen/capabilities.mdx | 116 ++++++++++++++++++++++++++++++++++- docs/gen/faq.mdx | 43 ++++++++++++- docs/gen/getting-started.mdx | 94 ++++++++++++++++++++++++++++ docs/gen/introduction.mdx | 17 ++++- docs/gen/troubleshooting.mdx | 98 +++++++++++++++++++++++++++++ 5 files changed, 365 insertions(+), 3 deletions(-) create mode 100644 docs/gen/getting-started.mdx create mode 100644 docs/gen/troubleshooting.mdx diff --git a/docs/gen/capabilities.mdx b/docs/gen/capabilities.mdx index e936e8eda..928fed043 100644 --- a/docs/gen/capabilities.mdx +++ b/docs/gen/capabilities.mdx @@ -64,4 +64,118 @@ Codegen's brain (powered by Claude 3.7 Sonnet) intelligently selects and combine 3. Execute the necessary actions across GitHub, Linear, and your codebase 4. Provide clear, helpful responses back in Slack -This seamless integration allows you to manage your entire development workflow through simple conversations, without having to switch between different platforms and interfaces. \ No newline at end of file +This seamless integration allows you to manage your entire development workflow through simple conversations, without having to switch between different platforms and interfaces. + +## Recommended Best Practices for Using Codegen + +Here are some recommended best practices for integrating Codegen effectively into your development workflow: + +### Workflow Integration + +- **Small bug fixes**: For minor issues, consider using Codegen for instant fixes and merges + + **Example**: + ``` + @codegen Fix the typo in the login button text in src/components/LoginForm.tsx + ``` + + Codegen will quickly locate the issue, make the correction, and create a PR that can be immediately reviewed and merged. + +- **Larger tickets**: A multi-step approach often works best: + 1. Ask Codegen to do a first pass on the implementation + 2. Check out the branch and review the changes + 3. Add any necessary adjustments + 4. QA the changes + 5. Merge the code + + **Example**: + ``` + @codegen Create a PR to implement JWT authentication in our Express backend + ``` + + Codegen will analyze your codebase, implement a JWT authentication system, and create a PR. You can then review the implementation, make any necessary adjustments, test thoroughly, and merge when ready. + +### When to Use Codegen vs. IDE + +Consider using Codegen for: +- Initial exploration and first pass on tickets and engineering efforts + + **Example**: + ``` + @codegen How would you implement a rate limiting middleware for our API? + ``` + + Codegen will analyze your codebase and suggest an implementation approach, which you can then refine in your IDE. + +- Quickly gathering context on issues (e.g., explaining errors in notification threads) + + **Example**: + ``` + @codegen Why are we getting this error in our logs: "TypeError: Cannot read property 'id' of undefined"? + ``` + + Codegen will investigate the error by examining your codebase and recent changes, providing insights on the root cause. + +- Understanding the "blast radius" of a given change to assess its impact + + **Example**: + ``` + @codegen What would be affected if we change the User interface to make the 'email' field optional? + ``` + + Codegen will analyze your codebase to identify all places that depend on the User interface and might be affected by this change. + +- Getting a solid first pass at approximately 80% of your work + + **Example**: + ``` + @codegen Create a PR to add pagination to our user list API endpoint + ``` + + Codegen will implement pagination in your API, handling the core functionality that you can then refine and extend. + +Use your preferred IDE (like Cursor or VS Code) for: +- Making precise adjustments after Codegen's first pass + + After Codegen creates a PR implementing a feature, you can check out the branch in your IDE to make specific adjustments to the implementation. + +- Detailed work that requires deep context + + Complex refactoring that spans multiple files and requires a deep understanding of the codebase's architecture might be better handled in your IDE after getting initial guidance from Codegen. + +### Effectiveness Tips + +- Be diligent about analyzing tasks and determining how to break them down for Codegen + + **Example**: Instead of asking Codegen to "Implement a new authentication system," break it down into smaller tasks like "Create a login form component," "Implement JWT token generation on the backend," and "Add authentication middleware to protected routes." + +- Split complex tasks into manageable chunks + + **Example**: When implementing a new feature like a shopping cart, you might ask Codegen to: + 1. First create the data models + 2. Then implement the API endpoints + 3. Finally, create the UI components + +- Don't hesitate to discard unhelpful outputs and try a different approach + + If Codegen's implementation doesn't meet your needs, provide specific feedback about what's missing or incorrect, and ask for a revised implementation. + +- View Codegen as a powerful assistant rather than an infallible oracle + + Use Codegen to accelerate your development process, but always review its output critically and be prepared to make adjustments as needed. + +These practices can help you leverage Codegen effectively while maintaining high code quality and productivity. + +## Limitations and Known Issues + +While Codegen is a powerful tool, it's important to be aware of its limitations: + +- **Complex architectural decisions**: Codegen works best with clear, specific tasks rather than open-ended architectural decisions. + +- **Very large codebases**: Performance may be affected when working with extremely large codebases. + +- **Specialized domain knowledge**: Codegen may need additional context when working with highly specialized or domain-specific code. + +- **External service integration**: Codegen can't directly interact with external services beyond GitHub, Slack, and Linear. + +We're continuously working to improve Codegen and address these limitations. For the most up-to-date information, check our [changelog](/changelog/changelog). diff --git a/docs/gen/faq.mdx b/docs/gen/faq.mdx index 2a34b0435..1b5eae9a3 100644 --- a/docs/gen/faq.mdx +++ b/docs/gen/faq.mdx @@ -9,10 +9,51 @@ iconType: "solid" Claude 3.7. Our code agent is roughly comparable with Claude Code. + Yes! For now. Get it while it's hot. + Codegen stores this data in their private cloud. We are SOC-2 compliant. [Learn more](/introduction/about) - \ No newline at end of file + + + Install Codegen by [logging in with GitHub](https://codegen.sh/install) and setting up the necessary integrations. Once installed, you can interact with Codegen through Slack by mentioning it in a channel where it's been added. + + + + Codegen can assist with a wide range of development tasks, including: + - Code reviews and PR feedback + - Bug fixes and feature implementations + - Code refactoring and modernization + - Answering questions about your codebase + - Creating and managing issues in Linear + - Analyzing code patterns and suggesting improvements + + + + Codegen accesses your code through the GitHub integration. It only has access to repositories you've explicitly granted it permission to view. You can manage these permissions at any time through the [Codegen dashboard](https://codegen.sh/repos). + + + + Yes! Codegen works with both public and private repositories. The GitHub integration respects the permissions you've granted, ensuring your private code remains secure. + + + + Like any tool, Codegen may occasionally make mistakes. If you notice an error in Codegen's output, you can: + 1. Ask Codegen to fix the specific issue + 2. Make the correction yourself + 3. Provide feedback to help improve future responses + + Remember that you should always review Codegen's changes before merging them into your codebase. + + + + You can provide feedback directly in Slack by responding to Codegen's messages. For more detailed feedback or to report issues, contact the Codegen team through the [support channels](/introduction/community). + + + + Currently, customization options are limited, but the Codegen team is working on adding more configuration options in future updates. Stay tuned to the [changelog](/changelog/changelog) for announcements. + + diff --git a/docs/gen/getting-started.mdx b/docs/gen/getting-started.mdx new file mode 100644 index 000000000..9589bd843 --- /dev/null +++ b/docs/gen/getting-started.mdx @@ -0,0 +1,94 @@ +--- +title: "Getting Started" +sidebarTitle: "Getting Started" +icon: "rocket" +--- + +# Getting Started with Codegen + +This guide will help you set up Codegen and start using it with your team. Codegen is an AI-powered development assistant that integrates with GitHub, Slack, and Linear to streamline your development workflow. + +## Installation + +1. Visit the [Codegen installation page](https://codegen.sh/install) +2. Log in with your GitHub account +3. Grant the necessary permissions to access your repositories +4. Connect your Slack workspace +5. (Optional) Connect your Linear account for project management integration + + + + + +## First Steps with Codegen + +Once you've installed Codegen, you can start interacting with it in your Slack workspace: + +1. **Add Codegen to a channel**: Invite the Codegen bot to any channel where you want to use it +2. **Mention Codegen**: Start a conversation by mentioning `@codegen` followed by your request +3. **Wait for a response**: Codegen will process your request and respond in the thread + +## Example Interactions + +Here are some examples of how to interact with Codegen: + +### Code Review + +``` +@codegen Can you review my PR? https://github.com/your-org/your-repo/pull/123 +``` + +Codegen will analyze the PR and provide feedback directly on GitHub, as well as a summary in Slack. + +### Bug Investigation + +``` +@codegen Why are the tests failing in the auth module? +``` + +Codegen will investigate the issue by examining the codebase and recent changes, then provide insights on potential causes. + +### Feature Implementation + +``` +@codegen Create a PR to add input validation to the login form in the auth module +``` + +Codegen will analyze the codebase, implement the requested feature, and create a pull request for your review. + +### Codebase Questions + +``` +@codegen How does the authentication flow work in our app? +``` + +Codegen will analyze the codebase and explain the authentication flow, including relevant files and functions. + +## Best Practices for Using Codegen + +For the most effective experience with Codegen: + +1. **Be specific in your requests**: Provide clear context and details about what you need +2. **Start with smaller tasks**: Begin with simple requests to understand Codegen's capabilities +3. **Review Codegen's work**: Always review code changes before merging them +4. **Provide feedback**: Let Codegen know if its responses are helpful or need improvement + +For more detailed best practices, see the [Capabilities](/gen/capabilities#recommended-best-practices-for-using-codegen) page. + +## Troubleshooting + +If you encounter issues with Codegen: + +- **Codegen doesn't respond**: Make sure you've properly mentioned `@codegen` in your message +- **Repository access issues**: Check that you've granted Codegen access to the relevant repositories +- **Unclear responses**: Try rephrasing your request with more specific details +- **Integration problems**: Visit the [Codegen dashboard](https://codegen.sh/dashboard) to verify your integrations are properly connected + +## Next Steps + +Now that you're familiar with the basics, explore these resources to get more out of Codegen: + +- [Capabilities](/gen/capabilities): Learn about all of Codegen's features +- [Integrations](/gen/integrations): Discover how Codegen works with other tools +- [FAQ](/gen/faq): Find answers to common questions +- [Use Cases](/use-cases/I.%20Upgrading%20APIs): Explore real-world applications of Codegen diff --git a/docs/gen/introduction.mdx b/docs/gen/introduction.mdx index a5d953af0..cdbe8b26c 100644 --- a/docs/gen/introduction.mdx +++ b/docs/gen/introduction.mdx @@ -20,7 +20,11 @@ Codegen is an intelligent code agent powered that seamlessly integrates with Sla [Log in with GitHub](https://codegen.sh/install) to install Codegen and set up integrations. - + + Follow our step-by-step guide to start using Codegen + + + Install codegen via OAuth with Github, Slack and Linear @@ -41,3 +45,14 @@ Perform a code review on a specified pull request, providing feedback and sugges > *Do we have any tickets about Y?* Search for tickets related to a specific topic or issue. This helps in tracking and managing tasks effectively. +# Need Help? + +If you encounter any issues while using Codegen, check out our: + + + Solutions to common problems and error messages + + + + Answers to frequently asked questions + diff --git a/docs/gen/troubleshooting.mdx b/docs/gen/troubleshooting.mdx new file mode 100644 index 000000000..7d655cf7b --- /dev/null +++ b/docs/gen/troubleshooting.mdx @@ -0,0 +1,98 @@ +--- +title: "Troubleshooting" +sidebarTitle: "Troubleshooting" +icon: "wrench" +--- + +# Troubleshooting Codegen + +This guide helps you diagnose and resolve common issues you might encounter when using Codegen. + +## Connection Issues + +### Codegen Not Responding in Slack + +If Codegen doesn't respond to your messages in Slack: + +1. **Check the mention format**: Ensure you're properly mentioning Codegen with `@codegen` +2. **Verify installation**: Confirm that Codegen has been added to your Slack workspace +3. **Check channel access**: Make sure Codegen has been invited to the channel where you're trying to use it +4. **Wait for processing**: Complex requests may take longer to process + +### GitHub Integration Problems + +If Codegen can't access your repositories: + +1. **Check permissions**: Verify that you've granted Codegen access to the relevant repositories at [codegen.sh/repos](https://codegen.sh/repos) +2. **Repository visibility**: Ensure the repository is either public or that Codegen has been granted access to private repositories +3. **Organization settings**: If you're using GitHub Organizations, check that Codegen has been approved by an organization admin + +### Linear Integration Issues + +If Codegen can't access or create Linear issues: + +1. **Verify connection**: Check that your Linear account is connected in the [Codegen dashboard](https://codegen.sh/dashboard) +2. **API access**: Ensure that the Codegen app has the necessary permissions in Linear +3. **Team access**: Confirm that Codegen has access to the relevant teams in Linear + +## Usage Problems + +### Unclear or Incorrect Responses + +If Codegen's responses are unclear or incorrect: + +1. **Provide more context**: Be more specific in your request, including relevant file paths or issue numbers +2. **Break down complex requests**: Split large tasks into smaller, more manageable requests +3. **Reference specific code**: Include links to relevant files or PRs in your request + +### Code Generation Issues + +If Codegen generates incorrect or incomplete code: + +1. **Review the code**: Always review generated code before merging it +2. **Provide feedback**: Let Codegen know what's wrong with the generated code +3. **Refine your request**: Be more specific about what you want the code to do +4. **Check for edge cases**: Ensure your request accounts for all possible scenarios + +### PR Creation Failures + +If Codegen fails to create a pull request: + +1. **Repository access**: Verify that Codegen has write access to the repository +2. **Branch conflicts**: Check if there are conflicts with the target branch +3. **CI checks**: Ensure that any required CI checks are passing +4. **Branch protection**: Check if the target branch has protection rules that prevent direct pushes + +## Common Error Messages + +### "Repository not found" + +This error occurs when Codegen can't access a repository: + +1. **Check the repository name**: Ensure you've specified the correct repository name +2. **Verify access**: Confirm that Codegen has been granted access to the repository +3. **Repository exists**: Make sure the repository actually exists and hasn't been deleted or renamed + +### "Permission denied" + +This error indicates that Codegen doesn't have the necessary permissions: + +1. **Check repository permissions**: Ensure Codegen has the required access level (read/write) +2. **Organization permissions**: Verify that Codegen has been approved by your organization +3. **Branch protection**: Check if branch protection rules are preventing Codegen from pushing changes + +### "Rate limit exceeded" + +This error occurs when you've exceeded GitHub's API rate limits: + +1. **Wait and retry**: Wait for the rate limit to reset (usually within an hour) +2. **Reduce request frequency**: Limit the number of requests you make to Codegen in a short period +3. **Optimize requests**: Make more focused requests that require fewer API calls + +## Getting Additional Help + +If you're still experiencing issues after trying these troubleshooting steps: + +1. **Check the FAQ**: Review the [FAQ](/gen/faq) for answers to common questions +2. **Contact support**: Reach out to the Codegen team through the [support channels](/introduction/community) +3. **Provide details**: When reporting an issue, include as much detail as possible, including error messages and steps to reproduce the problem