Add workshop setup documentation and images

Author: GeekTrainer

content/.DS_Store

@@ -0,0 +1,47 @@
+# Workshop setup
+
+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](https://docs.github.com/en/get-started/quickstart/fork-a-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](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository). Template repositories are a great way to provide starters for your organization, ensuring consistency across projects.
+
+The repository for this workshop is configured as a template, so we can use it to create your repository.
+
+## Create your repository
+
+Let's create the repository you'll use for your workshop.
+
+1. Navigate to [the repository root](/)
+2. Select **Use this template** > **Create a new repository**
+
+    ![Screenshot of Use this template dropdown](images/0-setup-template.png)
+
+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**.
+
+    ![Screenshot of configured template creation dialog](images/0-setup-configure.png)
+
+In a few moments a new repository will be created from the template for this workshop!
+
+## Clone the repository and start the app
+
+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.
+
+1. Copy the URL for the repository you just created in the prior set.
+2. Open your shell.
+3. Run the following command to clone the repository locally (changing directories to a parent directory as appropriate):
+
+    ```sh
+    git clone <INSERT_REPO_URL_HERE>
+    ```
+
+4. Change directories into the cloned repository by running the following command:
+
+    ```sh
+    cd <REPO_NAME_HERE>
+    ```
+
+5. Start the application by running the following command:
+
+## Summary and next steps
+
+You've now created the repository you'll use for this workshop! Next let's [enable Code Scanning](1-code-scanning.md) to secure the code we write.

content/1-hour/0-setup.md

@@ -0,0 +1,105 @@
+# Helping GitHub Copilot understand context
+
+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
+
+Before adding new functionality to the website, you want to explore the existing structure to determine where the updates need to be made. You also want to provide Copilot some context in the form of [custom instructions](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot?tool=vscode) so it has a better idea of how best to generate code.
+
+## Getting started with GitHub Copilot
+
+GitHub Copilot is a cloud-based service offered for both individuals and businesses. As an individual, you can [sign up for a free account](https://github.com/github-copilot/signup) of the service. After enrolling you will typically install the extension for your IDE, which is available for [Visual Studio](https://marketplace.visualstudio.com/items?itemName=GitHub.copilotvs), [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot), [NeoVIM](https://github.com/github/copilot.vim#getting-started) and the [JetBrains IDEs](https://plugins.jetbrains.com/plugin/17718-github-copilot).
+
+1. If you don't already have access to GitHub Copilot, [sign up for a free trial](https://github.com/github-copilot/signup).
+2. [Install the extension](https://docs.github.com/en/copilot/managing-copilot/configure-personal-settings/installing-the-github-copilot-extension-in-your-environment) in your IDE.
+
+## Chat participants and extensions
+
+GitHub Copilot Chat has a set of available chat participants and 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.
+
+> [!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. Open the repository in your IDE.
+2. Open GitHub Copilot Chat.
+3. Select the `+` icon towards the top to begin a new chat.
+4. Type `@workspace` in the chat prompt window and hit <kbd>tab</kbd> 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.
+5. Spend a few minutes exploring to find the answers to the following questions:
+    - What frameworks are currently in use?
+    - Where's the database the project uses?
+    - How is the frontend built?
+    - How is the backend built?
+    - What files are involved in listing dogs?
+
+## Providing custom instructions
+
+Context is key to ensuring the code suggestions you receive from GitHub Copilot align with your expectations. When operating with limited information, Copilot makes assumptions about what you're looking for, and can sometimes guess incorrectly. By providing context, you allow Copilot to better align with your objectives. One great way to do this is by building a [copilot-instructions.md](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot?tool=vscode) file. This markdown file is placed in your **.github** folder and becomes part of your project. 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 set of Copilot instructions 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) as needed.
+
+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:
+    - 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:
+        - Python code should always follow PEP8 rules.
+        - use arrow functions rather than the `function` keyword.
+- If you notice GitHub Copilot consistently provides an unexpected suggestion (e.g. using class components for React), add those notes to the instructions file.
+
+Let's create a Copilot instructions file. Just as before, because we want you to explore and experiment, we won't provide exact directions on what to type, but will give enough context to create one on your own.
+
+1. Create a new file in the **.github** folder called **copilot-instructions.md**.
+2. Add the markdown to the file necessary to provide information about the project structure and requirements, including:
+    - an overview of the project itself (based on the information you gathered earlier in this exercise).
+    - the languages and frameworks in use to create both the server and client.
+    - unit tests are required for routes in the Flask app, and must mock the database calls.
+    - the website should be in dark mode and have a modern look and feel.
+3. Save the file!
+
+Your Copilot instructions file could resemble the following (but again - use your own words and style!):
+
+```markdown
+# Dog shelter
+
+This is an application to allow people to look for dogs to adopt. It is built in a monorepo, with a Flask-based backend and Astro-based frontend.
+
+## Backend
+
+- Built using Flask and SQLAlchemy
+- All routes require unit tests, which are created in *test_file.py* in the same folder as the file
+- When creating tests, always mock database calls
+
+## Frontend
+
+- Built using Astro and Svelte
+- Pages should be in dark mode with a modern look and feel
+```
+
+## Watch the instructions file in action
+
+Whenever you make a call to Copilot chat, the response will always include the context being used. The context can automatically include the open file (focused on any code you highlight), and individual files or folders you add by using `#file` or `#folder`. You can also include the an index of your workspace by using `@workspace`, as highlighted earlier. The references dialog is a great way to check what information Copilot was using when generating its suggestions and response. Once you create a Copilot instructions file, you will see it's always included in the references section.
+
+1. Close all files currently open in VS Code or your Codespace.
+2. Select the `+` icon in GitHub Copilot chat to start a new chat.
+3. Ask Copilot chat **What are the guidelines for the flask app?**
+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/5-copilot-chat-references.png)
+
+## Summary and next steps
+
+Congratulations! 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 create a Copilot instructions file to provide an overview of what you're building and how you're building it. With this in place, it's time to turn our attention to [adding new functionality to our website](./2-code.md)!
+
+## Resources
+
+- [Getting started with GitHub Copilot](https://docs.github.com/en/copilot/getting-started-with-github-copilot)
+- [Adding repository custom instructions for GitHub Copilot](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot)
+- [Adding personal custom instructions for GitHub Copilot](https://docs.github.com/en/copilot/customizing-copilot/adding-personal-custom-instructions-for-github-copilot)
+- [Copilot Chat cookbook](https://docs.github.com/en/copilot/copilot-chat-cookbook)
+- [Use Copilot Chat in VS Code](https://code.visualstudio.com/docs/copilot/copilot-chat)

content/1-hour/1-context.md

@@ -0,0 +1,102 @@
+# Coding with GitHub Copilot
+
+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 and generate the necessary unit tests.
+
+## 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.
+
+## Overview of this exercise
+
+In the next handful of steps, you will:
+
+- create a new Flask endpoint to list the breeds available.
+- add the associated unit test.
+- update the backend and frontend to display the list and add the filters as required in the scenario.
+
+## GitHub Copilot interfaces
+
+Until now, we've primarily focused on GitHub Copilot chat. This will likely be the most common way you'll interact with GitHub Copilot. It allows you to interactively ask questions, and has an ability to perform operations across an individual and (with Copilot Edits) multiple files. You can also get support from GitHub Copilot with code completion, which provides suggestions as you code. We're going to explore each of these three capabilities.
+
+## Create a new Flask route with Code completion
+
+Code completion predicts the next block of code you're about to type based on the context Copilot has. For code completion, this includes the file you're currently working on and any tabs open in your IDE.
+
+> [!IMPORTANT]
+> At this time, the Copilot instructions file is only available to Copilot chat.
+
+Code completion is best for situations where you know what you want to do, and are more than happy to just start writing code with a bit of a helping hand along the way. Suggestions will be generated based both on the code you write (say a function definition) and comments you add to your code.
+
+> [!NOTE]
+> One great way to provide context for GitHub Copilot is to add comments to your code. While comments describing what is done can sometimes be superfluous, it helps Copilot get a better idea of what you're building.
+
+Let's build our new route in our Flask backend with the help of code completion.
+
+1. Return to your codespace, or reopen it by navigating to your repository and selecting **Code** > **Codespaces** and the name of your codespace.
+2. Open **server/app.py**.
+3. Locate the section of code at the very bottom which launches the server, and put your cursor just above it. This should be line 70, and the code will be:
+
+    ```python
+    if __name__ == '__main__':
+      app.run(debug=True, port=5100) # Port 5100 to avoid macOS conflicts
+    ```
+
+4. Create the route which will call the database to find all breeds, and returns a JSON array with their names and IDs. If you begin typing `@app.route` or add a comment with the requirements like `# Route to get all breeds`, you should notice italicized text generated by GitHub Copilot.
+5. Select <kbd>Tab</kbd> to accept the code suggestion.
+6. Navigate to [http://localhost:5100/api/breeds](http://localhost:5100/api/breeds) to validate the route.
+
+> [!NOTE]
+> As with the prior exercise, we don't provide specific prompts to use with Copilot, as part of the learning experience is to discover how to interact with Copilot. If you are unfamiliar with Flask or how to add routes, you can look at the routes defined above for inspiration, or ask Copilot chat for guidance!
+
+## Generate the unit tests
+
+With the route created, we want to now add the tests to ensure the code is correct. We can use GitHub Copilot chat's slash command **/tests** to create the test for us!
+
+1. Return to your Codespace or VS Code.
+2. Highlight the code you generated in the prior step.
+3. Open GitHub Copilot chat.
+4. Select the `+` button to start a new chat.
+5. Type **/tests** and select <kbd>tab</kbd> to activate the command, then press <kbd>enter</kbd> to run the command. GitHub Copilot will generate the tests!
+6. Select the **Apply edits** button just above the generated code suggestion to apply the changes to **test_app.py**.
+7. Review and validate the code, making any necessary changes. Select **Keep** once you're satisfied.
+    > [!IMPORTANT]
+    > GitHub Copilot, like any generative AI solution, can make mistakes. Always review the generated code, making any necessary changes to ensure it's accurate and performs as expected.
+8. Open a terminal window in your codespace or VS Code by selecting <kbd>Ctl</kbd>+<kbd>Shift</kbd>+<kbd>`</kbd>
+9. Ensure the virtual server is activated by running the terminal command `source ./venv/bin/activate`
+10. Navigate to the **server** folder by running the terminal command `cd server`
+11. Run the tests by running the terminal command `python -m unittest`
+12. Ensure all tests pass!
+
+## Add the filters
+
+Adding the filters to the page will require updating a minimum of three files - the Flask backend, the unit tests for our Flask backend, and the Svelte frontend. Fortunately, Copilot Edits can update multiple files! Let's get our page updated with the help of Copilot Edits.
+
+1. Open the following files in your IDE (which we'll point Copilot chat to for context):
+   - **server/app.py**
+   - **server/test_app.py**
+   - **client/src/components/DogList.svelte** 
+2. Select **Copilot Edits** in the Copilot Chat window.
+3. Ensure **Claude 3.7 Sonnet** is selected for the model.
+4. Select **Add Context...** in the chat window and **Open Editors** from the prompt. This will add all currently open files to the context.
+5. Ask Copilot to perform the operation you want, to update the page to add the filters. It should meet the following requirements:
+    - 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
+    - Tests should be updated for any changes to the endpoint.
+6. 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.
+7. Open the page at [http://localhost:4321](http://localhost:4321) to see the updates!
+8. Run the Python tests by using `python -m unittest` in the terminal as you did previously.
+9. 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.
+
+## Summary and next steps
+
+Congratulations! You've worked with GitHub Copilot to add new features to the website - the ability to filter the list of dogs. Let's close out by [creating a pull request with our new functionality](./7-github-flow.md)!
+
+## Resources
+
+- [Asking GitHub Copilot questions in your IDE](https://docs.github.com/en/copilot/using-github-copilot/copilot-chat/asking-github-copilot-questions-in-your-ide)
+- [Copilot Edits](https://code.visualstudio.com/docs/copilot/copilot-edits)
+- [Copilot Chat cookbook](https://docs.github.com/en/copilot/copilot-chat-cookbook)