|
| 1 | +<h1 align="center">Migrating a Python API to Rust with GitHub Copilot</h1> |
| 2 | +<h5 align="center">Perform a challenging migration to a completely different language</h3> |
| 3 | + |
| 4 | +<p align="center"> |
| 5 | + <a href="#mega-prerequisites">Prerequisites</a> • |
| 6 | + <a href="#books-resources">Resources</a> • |
| 7 | + <a href="#learning-objectives">Learning Objectives</a> |
| 8 | +</p> |
| 9 | + |
| 10 | +- **Who is this for**: Any tecnologist that is looking to apply AI pair-programming techniques with GitHub Copilot to perform challenging work like migrating or translating from one programming language to another. |
| 11 | +- **What you'll learn**: You'll use advanced GitHub Copilot techniques that are specifically useful when translating projects in different programming languages. |
| 12 | +- **What you'll build**: An HTTP API that uses Rust with full compatibility from the original HTTP API written in Python. |
| 13 | + |
| 14 | +## Requirements |
| 15 | + |
| 16 | +1. Enable your [GitHub Copilot service](https://github.com/github-copilot/signup) |
| 17 | +1. Open [this repository with Codespaces](https://codespaces.new/microsoft/github-copilot-migrating-languages) |
| 18 | + |
| 19 | + |
| 20 | +[](https://codespaces.new/microsoft/github-copilot-migrating-languages) |
| 21 | + |
| 22 | +## Learning Objectives |
| 23 | + |
| 24 | +In this workshop, you will: |
| 25 | + |
| 26 | + - Understand the Differences Between Python and Rust for Web Development |
| 27 | + Learn the key differences in syntax, libraries, and frameworks when transitioning from Python's FastAPI to Rust's actix-web. |
| 28 | + - Implement JSON Serialization and Deserialization in Rust |
| 29 | + Gain hands-on experience using the serde library to handle JSON data, ensuring compatibility with the original Python API. |
| 30 | + - Develop and Validate Incremental Endpoints in Rust |
| 31 | + Practice creating and testing individual endpoints iteratively, ensuring correctness and alignment with the original Python API. |
| 32 | + - Optimize Performance and Identify Bottlenecks in Rust |
| 33 | + Learn to analyze and address potential performance issues, such as redundant file serialization, while building a production-ready Rust application. |
| 34 | + |
| 35 | + |
| 36 | +## :mega: Prerequisites |
| 37 | + |
| 38 | +Before joining the workshop, there is only one prerequisite: you must have a public GitHub account. All resources, dependencies, and data are part of the repository itself. Make sure you have your GitHub Copilot license, trial, or the free version. |
| 39 | + |
| 40 | + |
| 41 | +## Main takeaways |
| 42 | + |
| 43 | +### 1. Define Clear Objectives and Requirements |
| 44 | + |
| 45 | +*What needs to be achieved?* |
| 46 | + |
| 47 | +Start by understanding the end goal clearly. What is the result you're after? For migrating a project from one programming language to another, you must ensure a thorough testing strategy that can help you validate correctness and completion when making critical changes. |
| 48 | + |
| 49 | +*What are the constraints?* |
| 50 | + |
| 51 | +Identify limitations or exclusions. For example, large language models (LLMs) can have (or lack) enough context to provide the right suggestions. It is up to you, the driver, to make decisions that achieve your goal. Certain business logic might prevent you from adding other external libraries or functionality. For example, if you are migrating a project that is used in a production environment, you might not be able to add new libraries or functionality that could break the existing code. |
| 52 | + |
| 53 | +> [!TIP] |
| 54 | +> Focus on being precise with the scope of the problem. If you're unsure, start broad and then progressively narrow down the details. |
| 55 | +
|
| 56 | +### 2. Break Down the Problem into Components |
| 57 | + |
| 58 | +Decompose the migration process into smaller, manageable pieces. For example, start with the core application components and then test a single API endpoint or library function. This makes it easier to understand and solve the problem step-by-step: |
| 59 | + |
| 60 | +- Identify and migrate single public, exposed functions, or API endpoints from Python to Rust |
| 61 | +- Develop and run tests, set up test environments, and create validation scripts to ensure correctness |
| 62 | +- Handle configuration and installation processes for the new Rust environment |
| 63 | + |
| 64 | +Ensure you're applying each condition step-by-step. In programming, breaking down a complex function into smaller helper functions can make it easier to write, debug, and migrate. |
| 65 | + |
| 66 | +> [!TIP] |
| 67 | +> Decomposition is a great way to deal with complexity, as it allows you to focus on one small task at a time. |
| 68 | +
|
| 69 | +### 3. Leverage Domain-Specific Vocabulary and Context |
| 70 | + |
| 71 | +Use the appropriate terminology for the migration process. Whether you're translating Python code to Rust, working with APIs, or designing algorithms, being familiar with the domain vocabulary helps you form more accurate instructions for tools like GitHub Copilot or while communicating with others. |
| 72 | + |
| 73 | +For example, understanding terms like "borrow checker" in Rust or "decorators" in Python can help you better navigate the migration process and communicate effectively with others involved. |
| 74 | + |
| 75 | +> [!TIP] |
| 76 | +> The more precise the vocabulary and context you use, the easier it is for both humans and tools to understand and generate solutions. |
| 77 | +
|
| 78 | +### 4. Iterate and Refine the Solution |
| 79 | + |
| 80 | +Start simple, then refine. In complex problems, initial attempts are rarely perfect. Start by generating a basic solution and progressively build on it. |
| 81 | + |
| 82 | +In this workshop for migrating an application from Python to Rust, you might want to start with a single function or piece of functionality and then isolate it, while subsequently adding complexity. For example, begin by translating a simple Python function to Rust, then incrementally add more complex features and integrations. |
| 83 | + |
| 84 | +> [!TIP] |
| 85 | +> With every iteration, test and verify against expected outcomes to ensure the result is moving in the right direction. |
| 86 | +
|
| 87 | +### 5. Use Examples to Clarify Requirements |
| 88 | + |
| 89 | +When creating prompts for AI models or explaining problems, provide examples. An example can illustrate your expectations, making the task clearer for anyone or anything (including tools like GitHub Copilot) involved in solving the problem. |
| 90 | + |
| 91 | +For instance, with migration code, you could explain what the inputs and expected outputs can be while including the logic to accomplish the task. |
| 92 | + |
| 93 | +> [!TIP] |
| 94 | +> Example-driven problem-solving helps align understanding. It's especially useful for ambiguous tasks. |
| 95 | +### 6. Identify Patterns and Reuse Solutions |
| 96 | + |
| 97 | +Recognize common patterns in your migration process and reuse solutions where applicable. For example, when migrating from Python to Rust, you might notice recurring patterns such as handling data structures, managing memory, or implementing similar algorithms. Once you identify these patterns, you can reuse and adapt these building blocks for different parts of your project. |
| 98 | + |
| 99 | +In code migration, identifying reusable functions or logic can save time and reduce errors. For instance, if you have a common way of handling API requests in Python, you can create a similar reusable function in Rust. |
| 100 | + |
| 101 | +> [!TIP] |
| 102 | +> Recognizing patterns is a hallmark of experience. As you encounter similar migration challenges repeatedly, you'll start to see similarities that can speed up your process and improve consistency. |
| 103 | +
|
| 104 | +### 7. Use Constraints and Edge Cases for Robustness |
| 105 | + |
| 106 | +Think about edge cases and exceptions. Complex problems often involve handling not just the "ideal" data, but also the "edge" or "outlier" cases that might break a naive solution. Ensure that your prompt or solution accounts for these edge cases. |
| 107 | + |
| 108 | +In migration code, this might mean considering how the code behaves with unexpected inputs which would guide you to write new tests or modify existing ones. |
| 109 | + |
| 110 | +> [!TIP] |
| 111 | +> Thinking through edge cases helps you build more resilient, generalized solutions. |
| 112 | +
|
| 113 | +### 8. Use Tools Effectively |
| 114 | + |
| 115 | +Whether you’re using GitHub Copilot, your editor auto-completion, or another form of automation, leverage the tools at your disposal but make sure you're guiding them with the right context. Tools are great for speeding up the generation, but they still need well-structured inputs and validation from you. |
| 116 | + |
| 117 | +For GitHub Copilot, ensure that your prompts are detailed, but concise. Tools often work best when given structured input that leaves little ambiguity. |
| 118 | + |
| 119 | +> [!TIP] |
| 120 | +> Be specific with your tools, but also check results, as tools might not always fully understand context unless properly guided. |
| 121 | +
|
| 122 | +### 9. Seek Feedback and Collaboration |
| 123 | + |
| 124 | +When tackling a complex task, especially one that involves code or queries, collaboration and feedback are crucial. Don’t hesitate to ask peers or communities for insights or review. |
| 125 | + |
| 126 | +For example, when rewriting complex functions or code blocks, having a second pair of eyes can help catch mistakes or suggest improvements. This is especially true in migration projects where the original intent might not be clear. |
| 127 | + |
| 128 | +> [!TIP] |
| 129 | +> Collaboration often brings new perspectives, reducing blind spots. |
| 130 | +### 10. Test and Validate |
| 131 | + |
| 132 | +Testing and validation are key to ensuring that your solution works as expected. In the case of migrating code to another programming language, this is even more critical, as you want to ensure that the new code behaves similarly (or exactly the same) as the old code. |
| 133 | + |
| 134 | +Testing ensures that both the expected and unexpected situations are handled correctly, and that the migration has not introduced any new issues. |
| 135 | + |
| 136 | +> [!TIP] |
| 137 | +> Always have a validation step built into your process to catch mistakes early and ensure the migrated code meets all requirements. |
| 138 | +
|
| 139 | +Generalization for Other Use Cases: |
| 140 | +For writing code or algorithms: The same concepts apply when generating functions, classes, or workflows. Clearly define input, expected output, edge cases, and iterate to refine. |
| 141 | + |
| 142 | +For AI model prompts: When asking for something complex (like generating code, text, or designs), give clear objectives, break down the problem, provide context, and iterate. |
| 143 | + |
| 144 | +For design or content generation: Define the purpose, break down design elements, and provide examples or inspiration, then refine based on feedback. |
| 145 | + |
| 146 | +Final Thoughts: |
| 147 | +Complex generation problems often involve a balance of clarity, decomposition, iteration, and validation. Whether it's a migrating from one programming language to another or any other task, keeping these concepts in mind will allow you to generate more accurate, efficient, and reliable results. |
| 148 | + |
| 149 | +## :books: Resources |
| 150 | + |
| 151 | +Although not required, some of the features this workshop covers are in these Microsoft Learning modules: |
| 152 | + |
| 153 | +- [Code with GitHub Codespaces](https://learn.microsoft.com/training/modules/code-with-github-codespaces/) |
| 154 | +- [Using advanced GitHub Copilot features](https://learn.microsoft.com/training/modules/advanced-github-copilot/) |
| 155 | + |
| 156 | +## Contributing |
| 157 | + |
| 158 | +This project welcomes contributions and suggestions. Most contributions require you to agree to a |
| 159 | +Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us |
| 160 | +the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com. |
| 161 | + |
| 162 | +When you submit a pull request, a CLA bot will automatically determine whether you need to provide |
| 163 | +a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions |
| 164 | +provided by the bot. You will only need to do this once across all repos using our CLA. |
| 165 | + |
| 166 | +This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). |
| 167 | +For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or |
| 168 | +contact [[email protected]](mailto:[email protected]) with any additional questions or comments. |
| 169 | + |
| 170 | +## Trademarks |
| 171 | + |
| 172 | +This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft |
| 173 | +trademarks or logos is subject to and must follow |
| 174 | +[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general). |
| 175 | +Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. |
| 176 | +Any use of third-party trademarks or logos are subject to those third-party's policies. |
0 commit comments