diff --git a/.agents/commands/gh-issue b/.agents/commands/gh-issue new file mode 100755 index 000000000..de2f37335 --- /dev/null +++ b/.agents/commands/gh-issue @@ -0,0 +1,64 @@ +#!/usr/bin/env nu + +# A command to generate an agent prompt to diagnose and formulate +# a plan for resolving a GitHub issue. +# +# IMPORTANT: This command is prompted to NOT write any code and to ONLY +# produce a plan. You should still be vigilant when running this but that +# is the expected behavior. +# +# The `` parameter can be either an issue number or a full GitHub +# issue URL. +def main [ + issue: any, # Ghostty issue number or URL + --repo: string = "ghostty-org/ghostty" # GitHub repository in the format "owner/repo" +] { + # TODO: This whole script doesn't handle errors very well. I actually + # don't know Nu well enough to know the proper way to handle it all. + + let issueData = gh issue view $issue --json author,title,number,body,comments | from json + let comments = $issueData.comments | each { |comment| + $" +### Comment by ($comment.author.login) +($comment.body) +" | str trim + } | str join "\n\n" + + $" +Deep-dive on this GitHub issue. Find the problem and generate a plan. +Do not write code. Explain the problem clearly and propose a comprehensive plan +to solve it. + +# ($issueData.title) \(($issueData.number)\) + +## Description +($issueData.body) + +## Comments +($comments) + +## Your Tasks + +You are an experienced software developer tasked with diagnosing issues. + +1. Review the issue context and details. +2. Examine the relevant parts of the codebase. Analyze the code thoroughly + until you have a solid understanding of how it works. +3. Explain the issue in detail, including the problem and its root cause. +4. Create a comprehensive plan to solve the issue. The plan should include: + - Required code changes + - Potential impacts on other parts of the system + - Necessary tests to be written or updated + - Documentation updates + - Performance considerations + - Security implications + - Backwards compatibility \(if applicable\) + - Include the reference link to the source issue and any related discussions +4. Think deeply about all aspects of the task. Consider edge cases, potential + challenges, and best practices for addressing the issue. Review the plan + with the oracle and adjust it based on its feedback. + +**ONLY CREATE A PLAN. DO NOT WRITE ANY CODE.** Your task is to create +a thorough, comprehensive strategy for understanding and resolving the issue. +" | str trim +} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 777771145..de7df4b71 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -45,11 +45,16 @@ work than any human. That isn't the world we live in today, and in most cases it's generating slop. I say this despite being a fan of and using them successfully myself (with heavy supervision)! +When using AI assistance, we expect contributors to understand the code +that is produced and be able to answer critical questions about it. It +isn't a maintainers job to review a PR so broken that it requires +significant rework to be acceptable. + Please be respectful to maintainers and disclose AI assistance. ## Quick Guide -### I'd like to contribute! +### I'd like to contribute [All issues are actionable](#issues-are-actionable). Pick one and start working on it. Thank you. If you need help or guidance, comment on the issue. @@ -58,7 +63,7 @@ Issues that are extra friendly to new contributors are tagged with ["contributor friendly"]: https://github.com/ghostty-org/ghostty/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22contributor%20friendly%22 -### I'd like to translate Ghostty to my language! +### I'd like to translate Ghostty to my language We have written a [Translator's Guide](po/README_TRANSLATORS.md) for everyone interested in contributing translations to Ghostty. @@ -67,7 +72,7 @@ and you can submit pull requests directly, although please make sure that our [Style Guide](po/README_TRANSLATORS.md#style-guide) is followed before submission. -### I have a bug! / Something isn't working! +### I have a bug! / Something isn't working 1. Search the issue tracker and discussions for similar issues. Tip: also search for [closed issues] and [discussions] — your issue might have already @@ -82,18 +87,18 @@ submission. [discussions]: https://github.com/ghostty-org/ghostty/discussions?discussions_q=is%3Aclosed ["Issue Triage" discussion]: https://github.com/ghostty-org/ghostty/discussions/new?category=issue-triage -### I have an idea for a feature! +### I have an idea for a feature Open a discussion in the ["Feature Requests, Ideas" category](https://github.com/ghostty-org/ghostty/discussions/new?category=feature-requests-ideas). -### I've implemented a feature! +### I've implemented a feature 1. If there is an issue for the feature, open a pull request straight away. 2. If there is no issue, open a discussion and link to your branch. 3. If you want to live dangerously, open a pull request and [hope for the best](#pull-requests-implement-an-issue). -### I have a question! +### I have a question Open an [Q&A discussion], or join our [Discord Server] and ask away in the `#help` channel. diff --git a/HACKING.md b/HACKING.md index d79d15a4a..2d3640fca 100644 --- a/HACKING.md +++ b/HACKING.md @@ -36,7 +36,7 @@ here: | `zig build test` | Runs unit tests (accepts `-Dtest-filter=` to only run tests whose name matches the filter) | | `zig build update-translations` | Updates Ghostty's translation strings (see the [Contributor's Guide on Localizing Ghostty](po/README_CONTRIBUTORS.md)) | | `zig build dist` | Builds a source tarball | -| `zig build distcheck` | Installs and validates a source tarball | +| `zig build distcheck` | Builds and validates a source tarball | ## Extra Dependencies @@ -69,6 +69,32 @@ sudo xcode-select --switch /Applications/Xcode-beta.app > You do not need to be running on macOS 26 to build Ghostty, you can > still use Xcode 26 beta on macOS 15 stable. +## AI and Agents + +If you're using AI assistance with Ghostty, Ghostty provides an +[AGENTS.md file](https://github.com/ghostty-org/ghostty/blob/main/AGENTS.md) +read by most of the popular AI agents to help produce higher quality +results. + +We also provide commands in `.agents/commands` that have some vetted +prompts for common tasks that have been shown to produce good results. +We provide these to help reduce the amount of time a contributor has to +spend prompting the AI to get good results, and hopefully to lower the slop +produced. + +- `/gh-issue ` - Produces a prompt for diagnosing a GitHub + issue, explaining the problem, and suggesting a plan for resolving it. + Requires `gh` to be installed with read-only access to Ghostty. + +> [!WARNING] +> +> All AI assistance usage [must be disclosed](https://github.com/ghostty-org/ghostty/blob/main/CONTRIBUTING.md#ai-assistance-notice) +> and we expect contributors to understand the code that is produced and +> be able to answer questions about it. If you don't understand the +> code produced, feel free to disclose that, but if it has problems, we +> may ask you to fix it and close the issue. It isn't a maintainers job to +> review a PR so broken that it requires significant rework to be acceptable. + ## Linting ### Prettier diff --git a/nix/devShell.nix b/nix/devShell.nix index 7b78539f7..a54e199c2 100644 --- a/nix/devShell.nix +++ b/nix/devShell.nix @@ -3,6 +3,7 @@ lib, stdenv, bashInteractive, + nushell, appstream, flatpak-builder, gdb, @@ -124,6 +125,9 @@ in # CI uv + # Scripting + nushell + # We need these GTK-related deps on all platform so we can build # dist tarballs. blueprint-compiler