GacUI/.github/copilot-instructions.md

General Instruction

• REPO-ROOT refers to the root directory of the repository.
• SOLUTION-ROOT refers to the root directory of a solution (*.sln or *.slnx).
• Solutions and projects you need to work on can be found in REPO-ROOT/Project.md.
• Following Leveraging the Knowledge Base, find the knowledge and documents for this project in REPO-ROOT/.github/KnowledgeBase/Index.md.
• Before writing to a source file, read it again and make sure you respect my parallel editing.
• If any *.prompt.md file is referenced, take immediate action following the instructions in that file.
• DO NOT ASK ANY QUESTION if you are not explicitly instructed to ask questions. Run the user's task to the end.
  • The only exception is when there is seriously conflicting information in the user's task. This is rare; try your best to resolve the ambiguity by yourself, and only ask when you are totally stuck.

Quality Control

• In these repos we are going to let exceptions blow any libraries, unit tests or test apps up without the needing to recover:
  • Unless explicitly instructed to do so.
  • Because crashing it is how we know there is something wrong.
• None of the test apps is going to be published, unnecessary error recovery will just cover mistakes up, preventing us from finding the root cause of the problem, making it harder to fix issues in libraries.
• Defensive cleanup should always be avoided when affected errors and exceptions crash the app. Since the app is going to be killed, cleaning up just make the code more complex and gain no benefit.
• Any REPO-ROOT/Tools/<TOOL-NAME> only allow very limited error recovery just to print error messages and exit.
• No heart beats or similar construction is needed, as all test apps are supposed to be running in the same computer, where the network quality is not an issue.

For Multi-Process Communication

• Unless explicitly instructed to do so:
  • Shutdown acknlowledgement is not required.
  • In a group of communicating processes, no recover is needed when any process is gone for any reason.
  • Crashing is welcome as it exposes the problem and makes it easier to debug and fix.
• In any test apps, all necessary error recovery will be defined in REPO-ROOT/Project.md. When not said, just let the app crash.

(Windows Specific) External Tools Environment and Context

• Always prefer the offered script files for building and running projects.
• DO NOT call msbuild directly.
• Run CDB directly following REPO-ROOT/.github/Guidelines/Debugging.md.
• DO NOT create or delete any file unless explicitly directed.
• MUST run any PowerShell script in this format: & absolute-path.ps1 parameters....
• Multiple PowerShell commands are concatenated with ; to be executed in one line.

(Linux Specific) External Tools Environment and Context

• DO NOT run any PowerShell script file as they are for Windows only.
• The bash script REPO-ROOT/.github/Ubuntu/build.sh is the only script you should call for building any project. build.sh will also run other script files in that folder; you may need to run chmod +x if any script file is blocked.
• build.sh is usable in REPO-ROOT/Test/Linux or REPO-ROOT/Test/Linux/PROJECT-NAME. It reads the local vmake configuration file, generates a makefile, and builds it.
  • Call build.sh -f for full rebuild.
  • Call build.sh for incremental build.
  • vmake, vmake.txt and makefile all live in the same Test/Linux (or Test/Linux/PROJECT-NAME) folder:
    • vmake is the configuration file derived from MSBuild project files. When the source file list changes, the MSBuild project files are expected to be modified, and build.sh will regenerate the rest.
    • vmake.txt and makefile are generated files, you are not allowed to modify them.
  • Unlike offered PowerShell scripts, build.sh does not produce Build.log or equivalent log file; running a unit test does not produce Execute.log or equivalent log file.
• Always use lldb and other interactive tools in a PTY-backed tool session.
• DO NOT call cmake, make, clang++, g++, gdb directly. build.sh and lldb are for building and debugging.

Coding Guidelines and Tools

The C++ project in this repo is built and tested using its own MSBuild wrappers. You must strictly follow the instructions in the following documents, otherwise it won't work properly.

• SUPER IMPORTANT Your should always follow the coding convention when coding:
  • REPO-ROOT/.github/Guidelines/Coding.md
  • REPO-ROOT/.github/Guidelines/Coding_MultiThreading.md
  • REPO-ROOT/.github/KnowledgeBase/Learning.md
  • REPO-ROOT/.github/Learning/Learning_Coding.md
  • REPO-ROOT/.github/Learning/Learning_Testing.md
• Adding/Removing/Renaming Source Files: REPO-ROOT/.github/Guidelines/SourceFileManagement.md
• Building a Solution: REPO-ROOT/.github/Guidelines/Building.md
• Running a Project:
  • Unit Test: REPO-ROOT/.github/Guidelines/Running-UnitTest.md
  • CLI Application: REPO-ROOT/.github/Guidelines/Running-CLI.md
  • GacUI Application: REPO-ROOT/.github/Guidelines/Running-GacUI.md
  • Basic Computer Use: REPO-ROOT/.github/Guidelines/Running-ComputerUse.md
    • This instruction is important for both Unit Test, CLI and GacUI applications.
    • MSVC compiled applications are inevitably (but not always) prompting a native dialog when crashed.
    • GacUI applications could invoke native dialogs proactivately, even when FakeDialogService is used.
    • This document describes how to handle native UI to unblock the debugging or testing process.
• Debugging a Project: REPO-ROOT/.github/Guidelines/Debugging.md
• Using Unit Test Framework: REPO-ROOT/.github/KnowledgeBase/manual/unittest/vlpp.md
• Using Unit Test Framework for GacUI Application:
  • Running GacUI in Unit Test Framework: REPO-ROOT/.github/KnowledgeBase/manual/unittest/gacui.md
  • Snapshots and Frames: REPO-ROOT/.github/KnowledgeBase/manual/unittest/gacui_frame.md
  • IO Interaction: REPO-ROOT/.github/KnowledgeBase/manual/unittest/gacui_io.md
  • Accessing: REPO-ROOT/.github/KnowledgeBase/manual/unittest/gacui_controls.md
  • Snapshot Viewer: REPO-ROOT/.github/KnowledgeBase/manual/unittest/gacui_snapshots.md
• Syntax of GacUI XML Resources:
  • Brief Introduction: REPO-ROOT/.github/Guidelines/GacUIXmlResource.md
  • Detailed document can be found in REPO-ROOT/.github/KnowledgeBase/Index.md under # Copy of Online Manual / ## GacUI, in the GacUI XML Resource item and all subitems.
• Syntax of Workflow Script (the script language in GacUI XML Resource):
  • Detailed document can be found in REPO-ROOT/.github/KnowledgeBase/Index.md under # Copy of Online Manual / ## Workflow Script, in the Syntax item and all subitems.

Accessing Task Documents

If you need to find any document for the current working task, they are in the REPO-ROOT/.github/TaskLogs folder:

• Copilot_Investigate.md
• Copilot_KB.md

Important Rules for Writing Markdown Files

• Do not print "" or "markdown" in a Markdown file.
• It is totally fine to have multiple top-level # Topic.
• When mentioning a C++ name in a Markdown file:
  • If it is defined in the standard C++ library or third-party library, use the full name.
  • If it is defined in the source code, use the full name if there is ambiguity, and then mention the file containing its definition.

(Windows Specific) Accessing Script Files

If you need to find any script or support files, they are in the REPO-ROOT/.github/Scripts folder:

• copilotBuild.ps1
• copilotExecute.ps1
• copilotRemember.ps1
• Build.log
• Execute.log

(Linux Specific) Accessing Script Files

If you need to find any script files, they are in the REPO-ROOT/.github/Ubuntu folder:

• build.sh

Leveraging the Knowledge Base

• When making design or coding decisions, you must leverage the knowledge base to make the best choice.
• The main entry is REPO-ROOT/.github/KnowledgeBase/Index.md, it is organized in this way:
  • ## Guidance: General guidance that plays an important role repo-wide.
  • Each ## Project: A brief description of each project and its purpose, plus a link to Index_<PROJECT>.md for project-specific guidance.
  • Each Index_<PROJECT>.md: Project-specific API and design guidance linked from the project section in Index.md.
    • ### Choosing APIs: Guidelines for selecting appropriate APIs for the project.
    • ### Design Explanation: Insights into the design decisions made within the project.
  • ## Experiences and Learnings: Reflections on the development process and key takeaways.
  • # Copy of Online Manual: A copy of the online manual so that you don't need network access. They are much more detailed, offering selectively important information.
    • Each ## Project: A copy of online manual for that project, organized in the same way as the knowledge base.
    • Not every project is included.
    • Manual for the unit test framework is in ## Unit Testing.

Index_.md/Choosing APIs

There are multiple categories under Choosing APIs. Each category begins with a short and accurate title #### Category. A category means a set of related things that you can do with APIs from this project.

Under the category, there is an overall and comprehensive description about what you can do.

Under the description, there are bullet points, and each item follows the format: - Use CLASS-NAME for blahblahblah (If a function does not belong to a class, you can generate Use FUNCTION-NAME ...). It mentions what to do, it does not mention how to do (as this part will be in API Explanation). If many classes or functions serve the same, or very similar purpose, one bullet point will mention them together.

At the end of the category, there is a hyperlink: [API Explanation](./KB_Project_Category.md) (no space between file name, all PascalCase).

Index_.md/Design Explanation

There are multiple topics under Design Explanation. Each topic begins with a short and accurate title #### Topic. A topic means a feature of this project; it can involve multiple components combined.

Under the topic, there is an overall and comprehensive description about what this feature does.

Under the description, there are bullet points to provide a little more detail, but do not make it too long. Full details are supposed to be in the document from the hyperlink.

At the end of the topic, there is a hyperlink: [Design Explanation](./KB_Project_Design_Topic.md) (no space between file name, all PascalCase).

Experiences and Learnings

(to edit ...)