README.md

@@ -1,3 +1,37 @@
 # pull-request-lint
 
-Lints the title of a pull request
+A GitHub/Gitea Action that lints pull request titles to ensure they follow the [Conventional Commits](https://www.conventionalcommits.org/) format.
+
+## Usage
+
+Add the following to your GitHub/Gitea workflow:
+
+```yaml
+name: Pull Request Lint
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: your-org/pull-request-lint@main
+```
+
+## Validation Rules
+
+The action enforces the following Conventional Commits rules for PR titles:
+
+- Format must be: `type(scope)!: description` (scope and breaking change marker `!` are optional)
+- Type and scope must be lowercase
+- Description must start with lowercase
+- Breaking change indicator and footer are mutually exclusive
+- Body must be separated from description by a blank line
+- Footer tokens must use hyphens instead of spaces (except for "BREAKING CHANGE")
+
+## License
+
+See [LICENSE](LICENSE) file for details.