Skip to content

Commit bdefdba

Browse files
authored
Add AGENTS guidelines (#1179)
1 parent cb0ed6e commit bdefdba

File tree

1 file changed

+64
-0
lines changed

1 file changed

+64
-0
lines changed

AGENTS.md

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Contributor Guide
2+
3+
This repository hosts the **docusaurus-plugin-openapi-docs** and **docusaurus-theme-openapi-docs** packages. The plugin converts OpenAPI specs to MDX and the theme provides React components for rendering those docs. The `demo` directory shows them working together.
4+
5+
```
6+
root
7+
├─ packages
8+
│ ├─ docusaurus-plugin-openapi-docs # generates MDX from OpenAPI specs
9+
│ └─ docusaurus-theme-openapi-docs # theme components for API docs
10+
├─ demo # example site using the plugin and theme
11+
└─ scripts # release and helper scripts
12+
```
13+
14+
The plugin and theme are typically used together:
15+
16+
```
17+
OpenAPI spec ──▶ plugin ──▶ generated MDX ──▶ docs plugin ──▶ theme ──▶ website
18+
```
19+
20+
## Developer Quick Start
21+
22+
Steps from the top-level `README.md` for getting started:
23+
24+
```bash
25+
git clone https://github.com/<your account>/docusaurus-openapi-docs.git
26+
cd docusaurus-openapi-docs
27+
yarn
28+
yarn build-packages
29+
yarn watch:demo
30+
```
31+
32+
## Contributing Tips
33+
34+
See `CONTRIBUTING.md` for the full guide. Use clear commit messages so reviewers can understand what each commit does.
35+
36+
## Required Checks
37+
38+
Run the following before committing any code changes (except documentation or comment-only updates):
39+
40+
```bash
41+
yarn lint
42+
yarn test
43+
```
44+
45+
## Other Common Tasks
46+
47+
- `yarn` – install dependencies
48+
- `yarn build-packages` – compile all packages
49+
50+
## Publish a New Release
51+
52+
1. **Bump the version** (use semantic versioning):
53+
```bash
54+
yarn release:version <patch|minor|major>
55+
```
56+
2. **Update `CHANGELOG.md`** by running:
57+
```bash
58+
yarn release:changelog
59+
```
60+
Copy the output to the top of `CHANGELOG.md` with the current date. Update the "High level enhancements" section and clean up the history for public release.
61+
3. **Cleanup documentation** in `README.md`, `packages/docusaurus-plugin-openapi-docs/README.md` and `demo/docs/intro.mdx`.
62+
4. **Commit** all changes with the message `Prepare release vX.Y.Z`.
63+
64+
Once merged, the `release.yaml` workflow will publish the release automatically.

0 commit comments

Comments
 (0)