Skip to content

Commit 06f152a

Browse files
slvvkoslvvko
committed
AG-51050 update docs due to sdd
Squashed commit of the following: commit cb94708 Merge: f5d55e5 5680d8d Author: slvvko <v.leleka@adguard.com> Date: Wed Mar 18 08:45:27 2026 -0400 Merge branch 'master' into fix/AG-51050 commit f5d55e5 Author: slvvko <v.leleka@adguard.com> Date: Tue Mar 17 19:14:12 2026 -0400 fix project structure section commit 4cb7fbe Merge: 248a796 9893ccb Author: slvvko <v.leleka@adguard.com> Date: Tue Mar 17 19:13:17 2026 -0400 Merge branch 'master' into fix/AG-51050 commit 248a796 Author: slvvko <v.leleka@adguard.com> Date: Mon Mar 16 21:50:08 2026 -0400 add DEVELOPMENT.md commit b1b3e44 Author: slvvko <v.leleka@adguard.com> Date: Mon Mar 16 21:50:00 2026 -0400 update AGENTS.md commit d72a504 Author: slvvko <v.leleka@adguard.com> Date: Mon Mar 16 21:48:53 2026 -0400 update gitignore
1 parent 5680d8d commit 06f152a

3 files changed

Lines changed: 207 additions & 0 deletions

File tree

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,3 +20,6 @@ dist/
2020

2121
.npmrc
2222
*.tgz
23+
24+
# SDD specs
25+
specs/.current/

‎AGENTS.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,7 @@ scriptlets/
6464
├── rollup.config.js # Rollup bundle configuration
6565
├── tsconfig.json # TypeScript configuration
6666
├── vitest.config.ts # Vitest configuration
67+
├── DEVELOPMENT.md # Development guide and SDD lifecycle
6768
└── package.json # Package manifest and scripts
6869
```
6970

@@ -164,6 +165,14 @@ You MUST follow the following rules for EVERY task that you perform:
164165

165166
- Use `pnpm` as the package manager. Do not use `npm` or `yarn`.
166167

168+
### Spec-Driven Development (SDD)
169+
170+
Non-trivial changes MUST be preceded by a spec created with the SDD slash
171+
commands, which should be available globally (preferred).
172+
173+
Specs are local-only and never committed — `specs/.current/` contents are
174+
gitignored.
175+
167176
## Code guidelines
168177

169178
### I. Architecture

‎DEVELOPMENT.md‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
# Development Guide
2+
3+
This guide covers setting up your development environment, building the
4+
library, running tests, and contributing code to the AdGuard Scriptlets and
5+
Redirect Resources library.
6+
7+
## Prerequisites
8+
9+
### Required Tools
10+
11+
| Tool | Version | Notes |
12+
| ---- | ------- | ----- |
13+
| [Node.js](https://nodejs.org/) | 22 | Use [nvm](https://github.com/nvm-sh/nvm) to manage versions |
14+
| [pnpm](https://pnpm.io/) | 10.7 | Package manager |
15+
| [Git](https://git-scm.com/) | Latest | Version control |
16+
17+
> **Note**: Development is tested on macOS and Linux. Windows users should use
18+
> WSL or a virtual machine.
19+
20+
## Getting Started
21+
22+
### 1. Clone the Repository
23+
24+
```bash
25+
git clone https://github.com/AdguardTeam/Scriptlets.git
26+
cd Scriptlets
27+
```
28+
29+
### 2. Install Dependencies
30+
31+
```bash
32+
pnpm install
33+
```
34+
35+
### 3. Build the Library
36+
37+
```bash
38+
pnpm build
39+
```
40+
41+
Build output goes to `dist/`.
42+
43+
### 4. Run Tests
44+
45+
```bash
46+
# All tests (Vitest + smoke + QUnit)
47+
pnpm test
48+
49+
# Vitest only (API, validators, converters)
50+
pnpm test:vitest
51+
52+
# QUnit only (scriptlets)
53+
pnpm test:qunit scriptlets
54+
55+
# QUnit only (redirects)
56+
pnpm test:qunit redirects
57+
58+
# Single scriptlet with rebuild
59+
pnpm test:qunit scriptlets --name <scriptlet-name> --build
60+
```
61+
62+
### 5. Run Linters
63+
64+
```bash
65+
# All linters
66+
pnpm lint
67+
68+
# Individual linters
69+
pnpm lint:code # ESLint
70+
pnpm lint:types # TypeScript type checking
71+
pnpm lint:md # markdownlint
72+
```
73+
74+
## Available Commands
75+
76+
| Command | Description |
77+
| ------- | ----------- |
78+
| `pnpm install` | Install dependencies |
79+
| `pnpm build` | Clean `dist/` and build all bundles |
80+
| `pnpm test` | Run all tests (Vitest + smoke + QUnit) |
81+
| `pnpm test:vitest` | Run Vitest tests only (API, validators, converters) |
82+
| `pnpm test:qunit scriptlets` | Run QUnit tests for all scriptlets |
83+
| `pnpm test:qunit redirects` | Run QUnit tests for all redirects |
84+
| `pnpm test:qunit helpers` | Run QUnit tests for helpers |
85+
| `pnpm test:qunit scriptlets --name <name> --build` | Run a single scriptlet test with rebuild |
86+
| `pnpm lint` | Run all linters |
87+
| `pnpm lint:code` | Run ESLint |
88+
| `pnpm lint:types` | Run TypeScript type checking (`tsc --noEmit`) |
89+
| `pnpm lint:md` | Run markdownlint |
90+
| `pnpm wiki:build-table` | Regenerate compatibility table |
91+
| `pnpm wiki:build-docs` | Regenerate scriptlet/redirect wiki docs from JSDoc |
92+
| `pnpm increment` | Bump patch version in `package.json` |
93+
94+
## Development Workflow
95+
96+
### Branching Strategy
97+
98+
1. Create a feature branch from `master`
99+
2. Make your changes
100+
3. Ensure all checks pass (see Before Committing below)
101+
4. Submit a pull request to `master`
102+
103+
### Before Committing
104+
105+
Run these checks before every commit:
106+
107+
```bash
108+
# Lint all (ESLint + TypeScript + markdownlint)
109+
pnpm lint
110+
111+
# Run the relevant test suite
112+
pnpm test:qunit scriptlets --name <name> --build # for scriptlet changes
113+
pnpm test:vitest # for API/converter/validator changes
114+
```
115+
116+
Both must pass with no errors.
117+
118+
## Spec-Driven Development (SDD)
119+
120+
All non-trivial changes must be guided by a spec authored **before**
121+
implementation begins. SDD slash commands should be available globally (preferred).
122+
123+
### When to Use Each Flow
124+
125+
| Change type | Flow |
126+
| ----------- | ---- |
127+
| New scriptlet or redirect resource | Full SDD |
128+
| API surface change | Full SDD |
129+
| Multi-component refactor | Full SDD |
130+
| Bug fix | Quick flow |
131+
| Small config or single-file change | Quick flow |
132+
133+
### Specs Directory Layout
134+
135+
All specs are stored in `specs/.current/` (local-only, contents are gitignored)
136+
and are never committed.
137+
138+
```text
139+
specs/
140+
├── .current/ # local only, gitignored contents
141+
├── ADG-1234-new-scriptlet/
142+
│ ├── spec.md
143+
│ └── plan.md
144+
└── ADG-5678-bugfix/
145+
└── quick.md
146+
```
147+
148+
## Common Tasks
149+
150+
### Adding a New Scriptlet
151+
152+
1. Run `/sdd-spec <scriptlet description>` then `/sdd-plan` to create the spec
153+
and plan.
154+
2. Create `src/scriptlets/<name>.ts` with a JSDoc `@scriptlet` header.
155+
3. Add a QUnit test file at `tests/scriptlets/<name>.test.js`.
156+
4. Update `scripts/compatibility-table.json` with the new entry.
157+
5. Run `pnpm test:qunit scriptlets --name <name> --build` to verify.
158+
6. Run `pnpm wiki:build-docs` to regenerate the wiki documentation.
159+
160+
### Adding a New Redirect Resource
161+
162+
1. Run `/sdd-spec <redirect description>` then `/sdd-plan`.
163+
2. Create the source file in `src/redirects/` and a YAML manifest alongside it.
164+
3. Add a QUnit test file at `tests/redirects/<name>.test.js`.
165+
4. Update `scripts/compatibility-table.json` with the new entry.
166+
5. Run `pnpm test:qunit redirects --build` to verify.
167+
6. Run `pnpm wiki:build-docs` to regenerate the wiki documentation.
168+
169+
### Updating Wiki Documentation
170+
171+
```bash
172+
# Regenerate compatibility table
173+
pnpm wiki:build-table
174+
175+
# Regenerate scriptlet/redirect docs from JSDoc
176+
pnpm wiki:build-docs
177+
```
178+
179+
> **Note**: Files in `wiki/` are auto-generated. Do **not** edit them manually.
180+
181+
### Bumping the Version
182+
183+
```bash
184+
pnpm increment
185+
```
186+
187+
This bumps the patch version in `package.json` without creating a git tag.
188+
Update `CHANGELOG.md` accordingly before publishing.
189+
190+
## Additional Resources
191+
192+
- [AGENTS.md](AGENTS.md) — AI agent instructions and code guidelines
193+
- [README.md](README.md) — Project overview and usage documentation
194+
- [CHANGELOG.md](CHANGELOG.md) — Version history
195+
- [AdGuard JavaScript Code Guidelines](https://github.com/AdguardTeam/CodeGuidelines/blob/master/JavaScript/Javascript.md)

0 commit comments

Comments
 (0)