diff --git a/content/1-hour/0-setup.md b/content/1-hour/0-setup.md index 221e352..09504ce 100644 --- a/content/1-hour/0-setup.md +++ b/content/1-hour/0-setup.md @@ -1,86 +1,67 @@ # Workshop setup -| [← Getting started with GitHub Copilot][walkthrough-previous] | [Next: Coding with GitHub Copilot →][walkthrough-next] | -|:-----------------------------------|------------------------------------------:| +To complete this workshop you will need to clone a repository with a copy of the contents of this repository -To complete this workshop you will need to create a repository with a copy of the contents of this repository. While this can be done by [forking a repository][fork-repo], the goal of a fork is to eventually merge code back into the original (or upstream) source. In our case we want a separate copy as we don't intend to merge our changes. This is accomplished through the use of a [template repository][template-repo]. Template repositories are a great way to provide starters for your organization, ensuring consistency across projects. +> [!Hint] +> Under regular conditions you would need to ensure all requirements, but don't worry. We have ensured this environment has all you need. -The repository for this workshop is configured as a template, so we can use it to create your repository. +## Configure GitHub Copilot -> [!IMPORTANT] -> Ensure you have the [requisite software][required-software] and [requisite resources][required-resources] setup. +> [!NOTE] +> For your convenience we have the username and password on the instructions, but you can also see their values in the **Resources** tab -## Create your repository -Let's create the repository you'll use for your workshop. +1. [] Open Visual Studio Code +2. [] Click on Copilot icon on top bar (left side next to the search input box) -1. Navigate to [the repository root](/) -2. Select **Use this template** > **Create a new repository** +![Copilot icon](./images/0-copilot-icon.png) - ![Screenshot of Use this template dropdown](images/0-setup-template.png) +3. [] Click on **Open Chat** option (if you clicked on the dropdown arrow, otherwise the window is now open) +4. [] If there is a login button on the chat window, click it, otherwise type something and press enter in the chat input box to force the login window +5. [] Click on **Sign In** blue button on the modal window +6. [] A browser will automatically open, enter on the login input `user_events` (the password input will be greyed out once you enter the username) click on green **Sign in with your identity provider** button +7. [] Click **Continue** button on the **Single sign-on** page +8. [] Enter +++@lab.CloudPortalCredential(User1).Username+++ on the **Email, phone, or Skype** input box and click on **Next** +9. [] Enter +++@lab.CloudPortalCredential(User1).Password+++ on the password field and click on **Sign in with your entity provider** button +10. [] Authorize the user by clicking continue and authorize VS Code access to user email by clicking on **Authorize Visual-Studio-Code*** button +11. [] Click **open** when browser asks for the confirmation (**This site is trying to open Visual Studio Code.**) +12. [] After Copilot is setup you should now have a **Walkthrough: GitHub Copilot Chat** open tab in Visual Studio Code -3. Under **Owner**, select the name of your GitHub handle, or the owner specified by your workshop leader. -4. Under **Repository**, set the name to **pets-workshop**, or the name specified by your workshop leader. -5. Ensure **Public** is selected for the visibility, or the value indicated by your workshop leader. -6. Select **Create repository from template**. +We are now ready to start working on our code with the help of Copilot. - ![Screenshot of configured template creation dialog](images/0-setup-configure.png) +## Clone lab repository -In a few moments a new repository will be created from the template for this workshop! +Let's clone the repository you'll use for the lab. -## Clone the repository and start the app +1. [] Click on the Source Control icon on the left sidebar -With the repository created, it's now time to clone the repository locally. We'll do this from a shell capable of running BASH commands. +![Source control icon](./images/0-source-control-icon.png) -1. Copy the URL for the repository you just created in the prior set. -2. Open your terminal or command shell. -3. Run the following command to clone the repository locally (changing directories to a parent directory as appropriate): +2. [] Click on **Clone Repository** button +3. [] Type `https://github.com/github-samples/pets-workshop` and press enter. +4. [] Select the repository destination folder (suggestion: use the one is automatically shown. The user home folder) by clicking in **Select as Repository Destination** button. + - Note: The repository will be cloned to **SELECTED FOLDER/pets-workshop** +5. [] Click **Open** button when asked if you **Would like to open the cloned repository?** +6. [] Click the **Yes, I trust the authors** button when asked. - ```sh - git clone - ``` +The code is now opened in Visual Studio, feel free to take a look at it or skip to the next section to start the app. -4. Change directories into the cloned repository by running the following command: +## Start the app - ```sh - cd - ``` +1. [] On the menu bar at the top, Click on **...** (three dots, or **Terminal** if already visible) and then select **Terminal -> New Terminal** +2. [] Start the application by running the following command on the terminal: -5. Start the application by running the following command: +```pwsh +.\scripts\start-app.ps1 +``` - ```sh - ./scripts/start-app.sh - ``` +The startup script will install dependencies and start two applications: -The startup script will start two applications: +- The backend Flask app on **http://localhost:5100**. You can see a list of dogs by opening the url +++http://localhost:5100/api/dogs+++ +- The frontend Astro/Svelte app on +++http://localhost:4321+++. You can see app the by opening that URL. -- The backend Flask app on [localhost:5100][flask-url]. You can see a list of dogs by opening the [dogs API][dogs-api]. -- The frontend Astro/Svelte app on [localhost:4321][astro-url]. You can see the [website][website-url] by opening that URL. - -## Open your editor - -With the code cloned locally, and the site running, let's open the codebase up in VS Code. - -1. Open VS Code. -2. Select **File** > **Open Folder**. -3. Navigate to the folder which contains the project you cloned earlier in this exercise. -4. With the folder highlighted, select **Open folder**. +- [] Try it now, open a browser and navigate to the links provided above. ## Summary and next steps -You've now cloned the repository you'll use for this workshop and have your IDE setup! Next let's [add a new endpoint to the server][walkthrough-next]! - - -| [← Getting started with GitHub Copilot][walkthrough-previous] | [Next: Coding with GitHub Copilot →][walkthrough-next] | -|:-----------------------------------|------------------------------------------:| - -[astro-url]: http://localhost:4321 -[dogs-api]: http://localhost:5100/api/dogs -[flask-url]: http://localhost:5100 -[fork-repo]: https://docs.github.com/en/get-started/quickstart/fork-a-repo -[required-resources]: ./README.md#required-resources -[required-software]: ./README.md#required-local-installation -[template-repo]: https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository -[walkthrough-previous]: README.md -[walkthrough-next]: ./1-add-endpoint.md -[website-url]: http://localhost:4321 \ No newline at end of file +You've now cloned the repository you'll use for this workshop and have GitHub Copilot setup! Next let's **add a new endpoint to the server** diff --git a/content/1-hour/1-add-endpoint.md b/content/1-hour/1-add-endpoint.md index 84fbbaf..b7af36b 100644 --- a/content/1-hour/1-add-endpoint.md +++ b/content/1-hour/1-add-endpoint.md @@ -1,9 +1,5 @@ # Coding with GitHub Copilot -| [← Workshop setup][walkthrough-previous] | [Next: Helping GitHub Copilot understand context →][walkthrough-next] | -|:-----------------------------------|------------------------------------------:| - - With code completions, GitHub Copilot provides suggestions in your code editor while you're coding. This can turn comments into code, generate the next line of code, and generate an entire function just from a signature. Code completion helps reduce the amount of boilerplate code and ceremony you need to type, allowing you to focus on the important aspects of what you're creating. ## Scenario @@ -13,11 +9,11 @@ It's standard to work in phases when adding functionality to an application. Giv The application uses a Flask app with SQLAlchemy as the backend API (in the [/server][server-code] folder), and an Astro app with Svelte as the frontend (in the [/client][client-code] folder). You will explore more of the project later; this exercise will focus solely on the Flask application. > [!NOTE] -> As you begin making changes to the application, there is always a chance a breaking change could be created. If the page stops working, check the terminal window you used previously to start the application for any error messages. You can stop the app by using Ctl+C, and restart it by running `./scripts/start-app.sh`. +> As you begin making changes to the application, there is always a chance a breaking change could be created. If the page stops working, check the terminal window you used previously to start the application for any error messages. You can stop the app by using Control+C, and restart it by running `./scripts/start-app.ps1`. ## Flask routes -While we won't be able to provide a full overview of [routing in Flask][flask-routing], they are defined by using the Python decorator `@app.route`. There are a couple of parameters you can provide to `@app.route`, including the path (or URL) one would use to access the route (such as **api/breeds**), and the [HTTP method(s)][http-methods] which can be used. +While we won't be able to provide a full overview of [routing in Flask][flask-routing], they are defined by using the Python decorator **@app.route**. There are a couple of parameters you can provide to **@app.route**, including the path (or URL) one would use to access the route (such as **api/breeds**), and the [HTTP method(s)][http-methods] which can be used. ## Code completion @@ -32,22 +28,26 @@ Let's build our new route in our Flask backend with the help of code completion. > [!IMPORTANT] > For this exercise, **DO NOT** copy and paste the code snippet provided, but rather type it manually. This will allow you to experience code completion as you would if you were coding back at your desk. You'll likely see you only have to type a few characters before GitHub Copilot begins suggesting the rest. -1. Return to your IDE with the project open. -2. Open **server/app.py**. -3. Locate the comment which reads `## HERE`, which should be at line 68. -4. Delete the comment to ensure there isn't any confusion for Copilot, and leave your cursor there. -5. Begin adding the code to create the route to return all breeds from an endpoint of **api/breeds** by typing the following: +1. [] Return to Visual Studio Code. +2. [] Open **server/app.py** file. +3. [] Locate the comment which reads **## HERE**, which should be at line 68. +4. [] Delete the comment to ensure there isn't any confusion for Copilot, and leave your cursor there. +5. [] Begin adding the code to create the route to return all breeds from an endpoint of **api/breeds** by typing the following: - ```python + ```python-nocopy @app.route('/api/breeds', methods=['GET']) ``` -6. Once you see the full function signature, select Tab to accept the code suggestion. -7. If it didn't already, code completion should then suggest the remainder of the function signature; just as before select Tab to accept the code suggestion. +6. [] Once you see the full function signature, select Tab to accept the code suggestion. + +> [!Hint] +> You can also use control+Right Arrow to accept a single word at a time. + +7. [] If it didn't already, code completion should then suggest the remainder of the function signature; just as before select Tab to accept the code suggestion. The code generated should look a little like this: - ```python + ```python-nocopy @app.route('/api/breeds', methods=['GET']) def get_breeds(): # Query all breeds @@ -68,15 +68,25 @@ Let's build our new route in our Flask backend with the help of code completion. > [!IMPORTANT] > Because LLMs are probabilistic, not deterministic, the exact code generated can vary. The above is a representative example. If your code is different, that's just fine as long as it works! -8. Add a comment to the newly created function. To do this, place your cursor inside the function (anywhere between the lines `def get_breeds...` and `return jsonify...`). Then, press Ctl+I (or cmd+I on a Mac) to open the editor inline chat. In the input box, type `/doc`. (You can optionally provide additional details, but it's not required). This will prompt GitHub Copilot to generate a documentation comment for the function. The suggested comment will appear inline in the code (highlighted in green). Click **Accept** to apply the comment to your code, or click **Close** to discard the suggestion. You just used a slash command, a shortcut to streamline a task, these commands eliminate the need for verbose prompts. +8. [] Let's add a comment to the newly created function. To do this, place your cursor inside the function (anywhere between the lines **def get_breeds...** and **return jsonify...**). Then, press Control+I to open the editor inline chat. +In the input box, type **/doc**. (You can optionally provide additional details, but it's not required). This will prompt GitHub Copilot to generate a documentation comment for the function. The suggested comment will appear inline in the code (highlighted in green). Click **Accept** to apply the comment to your code, or click **Close** to discard the suggestion. + +> [!TIP] +> You just used a slash command, a shortcut to streamline a task, these commands eliminate the need for verbose prompts. +> ![doc slash command](images/1-doc-slash-command-suggestion.png) -9. **Save** the file. +9. [] **Save** the file. ## Validate the endpoint With the code created and saved, let's quickly validate the endpoint to ensure it works. -1. Navigate to [http://localhost:5100/api/breeds][breeds-endpoint] to validate the route. You should see JSON displayed which contains the list of breeds! +1. [] Navigate to +++http://localhost:5100/api/breeds+++ on the browser to validate the new route. You should see JSON displayed which contains the list of breeds! +2. [] Let's commit the changes locally, click on the Source control icon on the left sidebar +3. [] Click on the **+** icon to stage **server/app.py** +4. [] On the commit message box click on the icon with two stars, Copilot is going to create the commit message for you +5. [] Click on the **Commit** blue button to commit locally if you are happy with the commit message, otherwise adjust the message before committing. + - Don't try to push the changes (by pushing or synching), you do not have write permissions on the repository. ## Summary and next steps @@ -87,20 +97,12 @@ You've added a new endpoint with the help of GitHub Copilot! You saw how Copilot - [Code suggestions in your IDE with GitHub Copilot][copilot-suggestions] - [Code completions with GitHub Copilot in VS Code][vscode-copilot] - [Prompt crafting][prompt-crafting] -- [Inline chat][inline-chat] - -| [← Workshop setup][walkthrough-previous] | [Next: Helping GitHub Copilot understand context →][walkthrough-next] | -|:-----------------------------------|------------------------------------------:| -[breeds-endpoint]: http://localhost:5100/api/breeds [client-code]: /client/ [copilot-suggestions]: https://docs.github.com/en/copilot/using-github-copilot/getting-code-suggestions-in-your-ide-with-github-copilot [flask-routing]: https://flask.palletsprojects.com/en/stable/quickstart/#routing [http-methods]: https://www.w3schools.com/tags/ref_httpmethods.asp [prompt-crafting]: https://code.visualstudio.com/docs/copilot/prompt-crafting -[inline-chat]: https://code.visualstudio.com/docs/copilot/chat/inline-chat [server-code]: /server/ [vscode-copilot]: https://code.visualstudio.com/docs/copilot/ai-powered-suggestions -[walkthrough-previous]: ./0-setup.md -[walkthrough-next]: ./2-explore-project.md \ No newline at end of file diff --git a/content/1-hour/2-explore-project.md b/content/1-hour/2-explore-project.md index 5e73d18..d5ca225 100644 --- a/content/1-hour/2-explore-project.md +++ b/content/1-hour/2-explore-project.md @@ -1,8 +1,5 @@ # Helping GitHub Copilot understand context -| [← Coding with GitHub Copilot][walkthrough-previous] | [Next: Providing custom instructions →][walkthrough-next] | -|:-----------------------------------|------------------------------------------:| - The key to success when coding (and much of life) is context. Before we add code to a codebase, we want to understand the rules and structures already in place. When working with an AI coding assistant such as GitHub Copilot the same concept applies - the quality of suggestion is directly proportional to the context Copilot has. Let's use this opportunity to both explore the project we've been given and how to interact with Copilot to ensure it has the context it needs to do its best work. ## Scenario @@ -11,25 +8,35 @@ Before adding new functionality to the website, you want to explore the existing ## Chat participants and extensions -GitHub Copilot Chat has a set of available [chat participants][chat-participants] and [extensions][copilot-extensions] available to you to both provide instructions to GitHub Copilot and access external services. Chat participants are helpers which work inside your IDE and have access to your project, while extensions can call external services and provide information to you without having to open separate tools. We're going to focus on one core chat participant - `@workspace`. +GitHub Copilot Chat has a set of available [chat participants][chat-participants] and [extensions][copilot-extensions] available to you to both provide instructions to GitHub Copilot and access external services. Chat participants are helpers which work inside your IDE and have access to your project, while extensions can call external services and provide information to you without having to open separate tools. We're going to focus on one core chat participant - **@workspace**. -`@workspace` creates an index of your project and allows you to ask questions about what you're currently working on, to find resources inside the project, or add it to the context. It's best to use this when the entirety of your project should be considered or you're not entirely sure where you should start looking. In our current scenario, since we want to ask questions about our project, `@workspace` is the perfect tool for the job. +**@workspace** creates an index of your project and allows you to ask questions about what you're currently working on, to find resources inside the project, or add it to the context. It's best to use this when the entirety of your project should be considered or you're not entirely sure where you should start looking. In our current scenario, since we want to ask questions about our project, **@workspace** is the perfect tool for the job. > [!NOTE] > This exercise doesn't provide specific prompts to type, as part of the learning experience is to discover how to interact with Copilot. Feel free to talk in natural language, describing what you're looking for or need to accomplish. -1. Return to your IDE with the project open. -2. Close any tabs you may have open in your IDE to ensure the context for Copilot chat is empty. -3. Open GitHub Copilot Chat. -4. Select the `+` icon towards the top of Copilot chat to begin a new chat. -5. Type `@workspace` in the chat prompt window and hit tab to select or activate it, then continue by asking Copilot about your project. You can ask what technologies are in use, what the project does, where functionality resides, etc. -6. Spend a few minutes exploring to find the answers to the following questions: +1. [] Return Visual Studio Code with the project open. +2. [] Close any tabs you may have open to ensure the context for Copilot chat is empty. +3. [] Open GitHub Copilot Chat. + +> [!Hint] +> You can open Chat by clicking on GitHub Copilot icon at the top bar and then choose **Open Chat** or use Control+Alt+I + +4. [] Select the **+** icon towards the top of Copilot chat to begin a new chat. +5. [] Type `@workspace` in the chat prompt window and hit tab to select or activate it, then continue by asking Copilot about your project. You can ask what technologies are in use, what the project does, where functionality resides, etc. + +> [!NOTE] +> You may be asked to authenticate again, if that happens follow the process you have followed before (this time you won't need to enter the credentials). + +6. [] Spend a few minutes exploring to find the answers to the following questions (don't forget the **@workspace**): - Where's the database the project uses? - What files are involved in listing dogs? +> [!Knowledge] Did you notice that when files are referenced, there's an icon in front of the name? If you click on it, it will open the file in the editor. Those files are part of the prompt Context. + ## Summary and next steps -You've explored context in GitHub Copilot, which is key to generating quality suggestions. You saw how you can use chat participants to help guide GitHub Copilot, and how with natural language you can explore the project. Let's see how we can provide even more context to Copilot chat through the use of [Copilot instructions][walkthrough-next]. +You've explored context in GitHub Copilot, which is key to generating quality suggestions. You saw how you can use chat participants to help guide GitHub Copilot, and how with natural language you can explore the project. Let's see how we can provide even more context to Copilot chat through the use of **Copilot instructions**. ## Resources @@ -37,13 +44,8 @@ You've explored context in GitHub Copilot, which is key to generating quality su - [Use Copilot Chat in VS Code][copilot-chat-vscode] - [Copilot extensions marketplace][copilot-marketplace] -| [← Coding with GitHub Copilot][walkthrough-previous] | [Next: Providing custom instructions →][walkthrough-next] | -|:-----------------------------------|------------------------------------------:| - [chat-participants]: https://code.visualstudio.com/docs/copilot/copilot-chat#_chat-participants [copilot-chat-vscode]: https://code.visualstudio.com/docs/copilot/copilot-chat [copilot-cookbook]: https://docs.github.com/en/copilot/copilot-chat-cookbook [copilot-extensions]: https://docs.github.com/en/copilot/using-github-copilot/using-extensions-to-integrate-external-tools-with-copilot-chat [copilot-marketplace]: https://github.com/marketplace?type=apps&copilot_app=true -[walkthrough-previous]: ./1-add-endpoint.md -[walkthrough-next]: ./3-copilot-instructions.md \ No newline at end of file diff --git a/content/1-hour/3-copilot-instructions.md b/content/1-hour/3-copilot-instructions.md index b9b07ff..25035bd 100644 --- a/content/1-hour/3-copilot-instructions.md +++ b/content/1-hour/3-copilot-instructions.md @@ -1,8 +1,5 @@ # Providing custom instructions -| [← Coding with GitHub Copilot][walkthrough-previous] | [Next: Add the filter feature →][walkthrough-next] | -|:-----------------------------------|------------------------------------------:| - There are always key pieces of information anyone generating code for your codebase needs to know - the technologies in use, coding standards to follow, project structure, etc. Since context is so important, as we've discussed, we likely want to ensure Copilot always has this information as well. Fortunately, we can provide this overview through the use of Copilot instructions. ## Scenario @@ -11,7 +8,7 @@ Before we begin larger updates to the site with the help of Copilot, we want to ## Overview of Copilot instructions -Copilot instructions is a markdown file is placed in your **.github** folder. It becomes part of your project, and in turn to all contributors to your codebase. You can use this file to indicate various coding standards you wish to follow, the technologies your project uses, or anything else important for Copilot Chat to understand when generating suggestions. +Copilot instructions is a markdown file is placed in your **.github** folder. It becomes part of your project, and in turn is available to all contributors to your codebase. You can use this file to indicate various coding standards you wish to follow, the technologies your project uses, or anything else important for Copilot Chat to understand when generating suggestions. > [!IMPORTANT] > The *copilot-instructions.md* file is included in **every** call to GitHub Copilot Chat, and will be part of the context sent to Copilot. Because there is always a limited set of tokens an LLM can operate on, a large Copilot instructions file can obscure relevant information. As such, you should limit your Copilot instructions file to project-wide information, providing an overview of what you're building and how you're building it. If you need to provide more specific information for particular tasks, you can create [prompt files](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot?tool=vscode#about-prompt-files). @@ -20,34 +17,34 @@ Here are some guidelines to consider when creating a Copilot instructions file: - The Copilot instructions file becomes part of the project, meaning it will apply to every developer; anything indicated in the file should be globally applicable. - The file is markdown, so you can take advantage of that fact by grouping content together to improve readability. -- Provide overview of **what** you are building and **how** you are building it, including: +- Provide an overview of **what** you are building and **how** you are building it, including: - languages, frameworks and libraries in use. - required assets to be generated (such as unit tests) and where they should be placed. - any language specific rules such as: - utilize [type hints][type-hints] in Python. - - use [arrow functions][arrow-functions] rather than the `function` keyword in TypeScript. + - use [arrow functions][arrow-functions] rather than the **function** keyword in TypeScript. - If you notice GitHub Copilot consistently provides an unexpected suggestion (e.g. using class components for React), add those notes to the instructions file. ## Create a Copilot instructions file Let's create a Copilot instructions file. We'll start by asking Copilot to generate a block of code, then add the instructions file, then ask the same question again to see the changes. -1. Return to your IDE with your project open. -2. Close any tabs you may have open in your IDE to ensure Copilot chat has an empty context. -3. Select the `+` icon towards the top of Copilot chat to begin a new chat. -4. Open Copilot Chat and send the following prompt: +1. [] Return to Visual Studio Code. +2. [] Close any tabs you may have open in your VS Code to ensure Copilot chat has an empty context. +3. [] Select the **+** icon towards the top of Copilot chat to begin a new chat. +4. [] Open Copilot Chat and send the following prompt: ``` Create a Python function to validate dog age. Ensure age is between 0 and 20. Throw an error if it is outside this range. ``` -5. Note the function signature is similar to `def validate_dog_age(age)` without type hints. +5. [] Note the function signature is similar to **def validate_dog_age(age)** without type hints. > [!NOTE] > Because LLMs are probabilistic rather than deterministic, the exact code will vary. -6. Create a new file in the **.github** folder called **copilot-instructions.md**. -7. Add the markdown to the file necessary which provides information about the project structure and requirements: +6. [] Create a new file in the **.github** folder called **copilot-instructions.md**. +7. [] Add the following markdown to the file, which provides information about the project structure and requirements: ```markdown # Dog shelter @@ -66,15 +63,15 @@ Let's create a Copilot instructions file. We'll start by asking Copilot to gener - Pages should be in dark mode with a modern look and feel ``` -8. **Save** the file. +8. [] **Save** the file. ## Watch the instructions file in action Whenever you make a call to Copilot chat, the references dialog indicates all files used to generate the response. Once you create a Copilot instructions file, you will see it's always included in the references section. Since you included directions to use type hints, you'll notice the code suggestions will follow this guidance. -1. Close all files currently open in VS Code or your Codespace. (This will ensure we are working with an empty context.) -2. Select the `+` icon in GitHub Copilot chat to start a new chat. -3. Send Copilot chat the same prompt you used previously: +1. [] Close all files currently open in VS Code or your Codespace. (This will ensure we are working with an empty context.) +2. [] Select the **+** icon in GitHub Copilot chat to start a new chat. +3. [] Send Copilot chat the same prompt you used previously: ``` Create a Python function to validate dog age. Ensure age is between 0 and 20. Throw an error if it is outside this range. @@ -83,13 +80,13 @@ Whenever you make a call to Copilot chat, the references dialog indicates all fi > [!TIP] > You can use up arrow to resend previous prompts to Copilot chat. -4. Note the references now includes the instructions file and provides information gathered from it. +4. [] Note the references now includes the instructions file and provides information gathered from it. ![Screenshot of the chat window with the references section expanded displaying Copilot instructions in the list](./images/copilot-chat-references.png) -5. Note the resulting Python now utilizes type hints, and the function signature will resemble the following: +5. [] Note the resulting Python now utilizes type hints, and the function signature will resemble the following: - ```python + ```python-nocopy def validate_dog_age(age: int): ``` @@ -98,18 +95,12 @@ Whenever you make a call to Copilot chat, the references dialog indicates all fi ## Summary and next steps -Copilot instructions improves the quality of suggestions, and ensures better alignment with the desired practices you have in place. With the groundwork in place, let's [add new functionality to our website][walkthrough-next]! +Copilot instructions improves the quality of suggestions, and ensures better alignment with the desired practices you have in place. With the groundwork in place, let's **add new functionality to our website** ## Resources - [Adding repository custom instructions for GitHub Copilot][custom-instructions] - -| [← Coding with GitHub Copilot][walkthrough-previous] | [Next: Add the filter feature →][walkthrough-next] | -|:-----------------------------------|------------------------------------------:| - [arrow-functions]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions [custom-instructions]: https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot [type-hints]: https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html -[walkthrough-previous]: ./2-explore-project.md -[walkthrough-next]: ./4-add-feature.md \ No newline at end of file diff --git a/content/1-hour/4-add-feature.md b/content/1-hour/4-add-feature.md index 52e3efc..799595c 100644 --- a/content/1-hour/4-add-feature.md +++ b/content/1-hour/4-add-feature.md @@ -1,13 +1,12 @@ # Add the filter feature -| [← Providing custom instructions][walkthrough-previous] | [Next: Bonus content →][walkthrough-next] | -|:-----------------------------------|------------------------------------------:| - We've explored how we can use GitHub Copilot to explore our project and to provide context to ensure the suggestions we receive are to the quality we expect. Now let's turn our attention to putting all this prep work into action by generating new code! We'll use GitHub Copilot to aid us in adding functionality to our website. ## Scenario -The website currently lists all dogs in the database. While this was appropriate when the shelter only had a few dogs, as time has gone on the number has grown and it's difficult for people to sift through who's available to adopt. The shelter has asked you to add filters to the website to allow a user to select a breed of dog and only display dogs which are available for adoption. +The website currently lists all dogs in the database. While this was appropriate when the shelter only had a few dogs, as time has gone on the number has grown and it's difficult for people to sift through who's available to adopt. + +The shelter has asked you to add filters to the website to allow a user to select a breed of dog and only display dogs which are available for adoption. ## Copilot Edits @@ -22,17 +21,21 @@ Adding the filters to the page will require updating a minimum of two files - th > [!NOTE] > Because Copilot Edits works best with auto-save enabled, we'll activate it. As we'll explore a little later in this exercise, Copilot Edits provides powerful tools to undo any changes you might not wish to keep. -1. Return to your IDE with your project open. -2. Close any tabs you have open inside your IDE. -3. Enable Auto Save by selecting **File** > **Auto Save**. -4. Open GitHub Copilot Chat. -5. Switch to edit mode by selecting **Edit** in the chat mode dropdown at the bottom of Chat view (should be currently **Ask**) -6. If available, select **Claude 3.5 Sonnet** from the list of available models -7. Select **Add Context...** in the chat window. -8. Select **server/app.py** and **client/src/components/DogList.svelte** files (you need to select **Add context** for each file) +1. [] Return to Visual Studio Code. +2. [] Close any tabs you may have open in your VS Code to ensure Copilot chat has an empty context. +3. [] Enable Auto Save by selecting **File** > **Auto Save**. (top left menu) +4. [] Open or switch to GitHub Copilot Chat. +5. [] Switch to edit mode by selecting **Edit** in the chat mode dropdown at the bottom of Chat view (should be currently **Ask**) + - If asked **Changing the chat mode mode will end your current session. Would you like to continue?** click **Yes** + - If you were already on Copilot Edit mode, press **+** to start a new chat. +6. [] If available, select **Claude 3.5 Sonnet** from the list of available models +7. [] Click **Add Context...** in the chat window. +8. [] Select **server/app.py** and **client/src/components/DogList.svelte** files (you need to select **Add context** for each file) + > [!TIP] -> If you type the file names after clicking **Add context**, they will show up in the filter. You can also drag the files or right click file in explorer and select `Copilot -> Add File to Chat`) -9. Ask Copilot to generate the update you want to the page, which is to add filters for both dog breed and if dogs are available for adoption. Use your own phrasing, ensuring the following requirements are met: +> If you type the file names after clicking **Add context**, they will show up in the filter. You can also drag the files or right click file in explorer and select **Copilot -> Add File to Chat**) + +9. [] Ask Copilot to generate the update you want to the page, which is to add filters for both dog breed and if dogs are available for adoption. Use your own phrasing, ensuring the following requirements are met: - A dropdown list should be provided with all breeds - A checkbox should be available to only show available dogs - The page should automatically refresh whenever a change is made @@ -40,6 +43,9 @@ Adding the filters to the page will require updating a minimum of two files - th > [!NOTE] > You should use your own phrasing when generating the prompt. As highlighted previously, part of the exercise is to become comfortable creating prompts for GitHub Copilot. One key tip is it's always good to provide more guidance to ensure you get the code you are looking for. +> [!NOTE] +> If you are asked to **Enable Claude 3.5 Sonnet for all clients** click on **Enable** button. + Copilot begins generating the suggestions! ## Reviewing the suggestions @@ -63,41 +69,58 @@ You can also keep or undo all changes made. And -1. Review the code suggestions to ensure they behave the way you expect them to, making any necessary changes. Once you're satisfied, you can select **Keep** on the files individually or in Copilot Chat to accept all changes. -2. Open the page at [http://localhost:4321][tailspin-shelter-website] to see the updates! -3. Run the Python tests by using `python -m unittest` in the terminal as you did previously. -4. If any changes are needed, explain the required updates to GitHub Copilot and allow it to generate the new code. +1. [] Review the code suggestions to ensure they behave the way you expect them to, making any necessary changes. Once you're satisfied, you can select **Keep** on the files individually or in Copilot Chat to accept all changes. +2. [] Open the page at +++http://localhost:4321+++ to see the updates! +3. [] Run the Python tests by running the following commands (you might want to open a new terminal) + - `./venv/Scripts/Activate.ps1` + - `python -m unittest discover -s server` ensure all tests pass (3 tests should pass) +4. [] If any changes are needed, explain the required updates to GitHub Copilot and allow it to generate the new code. > [!IMPORTANT] > Working iteratively a normal aspect of coding with an AI pair programmer. You can always provide more context to ensure Copilot understands, make additional requests, or rephrase your original prompts. To aid you in working iteratively, you will notice undo and redo buttons towards the top of the Copilot Edits interface, which allow you to move back and forth across prompts. > > ![Screenshot of the undo/redo buttons](./images/copilot-edits-history.png) -5. Confirm the functionality works as expected, then select **Keep** to accept all the changes. +5. [] Confirm the functionality works as expected, then select **Keep** to accept all the changes. 6. Optional: Disable Auto Save by unselecting **File** > **Auto Save**. +> [!HINT] +> If you are stuck or just want to see alternatives way of prompting we have provided two prompts +> A [simple one](https://github.com/github-samples/pets-workshop/tree/msbuild-25/content/prompts/add-feature-simple.md), that is simple, with some ambiguity that leaves some space for interpretation but it gets the job done. Another one which is more [verbose](https://github.com/github-samples/pets-workshop/tree/msbuild-25/content/prompts/add-feature-verbose.md) and leaves not a lot of space for interpretation. +> Take a look at the differences and see which one you like better. + ## Summary You've worked with GitHub Copilot to add new features to the website - the ability to filter the list of dogs. With the help of Copilot Edits, you updated multiple files across the project, and iteratively built the desired functionality. ## Workshop review -Over the course of the workshop you explore the core functionality of GitHub Copilot. You saw how to use code completion to get inline suggestions, chat participants to explore your project, Copilot instructions to add context, and Copilot Edits to update multiple files. +Over the course of the workshop you explored the core functionality of GitHub Copilot. You saw how to use code completion to get inline suggestions, chat participants to explore your project, Copilot instructions to add context, and Copilot Edits to update multiple files. But there is a lot more in GitHub Copilot (just to name a few): +- [Agent mode][copilot-agent] +- [MCP Servers support][MCP-server] +- [Extend Copilot][Extensibility-VS-Code] +- Copilot features available in GitHub + - [GitHub Copilot code review][code-review] + - [Extensions][copilot-extensions] + - [Answers about issues, PRs, discussions, files, commits, etc][asking-github-copilot-questions] There is no one right way to use GitHub Copilot. Continue to explore and try different prompts to discover what works best for your workflow and how GitHub Copilot can aid your productivity. +We have a bonus section for you, if you want to continue your explorations. + ## Resources - [Asking GitHub Copilot questions in your IDE][copilot-ask] - [Copilot Chat cookbook][copilot-cookbook] - [Copilot Edits][copilot-edits] - -| [← Providing custom instructions][walkthrough-previous] | [Next: Bonus content →][walkthrough-next] | -|:-----------------------------------|------------------------------------------:| +- [Copilo Agent][copilot-agent] [copilot-ask]: https://docs.github.com/en/copilot/using-github-copilot/copilot-chat/asking-github-copilot-questions-in-your-ide [copilot-cookbook]: https://docs.github.com/en/copilot/copilot-chat-cookbook [copilot-edits]: https://code.visualstudio.com/docs/copilot/copilot-edits -[tailspin-shelter-website]: http://localhost:4321 -[walkthrough-previous]: ./3-copilot-instructions.md -[walkthrough-next]: ./5-bonus.md +[copilot-agent]: https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode +[MCP-server]: https://code.visualstudio.com/docs/copilot/chat/mcp-servers +[Extensibility-VS-Code]: https://code.visualstudio.com/docs/copilot/copilot-extensibility-overview +[code-review]: https://docs.github.com/en/copilot/using-github-copilot/code-review/using-copilot-code-review?tool=webui +[copilot-extensions]: https://github.com/features/copilot/extensions +[asking-github-copilot-questions]: https://docs.github.com/en/enterprise-cloud@latest/copilot/using-github-copilot/copilot-chat/asking-github-copilot-questions-in-github diff --git a/content/1-hour/5-bonus.md b/content/1-hour/5-bonus.md index 5492e84..bc2e7b2 100644 --- a/content/1-hour/5-bonus.md +++ b/content/1-hour/5-bonus.md @@ -1,7 +1,54 @@ # Bonus content -| [← Add the filter feature][walkthrough-previous] | [Next: Pets workshop selection →][walkthrough-next] | -|:-----------------------------------|------------------------------------------:| + +## Overview of Copilot Agent Mode + +With chat agent mode in Visual Studio Code, you can use natural language to define a high-level task and to start an agentic code editing session to accomplish that task. In agent mode, Copilot **autonomously** plans the work needed and determines the relevant files and context. It then makes edits to your codebase and invokes tools to accomplish the request you made. Agent mode monitors the outcome of edits and tools and iterates to resolve any issues that arise. + +> [!IMPORTANT] +> While Copilot autonomously determines the operations necessary to complete the requested task, as the developer you are always in charge. You will work with Copilot to ensure everything is completely correctly, reading and reviewing the code. You will also want to continue to follow proper DevOps practices, including code reviews, testing, security scans, etc. + +Why would you use agent mode instead of edit mode? + +- **Edit scope**: agent mode autonomously determines the relevant context and files to edit. In edit mode, you need to specify the context yourself. +- **Task complexity**: agent mode is better suited for complex tasks that require not only code edits but also the invocation of tools and terminal commands. +- **Duration**: agent mode involves multiple steps to process a request, so it might take longer to get a response. For example, to determine the relevant context and files to edit, determine the plan of action, and more. +- **Self-healing**: agent mode evaluates the outcome of the generated edits and might iterate multiple times to resolve intermediate issues. +- **Request quota**: in agent mode, depending on the complexity of the task, one prompt might result in many requests to the backend. + +### How it works + +![How agent mode works](./images/copilot-agent-mode-how-it-works.png) + +## Add themes to the Tailspin Shelter website + +In this section, you will use Copilot's agent mode to add themes to the Tailspin Shelter website. You will be able to select a theme and apply it to the website. + +1. [] Return to Visual Studio Code. +2. [] Close any tabs you may have open in your VS Code to ensure Copilot chat has an empty context. +3. [] Select the **+** icon towards the top of Copilot chat to begin a new chat. +4. [] Select agent mode, by selecting **Agent** (just like you did **Edit** before) in the model selector dropdown at the bottom of the chat window. +5. [] Select one of models (some may not be available) **Claude 3.5 Sonnet**, **Claude 3.7 Sonnet** or **GPT-4.1** +6. [] Open the `content/prompts/fun-add-themes.md` file +7. [] Copy the content of the prompt +8. [] Paste the content in the copilot prompt input +9. The agent mode will take it's time, since it searches by itself the relevant files to modify, and then does multiple passes including talking with himself to refine the task at hand +10. [] While Agent is doing it's thing, take the opportunity to examine the content of prompt that was used. +11. [] When the agent is done (you no longer see any spinners and the thumb up/down icons will be visible), examine the prompt response + open a browser to see the results + - Open the page at ++http://localhost:4321++ to see the updates! + - Examine the changes made to the files if you like + - Was it good? If you are not happy with the results, you can refine the prompt by crafting extra prompts in the chat to improve the end results. Don't start a new session, it's an interactive process. + +You _may_ have gotten something like this for the Terminal Theme (generated with claude 3.7) + +![Tailspin Shelter Terminal Classic theme](images/tail-spin-shelter-terminal-theme.png) + +> [!IMPORTANT] +> Because LLMs are probabilistic, not deterministic, the exact code generated can vary. The above is a representative example. If your code is different, that's just fine as long as it works! + + +## Play a bit with Copilot You've made it to the end of the one hour workshop. Congratulations! You've explored the core skills to help you get the most out of GitHub Copilot. From here you can explore various challenges on your own, and see how GitHub Copilot can support you as you continue developing. @@ -14,12 +61,22 @@ You'll also notice there aren't step-by-step instructions here. You've already s Here's some ideas of how you could continue to grow and build upon what you've done: - Return to the API endpoints you updated previously in Flask and add unit tests. + +> [!Knowledge] +> The **/tests** slash command can give you a little hand or you can also do it edit mode. + - Add paging support to the full list of dogs or any results page with more than 5 results. - Add a form to allow a user to apply to adopt a dog if the dog is available. - Add a form to allow users to register a dog they found. -| [← Add the filter feature][walkthrough-previous] | [Next: Pets workshop selection →][walkthrough-next] | -|:-----------------------------------|------------------------------------------:| +We have provided you some prompts in [prompts][github-prompts-path] folder, which you can use directly as inspiration for your explorations. + +> [!TIP] +> These prompts are meant to be used as one shot, but if have prompts that can be are generic, reusable prompt are a great way to share prompts with the team members. They can be placed in a well know folder and be invoked directly in the Copilot Chat by referencing them. +> Learn more about [reusable prompts in Visual Studio Code][vscode-prompts] +> [!Knowledge] To use a prompt, select **Add Context..** in the chat and then select **Prompt** +> Learn more about [prompts in Visual Studio Code][vscode-prompts] + -[walkthrough-previous]: ./4-add-feature.md -[walkthrough-next]: ../README.md +[vscode-prompts]: https://aka.ms/vscode-ghcp-prompt-snippets +[github-prompts-path: https://github.com/github-samples/pets-workshop/tree/msbuild-25/content/prompts/ \ No newline at end of file diff --git a/content/1-hour/images/0-copilot-icon.png b/content/1-hour/images/0-copilot-icon.png new file mode 100644 index 0000000..dd8a1b2 Binary files /dev/null and b/content/1-hour/images/0-copilot-icon.png differ diff --git a/content/1-hour/images/0-source-control-icon.png b/content/1-hour/images/0-source-control-icon.png new file mode 100644 index 0000000..3729dfd Binary files /dev/null and b/content/1-hour/images/0-source-control-icon.png differ diff --git a/content/1-hour/images/1-doc-slash-command-suggestion.png b/content/1-hour/images/1-doc-slash-command-suggestion.png new file mode 100644 index 0000000..bd7df4b Binary files /dev/null and b/content/1-hour/images/1-doc-slash-command-suggestion.png differ diff --git a/content/1-hour/images/copilot-agent-mode-how-it-works.png b/content/1-hour/images/copilot-agent-mode-how-it-works.png new file mode 100644 index 0000000..7992c7a Binary files /dev/null and b/content/1-hour/images/copilot-agent-mode-how-it-works.png differ diff --git a/content/1-hour/images/tail-spin-shelter-terminal-theme.png b/content/1-hour/images/tail-spin-shelter-terminal-theme.png new file mode 100644 index 0000000..dc7e5ff Binary files /dev/null and b/content/1-hour/images/tail-spin-shelter-terminal-theme.png differ diff --git a/content/prompts/README.md b/content/prompts/README.md new file mode 100644 index 0000000..83f3db0 --- /dev/null +++ b/content/prompts/README.md @@ -0,0 +1,17 @@ +# Pets Workshop Prompts + +This directory contains various prompts designed for different aspects of development and enhancement of the Pets Workshop project. These prompts are meant for illustration purposes only. + +## Prompt Overview + +### Interface and User Experience + +- **[fun-add-themes](./fun-add-themes.md)**: Adds a theme selector dropdown that allows users to switch between multiple visual themes including 80s Retro, Terminal Classic, Hand-Sketched, Steampunk, and Fantasy Realm. Enhances user customization and visual appeal. + +- **[fun-add-dog-animation](./fun-add-dog-animation.md)**: Implements an interactive cartoon dog animation in the bottom-right corner of the website that follows the user's cursor with its eyes. The dog remains visible while scrolling and has extra animations on mouse clicks, adding a playful element to the user experience. + +### Backend Development + +- **[conversion-convert-flask-to-golang](./conversion-convert-flask-to-golang.md)**: Provides instructions for migrating the existing Python Flask server to a Go-based implementation while maintaining identical functionality, API endpoints, and response formats. The goal is to create a functionally equivalent server using Go's standard library. + +- **[monitoring-add-logging](./monitoring-add-logging.md)**: Details requirements for implementing a comprehensive logging system in the Python Flask server with multiple logging levels, consistent formatting, configuration options, and performance considerations. This improves monitoring, debugging, and operational visibility. diff --git a/content/prompts/add-feature-simple.md b/content/prompts/add-feature-simple.md new file mode 100644 index 0000000..3bfea8e --- /dev/null +++ b/content/prompts/add-feature-simple.md @@ -0,0 +1 @@ +Add to the dogs list a filter. Allow filtering by dog breed and adoption availability. The breed filter is a dropdown and the availability a check box. If the filter changes the page is automatically refreshed diff --git a/content/prompts/add-feature-verbose.md b/content/prompts/add-feature-verbose.md new file mode 100644 index 0000000..bb16321 --- /dev/null +++ b/content/prompts/add-feature-verbose.md @@ -0,0 +1,4 @@ +Add interactive filters to help users find their perfect furry companion on the dog list page: +- A breed selector dropdown populated with all available breeds +- An "Available for Adoption" checkbox to show only dogs ready for their forever homes +Make the list update automatically whenever a filter changes, so users see instant results. diff --git a/content/prompts/conversion-convert-flask-to-golang.md b/content/prompts/conversion-convert-flask-to-golang.md new file mode 100644 index 0000000..c8b3c9d --- /dev/null +++ b/content/prompts/conversion-convert-flask-to-golang.md @@ -0,0 +1,24 @@ +# Flask to Go Server Migration Project + +## Objective + +Convert the existing Python Flask server implementation to a Go-based server with identical functionality and API endpoints. The Go implementation should maintain the same request handling, routes, data processing, and response formats as the original Flask server. + +The Python Flask is stored in #folder:server + +## Requirements +1. Create a functionally equivalent Go server implementation +2. Match all existing API endpoints, query parameters, and HTTP methods +3. Preserve all current data processing logic and response formats +4. Implement the same error handling and status codes +5. Maintain any authentication mechanisms present in the Flask implementation +6. Use only the Go standard library where possible, with minimal external dependencies +7. Include appropriate comments explaining the code and any implementation decisions + +## Deliverables +1. Complete Go source code organized in a folder named `go_server` +2. A main.go file with server initialization and configuration +3. Separate handler files for different API endpoint groups +4. Any utility or helper functions required +5. A README.md with setup and usage instructions + diff --git a/content/prompts/fun-add-dog-animation.md b/content/prompts/fun-add-dog-animation.md new file mode 100644 index 0000000..43852a0 --- /dev/null +++ b/content/prompts/fun-add-dog-animation.md @@ -0,0 +1,13 @@ +# Puppy Cursor Follower + +Add an adorable cartoon dog to the bottom-right corner of the website that follows the user's cursor with its eyes, similar to the classic XEyes program from X11. + +## Requirements: +- The dog should be cute and cartoony with expressive eyes +- Eyes should smoothly track the cursor position across the entire screen +- Position the dog in the bottom-right corner as a fixed element (sticky positioning) +- Dog should remain visible even when the page is scrolled +- Add a slight head tilt or ear wiggle on mouse clicks for extra charm +- Optional: Make the dog occasionally blink or perform a random animation + +Let's make browsing fun again with this interactive canine companion! 🐶 \ No newline at end of file diff --git a/content/prompts/fun-add-themes.md b/content/prompts/fun-add-themes.md new file mode 100644 index 0000000..a0611b4 --- /dev/null +++ b/content/prompts/fun-add-themes.md @@ -0,0 +1,40 @@ +# 🎨 Theme-tastic Interface Enhancement! + +## 🎯 Your Mission +Transform our boring interface into a playground of visual delights! Let users express themselves through awesome themes. + +## 🔍 Key Requirements +1. **Theme Selector Dropdown** + - Position: ↗️ Top-right corner of the screen + - Behavior: Interface instantly refreshes when a new theme is selected + - Default label: "Default" (our current look) + +## 🌈 Required Themes +Add these fabulous theme options: + +* **80s Retro** 🕹️ + - Think neon colors, bold patterns, geometric shapes + - Inspiration: Miami Vice, arcade games, synthwave + +* **Terminal Classic** 💻 + - Nostalgic VT100 green-on-black terminal look + - Features: Monospace fonts, scan lines, command prompt aesthetic + +* **Hand-Sketched** ✏️ + - UI elements that appear hand-drawn with a playful, creative feel + - Think: Doodles, sketch lines, paper texture backgrounds + +* **Steampunk** ⚙️ + - Brass, gears, leather, and Victorian-era aesthetics mixed with futuristic elements + - Inspiration: Jules Verne, The League of Extraordinary Gentlemen, Bioshock Infinite + +* **Fantasy Realm** 🧙 + - Mystical forests, glowing runes, and enchanted elements + - Inspiration: Lord of the Rings, Dungeons & Dragons, Skyrim + + +## 🚀 Bonus Points +- Add subtle animations for theme transitions +- Include a small preview of each theme in the dropdown +- Make sure all themes maintain accessibility standards + diff --git a/content/prompts/monitoring-add-logging.md b/content/prompts/monitoring-add-logging.md new file mode 100644 index 0000000..75aaef1 --- /dev/null +++ b/content/prompts/monitoring-add-logging.md @@ -0,0 +1,30 @@ +Add logging commands to server application which is written in python + +The Python Flask is stored in #folder:server + +Create a standardized logging system for the Python Flask with the following requirements: + +1. LOGGING LEVELS: Implement five distinct logging levels (DEBUG, INFO, WARNING, ERROR, CRITICAL) with clear usage guidelines for each. + +2. FORMAT CONSISTENCY: Define a consistent log entry format including: + - Timestamp (ISO 8601 format: YYYY-MM-DD HH:MM:SS.mmm) + - Log level + - Module/component name + - Thread ID (where applicable) + - Message content + +3. CONFIGURATION: Provide a configuration system that allows: + - Setting global minimum log level + - Per-module logging levels + - Multiple output destinations (console, file, external service) + - Log rotation settings for file outputs + +4. CODE EXAMPLES: Include example implementations showing: + - Proper logger initialization + - Correct usage of each log level + - Error/exception logging with stack traces + - Context-enriched logging + +5. PERFORMANCE CONSIDERATIONS: Address how to optimize logging for production environments. + +The solution should be maintainable, follow industry best practices, and minimize performance impact.