CONTRIBUTING.md

1 files changed, 79 insertions, 0 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 000000000..af3c30be7
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,79 @@
+# Ghostty Development Process
+
+This document describes the development process for Ghostty. It is intended for
+anyone considering opening an **issue** or **pull request**. If in doubt,
+please open a [discussion](https://github.com/ghostty-org/ghostty/discussions);
+we can always convert that to an issue later.
+
+> [!NOTE]
+>
+> I'm sorry for the wall of text. I'm not trying to be difficult and I do
+> appreciate your contributions. Ghostty is a personal project for me that
+> I maintain in my free time. If you're expecting me to dedicate my personal
+> time to fixing bugs, maintaining features, and reviewing code, I do kindly
+> ask you spend a few minutes reading this document. Thank you. ❤️
+
+## Quick Guide
+
+**I'd like to contribute!**
+
+All issues are actionable. Pick one and start working on it. Thank you.
+If you need help or guidance, comment on the issue. Issues that are extra
+friendly to new contributors are tagged with "contributor friendly".
+
+**I have a bug!**
+
+1. Search the issue tracker and discussions for similar issues.
+2. If you don't have steps to reproduce, open a discussion.
+3. If you have steps to reproduce, open an issue.
+
+**I have an idea for a feature!**
+
+1. Open a discussion.
+
+**I've implemented a feature!**
+
+1. If there is an issue for the feature, open a pull request.
+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.
+
+**I have a question!**
+
+1. Open a discussion or use Discord.
+
+## General Patterns
+
+### Issues are Actionable
+
+The Ghostty [issue tracker](https://github.com/ghostty-org/ghostty/issues)
+is for _actionable items_.
+
+Unlike some other projects, Ghostty **does not use the issue tracker for
+discussion or feature requests**. Instead, we use GitHub
+[discussions](https://github.com/ghostty-org/ghostty/discussions) for that.
+Once a discussion reaches a point where a well-understood, actionable
+item is identified, it is moved to the issue tracker. **This pattern
+makes it easier for maintainers or contributors to find issues to work on
+since _every issue_ is ready to be worked on.**
+
+If you are experiencing a bug and have clear steps to reproduce it, please
+open an issue. If you are experiencing a bug but you are not sure how to
+reproduce it or aren't sure if it's a bug, please open a discussion.
+If you have an idea for a feature, please open a discussion.
+
+### Pull Requests Implement an Issue
+
+Pull requests should be associated with a previously accepted issue.
+**If you open a pull request for something that wasn't previously discussed,**
+it may be closed or remain stale for an indefinite period of time. I'm not
+saying it will never be accepted, but the odds are stacked against you.
+
+Issues tagged with "feature" represent accepted, well-scoped feature requests.
+If you implement an issue tagged with feature as described in the issue, your
+pull request will be accepted with a high degree of certainty.
+
+> [!NOTE]
+>
+> **Pull requests are NOT a place to discuss feature design.** Please do
+> not open a WIP pull request to discuss a feature. Instead, use a discussion
+> and link to your branch.