|
| 1 | +<h1 align="center">Upgrading a Python project with GitHub Copilot</h1> |
| 2 | +<h5 align="center">Perform complex upgrades from legacy code to latest stable versions</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 upgrade scenarios for legacy code. |
| 11 | +- **What you'll learn**: You'll use advanced GitHub Copilot techniques that are specifically useful when upgrading projects. These techniques and patterns can be applied to upgrading and revamping projects as well as developing from scratch. |
| 12 | +- **What you'll build**: A full revamped Python project that used Python 2.5 using legacy and deprecated constructs into the latest version of Python 3 available. |
| 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-upgrading) |
| 18 | + |
| 19 | + |
| 20 | +[](https://codespaces.new/microsoft/github-copilot-upgrading) |
| 21 | + |
| 22 | +## Learning Objectives |
| 23 | + |
| 24 | +In this workshop, you will: |
| 25 | + |
| 26 | + - Use advanced GitHub Copilot interaction techniques to deal with a legacy project |
| 27 | + - Iterate, validate, and refine answers to upgrade the legacy project and validate its correctness |
| 28 | + - Apply generic concpets that can improve suggestions and select from different strategies that can yield better results. |
| 29 | + - Build a thorough testing strategy to help you identify potential issues and |
| 30 | + validate the project in its final state after upgrading. |
| 31 | + |
| 32 | +## :mega: Prerequisites |
| 33 | + |
| 34 | +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. |
| 35 | + |
| 36 | +## Main takeaways |
| 37 | + |
| 38 | +### 1. Define Clear Objectives and Requirements |
| 39 | + |
| 40 | +*What needs to be achieved?* |
| 41 | + |
| 42 | +Start by understanding the end goal clearly. What is the result you're after? For upgrading legacy projects, you must ensure a thorough testing strategy that can help you validate correctness and completion when making critical changes. |
| 43 | + |
| 44 | +*What are the constraints?* |
| 45 | + |
| 46 | +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 upgrading 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. |
| 47 | + |
| 48 | +> [!TIP] |
| 49 | +> Focus on being precise with the scope of the problem. If you're unsure, start broad and then progressively narrow down the details. |
| 50 | +
|
| 51 | +### 2. Break Down the Problem into Components |
| 52 | + |
| 53 | +Decompose the problem into smaller, manageable pieces. For exampple, 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: |
| 54 | + |
| 55 | +- Single Public, exposed functions, or API endpoints |
| 56 | +- Tests, test setup and validation scripts |
| 57 | +- Configuration and installation process |
| 58 | + |
| 59 | +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 and debug. |
| 60 | + |
| 61 | +> [!TIP] |
| 62 | +> Decomposition is a great way to deal with complexity, as it allows you to focus on one small task at a time. |
| 63 | +
|
| 64 | +### 3. Create slices of work |
| 65 | + |
| 66 | +A slice of work is a small, manageable piece of the overall problem. This is similar to breaking down the problem into components, but it focuses on the specific tasks that need to be completed. Think of this like a functional test that validates a specific feature or functionality. For example, if you're upgrading a legacy project, you might want to create a slice of work that focuses on upgrading a single library or function. |
| 67 | +This allows you to focus on one small task at a time, and it makes it easier to test and validate the changes. |
| 68 | + |
| 69 | +> [!TIP] |
| 70 | +> When creating slices of work, thing about the functional testing so that you have an easy way to test the changes. This can be as simple as creating a test script that validates the changes or creating a test suite that runs all the tests in the project. |
| 71 | +
|
| 72 | +### 4. Iterate and Refine the Solution |
| 73 | +Start simple, then refine. In complex problems, initial attempts are rarely perfect. Start by generating a basic solution and progressively build on it. |
| 74 | + |
| 75 | + |
| 76 | +> [!TIP] |
| 77 | +> With every iteration, test and verify against expected outcomes to ensure the result is moving in the right direction. |
| 78 | +
|
| 79 | +### 5. Use Examples to Clarify Requirements |
| 80 | +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. |
| 81 | + |
| 82 | +For instance, with legacy code, you could explain what the inputs and expected outputs can be while including the logic to accomplish the task |
| 83 | + |
| 84 | +> [!TIP] |
| 85 | +> Example-driven problem-solving helps align understanding. It's especially useful for ambiguous tasks. |
| 86 | +
|
| 87 | +### 6. Identify Patterns and Reuse Solutions |
| 88 | +Recognize common patterns in your problem and reuse solutions where applicable. An obvious example of this in legacy Python projects is the use of exception handling in Python 2.5 would create a `SyntaxError` in Python 3+. |
| 89 | + |
| 90 | +Sometimes in legacy projects it is common to create functions that handle either case, or even modules that can do imports depending on the Python version. This is a common pattern in legacy projects that can be reused in other projects. |
| 91 | + |
| 92 | +> [!TIP] |
| 93 | +> Recognizing patterns is a hallmark of experience. As you encounter similar problems repeatedly, you'll start to see similarities that can speed up your process. |
| 94 | +
|
| 95 | +### 7. Use Constraints and Edge Cases for Robustness |
| 96 | +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. |
| 97 | + |
| 98 | +In legacy code, this might mean considering how the code behaves with unexpected inputs which would guide you to write new tests or modify existing ones. |
| 99 | + |
| 100 | +> [!TIP] |
| 101 | +> Thinking through edge cases helps you build more resilient, generalized solutions. Always put an added emphasis in testing and creating a robust test suite to validate your changes. |
| 102 | +
|
| 103 | +### 8. Use Tools Effectively |
| 104 | +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. |
| 105 | + |
| 106 | +For GitHub Copilot, ensure that your prompts are detailed, but concise. Tools often work best when given structured input that leaves little ambiguity. |
| 107 | + |
| 108 | +> [!TIP] |
| 109 | +> Be specific with your tools, but also check results, as tools might not always fully understand context unless properly guided. |
| 110 | +
|
| 111 | + |
| 112 | +### 9. Test and Validate |
| 113 | +Testing and validation are key to ensuring that your solution works as expected. In the case of legacy code, this is even more critical, as you want to ensure that the new code behaves similarly (or exactly the same) to the old code. |
| 114 | + |
| 115 | +Testing ensures that both the expected and unexpected situations are handled correctly. |
| 116 | + |
| 117 | +> [!TIP] |
| 118 | +> Always have a validation step built into your process to catch mistakes early. |
| 119 | +
|
| 120 | +Generalization for Other Use Cases: |
| 121 | +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. |
| 122 | + |
| 123 | +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. |
| 124 | + |
| 125 | +For design or content generation: Define the purpose, break down design elements, and provide examples or inspiration, then refine based on feedback. |
| 126 | + |
| 127 | +Final Thoughts: |
| 128 | +Complex generation problems often involve a balance of clarity, decomposition, iteration, and validation. Whether it's a SQL query or any other task, keeping these concepts in mind will allow you to generate more accurate, efficient, and reliable results. |
| 129 | + |
| 130 | + |
| 131 | + |
| 132 | +## :books: Resources |
| 133 | + |
| 134 | +Although not required, some of the features this workshop covers are in these Microsoft Learning modules: |
| 135 | + |
| 136 | +- [Code with GitHub Codespaces](https://learn.microsoft.com/training/modules/code-with-github-codespaces/) |
| 137 | +- [Using advanced GitHub Copilot features](https://learn.microsoft.com/training/modules/advanced-github-copilot/) |
| 138 | + |
| 139 | +## Contributing |
| 140 | + |
| 141 | +This project welcomes contributions and suggestions. Most contributions require you to agree to a |
| 142 | +Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us |
| 143 | +the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com. |
| 144 | + |
| 145 | +When you submit a pull request, a CLA bot will automatically determine whether you need to provide |
| 146 | +a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions |
| 147 | +provided by the bot. You will only need to do this once across all repos using our CLA. |
| 148 | + |
| 149 | +This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). |
| 150 | +For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or |
| 151 | +contact [[email protected]](mailto:[email protected]) with any additional questions or comments. |
| 152 | + |
| 153 | +## Trademarks |
| 154 | + |
| 155 | +This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft |
| 156 | +trademarks or logos is subject to and must follow |
| 157 | +[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general). |
| 158 | +Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. |
| 159 | +Any use of third-party trademarks or logos are subject to those third-party's policies. |
0 commit comments